# MCC-MNC.dev — Full reference for LLMs and agents > Free, searchable registry of 3,042 mobile networks in 227 countries — mobile country codes (MCC), mobile network codes (MNC), PLMN identifiers, ISO country codes, dial prefixes and operators — with a free JSON API and phone-number-to-operator lookup. Data licensed CC BY-SA 4.0. This is a single, self-contained document you can ingest whole. It explains the telecom identifiers, then documents the complete REST API distilled from the wire contract, with copy- pasteable curl examples. A shorter index lives at https://mcc-mnc.dev/llms.txt. Site: https://mcc-mnc.dev API base: https://mcc-mnc.dev/api/v1 Bulk data: https://mcc-mnc.dev/data/networks.json and /data/networks.csv License: CC BY-SA 4.0 — attribute "MCC-MNC.dev (https://mcc-mnc.dev), derived from Wikipedia". ================================================================================ 1. CONCEPTS: MCC, MNC, PLMN, IMSI ================================================================================ MCC (Mobile Country Code) A 3-digit code identifying the COUNTRY (or geographic region) of a mobile network, allocated by the ITU under recommendation E.212. Examples: 230 = Czech Republic, 310-316 = United States, 234/235 = United Kingdom, 262 = Germany, 404-406/40x = India. A single country can own several MCCs. MNC (Mobile Network Code) A 2- or 3-digit code identifying a specific NETWORK OPERATOR within an MCC. Examples inside MCC 230 (Czech Republic): 01 = T-Mobile, 02 = O2, 03 = Vodafone. Zero-padding is SIGNIFICANT: MNC "02" is not the same as "2". Whether an operator's MNC is 2 or 3 digits is set per country. PLMN (Public Land Mobile Network) id The MCC and MNC concatenated: it uniquely identifies one network worldwide and is the canonical key in this dataset. Example: MCC 230 + MNC 02 => PLMN "23002". This is the code broadcast by cell towers and stored on SIM cards; phones show it (or its friendly name) as the carrier. IMSI (International Mobile Subscriber Identity) The unique id of a SIM/subscriber, up to 15 digits, structured as MCC + MNC + MSIN (Mobile Subscriber Identification Number). The leading 5-6 digits of any IMSI are exactly the PLMN, so MCC/MNC lookups let you resolve which network issued a given IMSI. Example IMSI 230025512345678 => MCC 230, MNC 02 => O2 Czech Republic. Status and type status: "Operational", "Not operational", "Reserved", "Testing", "Unknown", etc. type: "National", "International" (MCC 90x: satellite/maritime/aviation), or "Test". Europe enrichment ~200 European rows carry extra operator-level detail: subscriber counts (millions, with a reporting period), ownership group, in-country rank, detailed radio-technology lines, and a computed market_reach percentage (operator subscribers / country total mobile subscriptions). All of these fields are null outside the enriched European rows. ================================================================================ 2. IMPORTANT CAVEAT: MCC IS NOT THE DIAL PREFIX ================================================================================ Do NOT confuse the MCC with the international dialling / country calling code. - MCC comes from ITU-T E.212 and identifies a SIM's HOME NETWORK country (Czech Republic = 230). - dial_prefix (country calling code) comes from ITU-T E.164 and is used to ROUTE CALLS (Czech Republic = +420). They are different numbering systems with different values for the same country (230 vs +420), and they do not map one-to-one: - One calling code can span several countries and MCCs. +1 (NANP) covers the US, Canada and ~20 Caribbean nations, which between them hold many MCCs (US alone uses 310-316). - Conversely a country with multiple MCCs still has one calling code. When you resolve a PHONE NUMBER, the flow is: calling code (E.164) -> country -> that country's MCC(s) -> operators. The /search endpoint does this for you: pass the phone number and it returns a "phone" analysis object plus the operators of the matched country. Never use an MCC to dial or route a call, and never treat a dial_prefix as an MCC. ================================================================================ 3. API REFERENCE ================================================================================ Base URL: https://mcc-mnc.dev/api/v1 Auth: X-API-Key: mcc_... (alias: Authorization: Bearer mcc_...). Every endpoint requires a free key; create one at https://mcc-mnc.dev/login (self-service, instant, no cost). Method: all endpoints are GET. Rate limit: 100 requests/second per key -> 429 rate_limited with Retry-After: 10. CORS: Access-Control-Allow-Origin: * on all responses; OPTIONS returns 204. -------------------------------------------------------------------------------- 3.1 The Row object (flat, snake_case) -------------------------------------------------------------------------------- Every endpoint that returns network data returns one or more Row objects with these 21 fields: Field | Type | Nullable | Meaning ---------------------+-----------------+----------+--------------------------------------------- plmn | string | never | MCC + MNC concatenated, e.g. "23002". Key. mcc | string | never | Mobile country code, 3 digits. mnc | string | never | Mobile network code, 2-3 digits (padding kept). country | string | null | yes | English country name (null for International). iso2 | string | null | yes | ISO 3166-1 alpha-2, e.g. "CZ". iso3 | string | null | yes | ISO 3166-1 alpha-3, e.g. "CZE". iso_numeric | string | null | yes | ISO 3166-1 numeric as string, e.g. "203". dial_prefix | string | null | yes | E.164 calling code, e.g. "+420" (NOT the MCC). brand | string | null | yes | Consumer brand, e.g. "O2". operator | string | null | yes | Legal operator name, e.g. "O2 Czech Republic". status | string | never | "Operational", "Not operational", "Reserved"... type | string | never | "National", "International", or "Test". bands | string | null | yes | Radio bands summary, e.g. "GSM 900 / LTE 800". technology | string[] | null | yes | Detailed technology lines (Europe rows only). ownership | string | null | yes | Owning group, e.g. "PPF" (Europe rows only). subscribers | number | null | yes | Subscribers in MILLIONS (Europe rows only). subscribers_as_of | string | null | yes | Reporting period, e.g. "2021-Q2". market_reach | number | null | yes | Percentage 0-100 (null outside Europe). market_reach_basis | string | null | yes | Denominator basis, e.g. "country_total". rank | number | null | yes | Operator rank within its country (Europe only). notes | string | null | yes | Free-text remarks (shutdowns, renames, ...). fields parameter: comma-separated subset of the field names above (default: all). An unknown field name returns 400 bad_request. Applies to every endpoint that returns Rows. format parameter: - json (default). - text -> TSV: header line then one Row per line, columns in fields order, technology joined with "; ", nulls as empty strings. Content-Type text/plain; charset=utf-8. Sending "Accept: text/plain" also selects text; an explicit format param wins. - csv -> /dataset only. RFC 4180, Content-Disposition: attachment; filename="mcc-mnc.csv". -------------------------------------------------------------------------------- 3.2 Endpoints -------------------------------------------------------------------------------- GET /search?q=... One search box for everything. q (required) accepts an MCC ("230"), a PLMN ("23002"), a country name or ISO code ("CZ", "Czech"), an operator/brand name ("O2", "vodafone"), or a PHONE NUMBER ("+420601123456"; common national formats are auto-detected). Optional: fields, format, limit (default 50, max 500), offset (default 0). Response shape: { "query": "", "phone": { ...analysis... } | null, "count": , "results": [ Row, ... ] } For phone queries, "phone" is populated and "results" are the operators of the matched country(ies); a valid number whose country cannot be determined returns "phone" with count 0. For non-phone queries, "phone" is null. GET /plmn/{plmn} Exact lookup by concatenated code, e.g. /plmn/23002. Returns a BARE Row. 404 not_found if unknown. Supports fields and format. GET /mcc/{mcc} All networks under one MCC: { "mcc": "230", "count": N, "results": [ Row, ... ] }. 404 if none. GET /mcc/{mcc}/{mnc} Single network, e.g. /mcc/230/02. Bare Row, 404 if unknown. MNC matched as given (zero-padding significant), with a fallback: if no exact match, the 2- or 3-digit zero-padded variant is tried. GET /dataset Full dump, no phone logic. format=json (default) | csv | text; optional fields. Response (json): { "count": 3042, "generated_at": "...", "license": "CC BY-SA 4.0", "results": [ Row, ... ] }. -------------------------------------------------------------------------------- 3.3 Errors -------------------------------------------------------------------------------- Errors are JSON (or a single text line when text format was requested): { "error": { "code": "invalid_api_key", "message": "..." } } HTTP | code -----+----------------------------------------------- 400 | bad_request (malformed query / unknown fields value / bad param) 401 | missing_api_key (no X-API-Key header or Bearer token) 401 | invalid_api_key (key unknown or revoked) 404 | not_found (no network for that PLMN / MCC / MCC+MNC) 429 | rate_limited (over 100 req/s; includes header Retry-After: 10) ================================================================================ 4. CURL EXAMPLES ================================================================================ # Exact PLMN lookup -> a single flat Row curl -H "X-API-Key: mcc_your_key" \ https://mcc-mnc.dev/api/v1/plmn/23002 # Response: { "plmn": "23002", "mcc": "230", "mnc": "02", "country": "Czech Republic", "iso2": "CZ", "iso3": "CZE", "iso_numeric": "203", "dial_prefix": "+420", "brand": "O2", "operator": "O2 Czech Republic", "status": "Operational", "type": "National", "bands": "GSM 900 / GSM 1800 / LTE 800 / ...", "technology": ["GSM-900/1800 MHz (GPRS, EDGE)", "..."], "ownership": "PPF", "subscribers": 5.987, "subscribers_as_of": "2021-Q2", "market_reach": 37.1, "market_reach_basis": "country_total", "rank": 2, "notes": "Former Eurotel; ..." } # Phone-number -> country + operators. Note the leading "+" must be URL-encoded as %2B. curl -H "X-API-Key: mcc_your_key" \ "https://mcc-mnc.dev/api/v1/search?q=%2B420601123456&fields=plmn,mcc,mnc,brand,operator&limit=3" # Response (abridged): { "query": "+420601123456", "phone": { "valid": true, "possible": true, "type": "MOBILE", "country": "CZ", "calling_code": "420", "e164": "+420601123456", "international": "+420 601 123 456", "national": "601 123 456" }, "count": 12, "results": [ { "plmn": "23001", "mcc": "230", "mnc": "01", "brand": "T-Mobile", "operator": "T-Mobile Czech Republic" }, { "plmn": "23002", "mcc": "230", "mnc": "02", "brand": "O2", "operator": "O2 Czech Republic" }, { "plmn": "23003", "mcc": "230", "mnc": "03", "brand": "Vodafone", "operator": "Vodafone Czech Republic" } ] } # Text (TSV) output with a field subset curl -H "X-API-Key: mcc_your_key" \ "https://mcc-mnc.dev/api/v1/search?q=23002&format=text&fields=plmn,mcc,mnc,brand,country" # plmn mcc mnc brand country # 23002 230 02 O2 Czech Republic # Whole dataset as CSV (saved as mcc-mnc.csv) curl -H "X-API-Key: mcc_your_key" -OJ \ "https://mcc-mnc.dev/api/v1/dataset?format=csv" ================================================================================ 5. BULK DATA & RAG ================================================================================ For embedding, indexing or offline enrichment, download the full dataset (no API key required): https://mcc-mnc.dev/data/networks.json full nested JSON (country block + Europe enrichment) https://mcc-mnc.dev/data/networks.csv flat CSV, same columns as the API wire format https://mcc-mnc.dev/data/meta.json generation metadata; watch generatedAt for new revisions Each network row is compact and self-contained, which makes one-row-per-chunk a reasonable RAG granularity. Official client libraries (JavaScript/TypeScript, Python, .NET, PHP) are documented at https://mcc-mnc.dev/docs. Tool/function schemas for OpenAI and Anthropic agents are at https://mcc-mnc.dev/ai. License: CC BY-SA 4.0. If you redistribute or build a derived dataset, credit the source and share derivatives under the same license. Attribution: Data: MCC-MNC.dev (https://mcc-mnc.dev), derived from Wikipedia — CC BY-SA 4.0