plmn

Look up mobile network operator information by MCC/MNC (PLMN) codes.

Installation

npm install plmn

Usage

This package is ESM-only. It cannot be used with require().

TypeScript

import { getOperatorInfo, type Operator } from 'plmn';

const operator = getOperatorInfo({ mcc: '310', mnc: '260' });

if (operator) {
  console.log(operator.operator);  // "T-Mobile USA"
  console.log(operator.country);   // "United States of America"
  console.log(operator.bands);     // ["GSM 1900", "LTE 700", "5G 600", ...]
}

JavaScript (ESM)

import { getOperatorInfo } from 'plmn';

const operator = getOperatorInfo({ mcc: '310', mnc: '260' });

console.log(operator?.operator);  // "T-Mobile USA"

CommonJS / require()

This package does not support CommonJS. If you need to use it in a CommonJS context, use dynamic import:

const { getOperatorInfo } = await import('plmn');

API

getOperatorInfo(input)

Retrieves operator information for a given MCC/MNC combination.

Parameters:

• input.mcc - Mobile Country Code (3 digits, e.g., "310")
• input.mnc - Mobile Network Code (2-3 digits, e.g., "260")

Returns: Operator | null - Returns null if the PLMN code is not found.

Type: Operator

type Operator = {
  mcc: string;        // Mobile Country Code (3 digits)
  mnc: string;        // Mobile Network Code (2-3 digits)
  plmn: string;       // Combined PLMN code (e.g., "310260")
  region: string | null;   // Geographic region
  country: string | null;  // Full country name
  iso: string | null;      // ISO 3166-1 alpha-2 country code
  operator: string;   // Full legal operator name
  brand: string | null;    // Commercial brand name
  tadig: string | null;    // TADIG code for roaming
  bands: string[];    // Supported frequency bands
};

Data Source

Data is sourced from mcc-mnc.net.

Using JSON Files Directly

The /dist/data directory contains individual JSON files for each PLMN code, named {PLMN}.json (e.g., 310260.json). This allows you to use the data directly in other programming languages without using this package.

Example JSON structure:

{
  "mcc": "310",
  "mnc": "260",
  "plmn": "310260",
  "region": "North America and the Caribbean",
  "country": "United States of America",
  "iso": "US",
  "operator": "T-Mobile USA",
  "brand": "T-Mobile",
  "tadig": "USAW6",
  "bands": ["GSM 1900", "LTE 700", "5G 600"]
}

Updating the Data

To regenerate the JSON data files from the source:

npm run generate

This downloads the latest data from mcc-mnc.net and generates JSON files in the dist/data/ directory.