MCC/MNC Lookup

Global Mobile Network Code Database

World Map View
Back to Home

API Documentation

Complete guide to accessing the MCC-MNC Database API

MCC-MNC Database API Documentation

Base URL

https://mcc-mnc-lookup.com/api/codes/

Rate Limits

API Endpoints: - 1,000 requests per day per IP address - 10 requests per minute per IP address

Downloads (CSV/JSON): - 10 downloads per day per IP address

When rate limits are exceeded, you'll receive a 429 Too Many Requests response.

Important Notes

  • The API only returns active codes - Inactive change types (LIR, SUP, DEL, WD) are automatically excluded to protect database integrity
  • The API returns the latest active record for each unique MCC-MNC combination

Response Format

All API endpoints return JSON responses.

API Endpoints

List Mobile Codes

GET /api/codes/

Returns a list of mobile network codes with optional filtering, searching, and sorting.

Query Parameters

Parameter Type Description Example
q string Search across MCC, MNC, country, operator, and ISO code ?q=vodafone
mcc string Filter by Mobile Country Code (partial match) ?mcc=310
mnc string Filter by Mobile Network Code (partial match) ?mnc=410
country string Filter by country name (partial match) ?country=united
iso_code string Filter by ISO country code (exact match) ?iso_code=US
operator string Filter by operator name (partial match) ?operator=verizon
region string Filter by geographic region ?region=americas
as_of_date date Show data as of specific date (YYYY-MM-DD) ?as_of_date=2024-01-01
status string Filter by status ?status=Operational
sort string Sort by field ?sort=country
dir string Sort direction (asc or desc) ?dir=desc

Note: The API automatically returns only active codes (excludes LIR, SUP, DEL, WD change types).

Valid Region Values

  • africa
  • americas
  • asia
  • europe
  • oceania

Valid Sort Fields

  • country
  • mcc
  • mnc
  • operator
  • bulletin_date

Response Example

[
  {
    "mcc": "310",
    "mnc": "410",
    "country": "United States",
    "iso_code": "US",
    "operator": "AT&T Mobility",
    "status": "Operational",
    "change_type": "ADD",
    "bulletin_number": "1234",
    "bulletin_date": "2024-01-15"
  }
]

Get Specific Mobile Code

Note: This endpoint has been disabled to protect internal database IDs. Please use filter parameters on the /api/codes/ endpoint instead.

For example, to find a specific code:

# Filter by MCC and MNC
curl "https://www.mcc-mnc-lookup.com/api/codes/?mcc=310&mnc=410"

Get Code History Timeline

GET /api/codes/history/{mcc}/{mnc}/

Returns the complete history for a specific MCC-MNC code, showing all operator assignments with their active date ranges. Each entry represents a unique operator assignment to this code.

How Active Dates Are Determined: - active_start_date: - Set to the bulletin date if change_type is ADD - Set to "unknown" for pre-existing codes (null change_type) or codes first seen with MOD/REP - active_end_date: - Set to the bulletin date if terminated with SUP (Suppressed), DEL (Deleted), or WD (Withdrawn) - Set to "present" if the assignment is still active

Sorting: - Currently active assignments (active_end_date: "present") appear first - Within each group, sorted by latest bulletin date (newest first)

Parameters

  • mcc - Mobile Country Code (path parameter)
  • mnc - Mobile Network Code (path parameter)

Response Example

{
  "mcc": "425",
  "mnc": "12",
  "history": [
    {
      "mcc": "425",
      "mnc": "12",
      "operator": "Widly Mobile",
      "country": "Israel",
      "iso_code": "IL",
      "active_start_date": "2025-02-01",
      "active_end_date": "present",
      "latest_bulletin_date": "2025-02-01"
    },
    {
      "mcc": "425",
      "mnc": "12",
      "operator": "Free Telecom",
      "country": "Israel",
      "iso_code": "IL",
      "active_start_date": "unknown",
      "active_end_date": "2025-02-01",
      "latest_bulletin_date": "2025-02-01"
    }
  ]
}

Interpretation: - Widly Mobile currently holds this MCC-MNC code (started 2025-02-01, still active) - Free Telecom previously held this code (start date unknown, ended 2025-02-01)

Example API Calls

Search for all Verizon networks

curl "https://www.mcc-mnc-lookup.com/api/codes/?operator=verizon"

Get all codes in the United States

curl "https://www.mcc-mnc-lookup.com/api/codes/?country=united%20states"

Get all codes in Americas region

curl "https://www.mcc-mnc-lookup.com/api/codes/?region=americas"

Get all codes with MCC 310

curl "https://www.mcc-mnc-lookup.com/api/codes/?mcc=310"

Get codes as they existed on January 1, 2024

curl "https://www.mcc-mnc-lookup.com/api/codes/?as_of_date=2024-01-01"

Get codes sorted by operator name in descending order

curl "https://www.mcc-mnc-lookup.com/api/codes/?sort=operator&dir=desc"

Combined filters and sorting

curl "https://www.mcc-mnc-lookup.com/api/codes/?country=germany&sort=operator&dir=asc"

Get history timeline for a specific MCC-MNC

curl "https://www.mcc-mnc-lookup.com/api/codes/history/310/410/"

Pagination

The API supports pagination using Django REST Framework's default pagination. Add page and page_size parameters:

curl "https://www.mcc-mnc-lookup.com/api/codes/?page=2&page_size=50"

Error Responses

404 Not Found

{
  "error": "No records found for MCC-MNC 999-999"
}

400 Bad Request

Invalid query parameters will be ignored, and the API will return results based on valid parameters.

Notes

  1. Active Codes Only: The API only returns active codes (automatically excludes LIR, SUP, DEL, WD change types).

  2. Historical View: When using as_of_date, the API shows the state of active codes as they existed on that date.

  3. Latest Records: The API automatically returns the latest active bulletin record for each unique MCC-MNC combination.

  4. Case-Insensitive Search: Text searches and filters are case-insensitive for better usability.

  5. Partial Matching: Most text filters use partial matching (contains), except iso_code which uses exact matching.

← Back to Home