{"id":13800162,"url":"https://github.com/P1sec/MCC_MNC","last_synced_at":"2025-05-13T09:31:28.994Z","repository":{"id":136503575,"uuid":"245994912","full_name":"P1sec/MCC_MNC","owner":"P1sec","description":"Providing accurate JSON and Python dicts about the many public information available about MNO","archived":false,"fork":false,"pushed_at":"2024-07-01T10:36:33.000Z","size":87493,"stargazers_count":69,"open_issues_count":0,"forks_count":18,"subscribers_count":20,"default_branch":"master","last_synced_at":"2024-11-18T15:51:08.466Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/P1sec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-09T09:35:01.000Z","updated_at":"2024-11-12T08:51:22.000Z","dependencies_parsed_at":"2024-11-18T15:52:27.670Z","dependency_job_id":null,"html_url":"https://github.com/P1sec/MCC_MNC","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P1sec%2FMCC_MNC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P1sec%2FMCC_MNC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P1sec%2FMCC_MNC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P1sec%2FMCC_MNC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/P1sec","download_url":"https://codeload.github.com/P1sec/MCC_MNC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253913071,"owners_count":21983249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T00:01:10.004Z","updated_at":"2025-05-13T09:31:23.970Z","avatar_url":"https://github.com/P1sec.png","language":"Python","funding_links":[],"categories":["Protocols","Tools"],"sub_categories":["Others","Diameter"],"readme":"# MCC_MNC\n\nScrap available information on the Internet related to:\n- mobile network operators (such as MCC, MNC, brand, network type, countries of operation...)\n- countries (such as country name, 2 and 3-chars ISO codes, tld, boundaries and neighbours...)\n- international dialplan (such as MSISDN prefix and associated countries, signaling point codes...)\n\nUsing public data from the the following websites:\n- Wikipedia\n- ITU-T\n- The CIA World Factbook\n- txtNation\n- Ewen Gallic blog\n\nAll raw content extracted is available in *raw/* as JSON and Python dictionnaries.\nThis project aggregates and generates re-engineered dictionnaries from all those sources.\nAll re-engineered content is available in *mcc_mnc_lut/*, as JSON and Python dictionnaries too.\n\nFinally, it provides additionally command-line tools to request those dictionnaries:\n- `chk_cntr.py`: to get information related to a country\n- `chk_mnc.py`: to get information related to an Mobile Country Code - Mobile Network Code\n- `chk_msisdn.py`: to get information related to a phone prefix\n- `chk_ispc.py`: to get information related to an international Signaling Point Code\n- `conv_pc_383.py`: to convert signaling point code in different formatting\n\n\n## License\n\nThe code from this repository that is used to generate the dataset, and the command-line tools, is licensed under the terms of the AGPLv3.\nThe data downloaded from Wikipedia is licensed under the terms of the Creative Commons Attribution-ShareAlike license.\nThe 4 other websites used as source do not indicate any specific licensing for the data provided however, we provide an explicit indication \nof the data sources used in each JSON and Python dictionnary.\n\n\n## Data sources\n\nSeveral sources are available on the Internet to learn on the countries' geopraphy, and international mobile and telephony identifiers:\n\n\n### For country codes:\n\n- ISO website:\n  - https://www.iso.org/obp/ui/#search\n  - https://www.iso.org/obp/ui/#iso:pub:PUB500001:en\n- Wikipedia:\n  - https://en.wikipedia.org/wiki/Mobile_country_code\n\n\n### For MNO-related information:\n\n- ITU-T documents:\n  - List of MCC: https://www.itu.int/pub/T-SP-E.212A\n  - List of MNC: https://www.itu.int/pub/T-SP-E.212B\n  - Operational bulletins: https://www.itu.int/pub/T-SP-OB\n- Wikipedia:\n  - List of MCC: https://en.wikipedia.org/wiki/Mobile_country_code\n  - List of MNC: international networks listed in the MCC page, and 6 pages linked from there, one per world region\n- Other websites:\n  - https://www.mcc-mnc.com/ (contains several errors, e.g. related to country codes)\n  - https://clients.txtnation.com/hc/en-us/articles/218719768-MCCMNC-mobile-country-code-and-mobile-network-code-list (csv file)\n  - https://clients.txtnation.com/hc/en-us/articles/218719468-Operator-Details-Operator-Network-CC-MCC-MNC (xls file)\n  - https://cellidfinder.com/mcc-mnc\n  - https://docs.routee.net/docs/list-of-mccmnc-codes\n\n\n### For MSISDN numbering prefixes:\n\n- ITU-T documents:\n  - https://www.itu.int/pub/T-SP-E.164D\n  - Per-country numbering plan: https://www.itu.int/oth/T0202.aspx?parent=T0202\n- Wikipedia:\n  - https://en.wikipedia.org/wiki/List_of_country_calling_codes\n  - https://en.wikipedia.org/wiki/List_of_mobile_telephone_prefixes_by_country#International_prefixes_table\n  - https://en.wikipedia.org/wiki/International_Networks_(country_code) (for international networks)\n- Other websites:\n  - https://github.com/google/libphonenumber/tree/master/resources/geocoding/en\n  - https://phonenum.info/en/country-code/\n\n\n### For geographical countries and borders:\n\nMobile networks and other sorts of telephony networks being regulated nationally, it is important for analysts to have\naccurate information related to borders and proximity between countries. This helps to evaluate e.g., the feasibility of\ncertain mobility events for mobile subscribers.\n\n- Wikipedia:\n  - https://en.wikipedia.org/wiki/List_of_countries_and_territories_by_land_borders\n- Other websites:\n  - https://www.cia.gov/the-world-factbook/countries/\n  - http://www.naturalearthdata.com/downloads/10m-cultural-vectors/ (open US-based initiative, see admin 0 data)\n  - https://github.com/nvkelso/natural-earth-vector (vectorized data from naturalearthdata)\n  - https://developers.google.com/maps/documentation/javascript/geocoding (Google maps API)\n  - https://pypi.org/project/leafmap/ (Python notebook based project for geography and maps)\n\nThe CIA World Factbook looks more complete and less prone to periodic changes than Wikipedia when coming to geography and borders' referencement.\n\nSpecifically for the minimum distance between countries, here are valuable sources:\n- https://egallic.fr/en/closest-distance-between-countries/\n  - with updated R code and computed values:\n    https://gist.github.com/mtriff/185e15be85b44547ed110e412a1771bf/\n- https://zenodo.org/record/46822 for sea-distances only\n  - with related information provided here:\n    https://halshs.archives-ouvertes.fr/halshs-01288748/document\n\nSome other sources may be found online; additionally, it seems the R programming language has nice geography-related packages.\n\n\n## The case of international signaling point codes\n\nITU-T seems to be the only entity to maintain the list of International Signalling Point Codes.\nPoint codes are addresses used by each routing equipment at the MTP3 / M3UA layer for fixed telephony and SS7 signalling.\nThat means ISPC correspond most often to STP used by telecom operators for international routing of SS7 signaling.\n\nThe geographical relation between ISCP prefixes (most significant bits), also called Signaling Area Network Codes (SANC),\nand countries are provided in the operational bulletin 1125 from 2017.\nAdditionally, the operational bulletin 1199 from 2020 provides the complete list of those ISPC at the time.\nThis is however evolving with differences provided from time to time in other operational bulletins.\n\n\n### Working with ITU-T operational bulletins\n\nITU-T is publishing bi-mensual bulletins (23 or 24 a year, depends...), containing\nall additions and modifications to numbering plans, MNC identifiers and other signaling-related\ninformation. Complete lists of MCC-MNC can be found in bulletin 1111 from 2016 and \nbulletin 1162 from 2018. Moreover, differentials can be provided into individual bulletin.\n\nThe script `parse_itut_bulletins.py` can be used to download all bulletins (starting from 1111\nor whatever numbering after) and convert them to text using the Linux command ```pdftotext```.\nAll resulting documents are available in the *itut/* directory.\n\nBulletins 1111 from 2016 and 1162 from 2018 contain a full list of declared MCC-MNC which is extracted.\nAdditionally, all MCC-MNC incremental updates from bulletins after the 1162 are also extracted.\nFinally, bulletin 1199 contains a full list of declared international signaling point codes which is extracted too.\nThe script put all resulting JSON and Python files into the *raw/* directory for further integration.\n\n\n### Which ones to use:\n\nAfter checking several sources, it seems Wikipedia has the most complete, up-to-date and accurate information.\nTherefore, the tool primarily uses it to build the JSON / Python dictionnaries.\nInformation related to MCC-MNC is completed with the csv listing from the txtNation website \nand the ITU-T operational bulletins 1162 and all following incremental updates.\nThe list of Signaling Point Codes is extracted from ITU-T bulletin 1199.\nGeographical information are taken from the CIA World Factbook to gather information related to each country,\nincluding borders and telephony-related.\nThis is completed with the data provided on the _egallic_ blogpost for getting countries' proximity in addition to neighbours one.\n\n\n## Directory structure\n\nAll command-line tools are available straight in the root directory of the project.\nData downloaded and extracted from Internet are put in the *raw/* directory, except \ndocument from the ITU-T which are downloaded as PDF and converted to text in the *itut/*\ndirectory.\nRe-engineered look-up tables put in the *mcc_mnc_gen/* directory.\n\n\n## Install and usage\n\n### Install\n\nThe provided scripts all require Python3.\nFor rebuilding / updating the source dataset (the files in the *raw/* subdirectory),\nthe following packages are required: `urllib`, `lxml` and `csv`.\nFor generating the aggregated dataset (the files in the *mcc_mnc_lut/* subdirectory),\nno specific packages are required.\n\nIf you want, you can run `python setup.py install` to install the *chk\\_\\*.py* scripts\ntogether with the look-up tables (in the `./mcc_mnc_lut/` subdirectory) in your system or user\nenvironment. The extraction and table generation scripts won't be installed however, \nand you will need to reinstall the package each time you update the tables.\n\nGenerally, installation is not required and every scripts can be run as-is.\n\n\n### Source dataset update\n\nThe Wikipedia, World Factbook and ITU-T bulletins source datasets can be updated with the\nfollowing scripts:\n\n```\n$ ./parse_wikipedia_tables.py --help\nusage: parse_wikipedia_tables.py [-h] [-j] [-p]\n\ndump Wikipedia ISO-3166 country codes, MCC and MNC tables into JSON or Python\nfile\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -j          produce JSON files (with suffix .json)\n  -p          produce Python files (with suffix .py)\n```\n\n```\n$ ./parse_worldfactbook_infos.py --help\nusage: parse_worldfactbook_infos.py [-h] [-j] [-p]\n\ndump country-related informations from the CIA World Factbook into JSON or\nPython file\n[...]\n```\n\n```\n$ ./parse_itut_bulletins.py --help\nusage: parse_itut_bulletins.py [-h] [-d] [-b B] [-j] [-p]\n\ndownload ITU-T operational bulletins, convert them to text, extract lists of MNC and SPC\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -d          download and convert from pdf to text all ITU-T bulletins (requires pdftotext)\n  -b B        ITU-T bulletin number to start with, default is 1111\n  -j          produce a JSON file listing all MNC and SPC (with suffix .json)\n  -p          produce a Python file listing all MNC and SPC (with suffix .py)\n```\n\nThe script extracting information from Wikipedia tables may fail sometimes, as the layout on\nWikipedia can be modified or adjusted. Nothing magic here, it's then require to patch the `parse_wikipedia_tables.py`\nscript to make it work again against the new Wikipedia layout.\n\nThe Egallic and txtNation data can be processed with the following script (it won't download anything \nfrom the Internet, as both CSV files are provided directly in the project and do not change anymore):\n\n```\n$ ./parse_various_csv.py --help\nusage: parse_various_csv.py [-h] [-j] [-p]\n\ndump csv files from the Egallic blog (distance between countries) and the\ntxtNation website (list of MCC-MNC)\n[...]\n```\n\n\n### Aggregated dataset generation\n\nIn order to load all those imported data with aligned and coherent values \n(e.g. country names, ISO codes and other information and numbering), the module\n*patch_dataset* can be used. It exports the Wikipedia, World Factbook, Egallic, \ntxtNation and ITU-T datasets, after applying few corrections and fixes on them:\n\n```\n\u003e\u003e\u003e from patch_dataset import *\n[...]\n\u003e\u003e\u003e WIKIP_ISO3166\n[...]\n```\n\nThe module *gen_dataset.py* then generates new JSON and Python dictionnaries based on \nthose re-engineered data and store them in new files prefixed with \"p1\":\n- MNC: dict of MCCMNC 5/6-digit-str, MNO(s) information\n- MCC: dict of MCC 3-digit-str, Operators-related information\n- MSISDN: dict of MSISDN prefixes, countries\n- MSISDNEXT: dict of MSISDN prefixes, countries and extra-territories\n- ISPC: dict of international signaling point codes, countries and operators\n- CC2: dict of alpha-2 code, country-related information\n- CNTR: dict of country, country-related information (similar to CC2)\n- TERR: dict of country or territory, borders and neighbour related information\n\n```\n$ ./gen_dataset.py\n[...]\n[+] mcc_mnc_lut/p1_mnc.json file generated\n[+] mcc_mnc_lut/p1_mnc.py file generated\n[+] mcc_mnc_lut/p1_mcc.json file generated\n[+] mcc_mnc_lut/p1_mcc.py file generated\n[+] mcc_mnc_lut/p1_msisdn.json file generated\n[+] mcc_mnc_lut/p1_msisdn.py file generated\n[+] mcc_mnc_lut/p1_msisdnext.json file generated\n[+] mcc_mnc_lut/p1_msisdnext.py file generated\n[+] mcc_mnc_lut/p1_ispc.json file generated\n[+] mcc_mnc_lut/p1_ispc.py file generated\n[+] mcc_mnc_lut/p1_sanc.json file generated\n[+] mcc_mnc_lut/p1_sanc.py file generated\n[+] mcc_mnc_lut/p1_cc2.json file generated\n[+] mcc_mnc_lut/p1_cc2.py file generated\n[+] mcc_mnc_lut/p1_cntr.json file generated\n[+] mcc_mnc_lut/p1_cntr.py file generated\n[+] mcc_mnc_lut/p1_terr.json file generated\n[+] mcc_mnc_lut/p1_terr.py file generated\n```\n\nThe following one-liner can be used to update the whole final dataset (without downloading new ITU-T bulletins):\n```\n$ ./parse_wikipedia_tables.py -j -p \u0026\u0026 ./parse_worldfactbook_infos.py -j -p \u0026\u0026 ./parse_various_csv.py -j -p \u0026\u0026 ./parse_itut_bulletins.py -j -p \u0026\u0026 ./gen_dataset.py\n```\n\n### Usage\n\nNow you can use those dictionnaries to get complete information for any MCC, MNC, MSISDN prefix, \nand related geographical information, directly in your application as much as you want\n(do not forget to comply with the licensing).\n\nFinally, 4 little command-line tools are provided to make direct use of the aggregated \ndatasets straight from the CLI:\n\n```\n$ ./chk_mnc.py --help\nusage: chk_mnc.py [-h] [-x] [MCCMNC [MCCMNC ...]]\n\nprovides information related to mobile operator(s); if no argument is passed,\nlists all known MCC-MNC\n\npositional arguments:\n  MCCMNC      0 or more 5/6-digit string for MCC-MNC\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -x          provides extended information for MNO(s)\n\n\n$ ./chk_msisdn.py --help\nusage: chk_msisdn.py [-h] [-x] [MSISDN [MSISDN ...]]\n\nprovides information related to international telephone prefix; if no argument\nis passed, lists all known MSISDN prefixes\n\npositional arguments:\n  MSISDN      0 or more digit string for MSISDN\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -x          provides extended country-related information\n\n\n$ ./chk_cntr.py --help\nusage: chk_cntr.py [-h] [-x] [COUNTRY [COUNTRY ...]]\n\nprovides information related to a given country or territory; if no argument\nis passed, lists all known countries and territories\n\npositional arguments:\n  COUNTRY     0 or more string for country (can be an alpha-2 code too)\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -x          provides extended country-related information\n\n\n$ chk_ispc.py --help\nusage: chk_ispc.py [-h] [-x] [ISPC [ISPC ...]]\n\nprovides information related to ISPC (International Signaling Point Code); if no \nargument is passed, lists all known ISPC\n\npositional arguments:\n  ISPC        0 or more 3-8-3 formatted or integer ISPC values\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -x          provides extended information for associated country\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FP1sec%2FMCC_MNC","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FP1sec%2FMCC_MNC","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FP1sec%2FMCC_MNC/lists"}