Data sources

Data sources

This library ships several reference tables. This page records where they come from and how corrections are decided, so changes are reviewable rather than taken on trust.

Mobile prefixes

Assigned by the Communications Regulatory Authority. The table covers the three network operators (MCI, Irancell, RightTel), Taliya, and the virtual operators Shatel Mobile, ApTel, Tele Kish and Espadan.

Checked against the actively maintained persian-tools JavaScript implementation and against published operator prefix lists. v1.1.0 added ApTel (999), Tele Kish (934), Espadan (931) and RightTel's 924.

A test asserts no prefix is claimed by two operators and that every prefix in a table resolves through the public lookup.

National id districts

The first three digits of a national code identify the district where the birth certificate was issued. 477 districts across 31 province entries.

Because the code records where a certificate was issued, the table reflects the country's divisions at the time of issuance rather than today's map — Karaj sits under Tehran, not Alborz.

The v1.1.0 correction

Six rows had been appended to the end of the table carrying Isfahan's province code, which is also present in the upstream JavaScript dataset:

District	Code	Was	Now
زنجان	427–428	اصفهان	زنجان
ابهر	615	اصفهان	زنجان
خرمدره	615	اصفهان	زنجان
مرند	158	اصفهان	آذربایجان شرقی
ملکان	507	اصفهان	آذربایجان شرقی
میانه	152–153	اصفهان	آذربایجان شرقی

Two independent checks agreed:

• Published tables of national-code prefixes by province list 427–428 as Zanjan and 615 as Abhar and Khorramdarreh in Zanjan province.
• Range clustering. Each province's codes cluster. Marand (158) and Mianeh (152–153) fall inside East Azerbaijan's existing 136–171 band, alongside Tabriz (136–138), Ahar (149–150) and Sarab (164–165). Malekan (507) sits immediately after Jolfa (505) and Ajabshir (506), both East Azerbaijan. Zanjan's 427–428 falls in the gap between Kohgiluyeh (≤426) and Qazvin (≥431) — exactly where a missing province would sit.

Azna's code also carried a leading space, which leaked into the returned Codes slice.

A deliberate difference from upstream

Upstream lists Estahban as 252-254. This library keeps 252, because 253 is already Eghlid and Sepidan; the wider range would make the lookup ambiguous.

Bank card prefixes and Sheba codes

The six-digit BIN table and the three-digit Sheba bank codes were checked against the persian-tools JavaScript dataset. v1.1.0 added the 505426 (Gardeshgari) and 636797 (Central Bank) card prefixes.

Codes for the five institutions absorbed by Bank Sepah are kept, because IBANs issued before the merger remain valid — see bank.

Testing

The dataset tests are as important as the tables:

• every one of the 477 national id prefixes resolves to a city and a province
• no city points at a province that is not defined
• no code carries stray whitespace or a non-three-digit part
• no mobile prefix is claimed by two operators
• no duplicate or malformed bank codes; any bank advertising account numbers has a Process function

Reporting a data error

Open an issue with the code, what the library returns, what you expected, and a source. Data corrections are welcome and easy to review when they come with a reference.