Worldref

worldref

Every country in Arabic, English, or both: names, nationalities, capitals, currencies, languages, time zones, dial codes, phone validation, address formats and subdivisions. One dataset, ready for JSON, CSV, SQL, TypeScript, Python, Swift, Kotlin, Dart, PHP, Go and C#, and for AI agents (MCP).

العربية · Website and search demo · Best practices · Field reference · Data sources

[CI] [npm] [PyPI] [pub.dev] [NuGet] [Packagist] [MCP Registry] [countries] [subdivisions] [languages]

import { countries, search, parsePhone, byIso2 } from "worldref";
byIso2("SA").name_ar;                       // "السعودية"byIso2("SA").nationality.nationality_ar_f;  // "سعودية"search(countries, "الامارات", "ar")[0].iso2; // "AE"  (ignores «ال», hamza and tashkeel)parsePhone("٠٥٠١٢٣٤٥٦٧", byIso2("SA"));     // { e164: "+966501234567", valid: true, mobile: true, ... }

Why worldref

• Arabic done natively. Short common names (السعودية, not a transliteration), nationality in masculine and feminine (سعودي / سعودية), search that ignores «ال», tashkeel, tatweel and hamza forms, Arabic-Indic and Persian digits accepted everywhere, and sort keys that give correct Arabic alphabetical order on every platform.
• Works for one language or two. Every file comes in three builds: bilingual (name_ar, name_en), Arabic-only (name) and English-only (name).
• Phone fields that work. Dial codes, valid lengths, mobile prefixes and exact validation patterns for every country, shared calling codes resolved (+1, +7, +44...), and international (E.164) output.
• Everything a form or app needs in one place: official names, capitals, currencies with symbols (including the new Saudi riyal sign), official languages, week start and weekend, preferred calendars (including Umm al-Qura), postal code rules, address templates, emergency numbers, plug types and voltage, FIFA and IOC codes, and ISO 3166-2 subdivisions.
• Sourced, not guessed. Official sources first (Unicode CLDR, Google libphonenumber, World Bank, IANA, ITU and government sources). Every column names its source in data/sources.json. A missing value is null, never a guess or a machine translation.

Install

Published on npm, PyPI, pub.dev, Packagist, NuGet and the MCP Registry. Swift, Kotlin and Go install straight from this repository.

Each language folder has its own README with a usage example: python, Swift, kotlin, dart, php, go, csharp.

Use only what you need

• The data is split into modules that share the key iso2: core, nationality, phone, currency, geo, locale, address, travel, sports, plus subdivisions. Find them in data/modules/.
• Each module comes in 3 builds: .json (Arabic and English), .ar.json (Arabic only), .en.json (English only).
• JS/TS: import only the module you use, and your bundler ships only that file:
  js

  import phone from "worldref/data/modules/phone.json" with { type: "json" };import { parsePhone } from "worldref/helpers";

• Other languages: load only the module files you need. data/worldref.json has everything.
• One country, no install: https://arj-89.github.io/worldref/api/v1/{iso2}.json.
• A missing value is null (or an empty list). Treat it as unknown; never fill it in.
• Within a major version, fields are never renamed or removed.

Recipes

Country picker (user's country first, then alphabetical in the UI language):

import { countries, sortCountries, search } from "worldref";const list = sortCountries(countries, "ar", "SA");          // السعودية first, then Arabic orderconst hits = search(countries, userQuery, "ar");            // names, aliases, ISO codes, +966 / 00966 / 966

Show: flag, name in the UI language, then the dial code. In Arabic, isolate the dial code left-to-right (<bdi dir="ltr">+966</bdi>).

Phone field (store the international form plus the country the user picked):

const p = parsePhone(input, byIso2(pickedIso2), countries);if (p?.valid && p.mobile) save({ phone: p.e164, phone_country: p.iso2 });

Nationality field (only rows that have one: countries, plus Taiwan, Hong Kong and Macau):

const options = countries.filter((c) => c.nationality.nationality_en);const label = (c, female) => (female ? c.nationality.nationality_ar_f : c.nationality.nationality_ar_m);

Database seed: run data/sql/postgres.sql (or mysql.sql, sqlite.sql). It creates countries and subdivisions.

Best practices

Every rule below is built into the helpers of all eight packages and locked by the shared tests in tests/vectors.json. Use the helpers; if you write your own, follow these rules exactly.

Search (normalize(), search())

• Normalise both sides, the query and the names, the same way.
• Arabic: drop «ال» at the start of every word (not only the first); remove tashkeel (fatha, damma, kasra, sukun, shadda, tanween) and tatweel (ـ); treat أ إ آ ٱ as ا, ة as ه, ى as ي, ؤ as و, ئ as ي. So «الإمارات», «امارات» and «الأمارات» all find the UAE.
• Latin: ignore case and accents, and treat punctuation as a space, so «cote d'ivoire» finds Côte d’Ivoire.
• Digits: convert Arabic-Indic (٠١٢٣٤٥٦٧٨٩) and Persian (۰۱۲۳۴۵۶۷۸۹) digits to Western before anything else.
• Match names and aliases in both languages, ISO codes (SA, SAU), and dial codes with or without «+» or «00» (+966, 00966, 966).

Sorting (sortCountries())

• Put the user's country first: from their profile, else the device region, else pin nothing.
• Then sort by sort_ar or sort_en with plain string comparison. Do not use locale collation (Intl.Collator("ar"), localizedStandardCompare): neither ignores «ال», so every «ال» name bunches under ا.

Display

• Show the flag, then the name in the UI language, then the dial code.
• In Arabic, isolate the dial code and any Latin text left-to-right in the UI (<bdi dir="ltr">+966</bdi>, or U+2066 ... U+2069). The data never contains bidi marks.
• Show Western numerals (0-9) in the UI, in both languages.
• Use flag_svg on the web: Windows does not draw flag emoji.
• Currency: show symbol (the Saudi riyal sign is U+20C1) and fall back to symbol_fallback (ر.س) where the font lacks the new sign.

Phone fields (parsePhone(), formatNational())

• Accept whatever the user types: Arabic or Western digits, spaces, dashes, a leading 0, «+» or «00».
• Store the international form (e164) together with the iso2 the user picked. Shared calling codes (+1, +7, +44, +599...) cannot be read back to one country from the number alone.
• Validate a mobile with mobile_pattern. Where mobile_distinguishable is false (US, Canada), do not reject a number for not looking like a mobile.
• Format for display with formatNational() (5X XXX XXXX style).

Nationality fields

• List only rows where nationality.nationality_en is not null (countries, plus Taiwan, Hong Kong and Macau).
• In Arabic, use the form that matches the person: nationality_ar_m (سعودي) or nationality_ar_f (سعودية).

Data

• null (or an empty list) means unknown. Show it as unknown; never fill it from elsewhere.
• Load only the modules you need; they join on iso2.
• Pin a version (#v1.1.2, @1.1.2) so names and rules do not change under you.

Data policy

• Israel is not in this dataset, in any file, under any name or code. A test enforces this on every output.
• Palestine is «فلسطين» / "Palestine", a country, with its capital «القدس» / "Jerusalem". Numbers with +970 and +972 (including Jerusalem and the 1948 lines) are Palestinian numbers here. Its currencies are the Jordanian dinar and the shekel (shown as «شيكل» / "Shekel").
• Disputed places follow the official positions of Saudi Arabia: Western Sahara is part of Morocco (no separate row), Kosovo is included, Northern Cyprus is not, and Taiwan, Hong Kong and Macau are territories that still have a nationality (they issue their own passports).
• Requests to change this policy are closed without discussion. Corrections to data are welcome with a source link (see CONTRIBUTING).

Fields

Single-language builds drop the _ar / _en suffix (name_ar becomes name in .ar.json).

FAQ

How do I get a list of countries in Arabic? Use data/worldref.ar.json (or data/modules/core.ar.json for names only). Each row has name in Arabic. For a ready-made picker order, sort by sort (it ignores «ال» and hamza forms).

Where is a list of nationalities in Arabic, masculine and feminine? data/modules/nationality.json: nationality_ar_m (سعودي) and nationality_ar_f (سعودية), plus nationality_en (Saudi).

How do I validate a Saudi mobile number? parsePhone(input, byIso2("SA")) and check valid && mobile. The rule is in phone[0].mobile_pattern: 9 digits starting with 50, 51, 53 to 59 after dropping the leading 0. Arabic digits are accepted.

Why is travel.emergency.police null for some countries? Only numbers confirmed by an official source are published. If a service is null, call general.

Can I use this commercially? Yes. Code is MIT; data licences (Unicode, Apache-2.0, CC-BY-4.0, CC0, public domain) all allow commercial use with attribution where required. See LICENSE.

How current is it? An automated job checks the upstream sources monthly (population quarterly) and releases a patch when they change and every test passes. Versions are in data/meta.json.

For AI agents

Start at llms.txt and AGENTS.md. Schemas are in schema/. The MCP server (npx -y worldref mcp) offers get_country, search_countries, validate_phone and list_subdivisions. Answer from the data only and treat null as unknown.

Roadmap

Planned for 1.2.0 (new, non-breaking):

1. Official Arabic names: 222 rows are empty today, the largest gap in the data.
2. Subdivision types in both languages (region, province, emirate, state).
3. More forgiving search: names typed without punctuation or with small typos ("cote divoire", "Kuwiat").
4. An address-form helper: the fields, order and labels of a country's address form in Arabic or English.
5. Kotlin on Maven Central, alongside JitPack.
6. Cities: a new cities module with Arabic and English names, linked to each country and subdivision.

Sources and licences

Code: MIT. Data: Unicode CLDR 49 (Unicode-3.0), Google libphonenumber v9.0.42 and address metadata (Apache-2.0, modified), World Bank (CC-BY-4.0), Wikidata (CC0), CIA World Factbook final edition and IANA (public domain), flag-icons (MIT), and official government sources for emergency numbers. Full texts: LICENSES/. Per-column sources and every editorial decision: data/sources.json.

Cite as: see CITATION.cff.