worldref

worldref

アラビア語、英語、またはその両方ですべての国を網羅： 国名、国籍、首都、通貨、言語、タイムゾーン、国番号、電話番号の検証、住所形式、行政区画を収録しています。1 つのデータセットで、JSON、CSV、SQL、TypeScript、Python、Swift、Kotlin、Dart、PHP、Go、C# に対応し、AI エージェント（MCP）でも利用できます。

العربية · ウェブサイトと検索デモ · ベストプラクティス · フィールドリファレンス · データソース

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, ... }

worldref を選ぶ理由

• アラビア語にネイティブ対応。 短い一般的な名称（音訳ではなく、السعودية など）、男性形と女性形の国籍名（سعودي / سعودية）、«ال»、タシュキール、タトウィール、ハムザの異形を無視する検索、あらゆる場所で使えるアラビア・インド数字とペルシア数字、すべてのプラットフォームで正しいアラビア語のアルファベット順になるソートキーを備えています。
• 1 言語でも 2 言語でも利用できます。 すべてのファイルが 3 種類のビルドで提供されます：バイリンガル版（name_ar、name_en）、アラビア語のみの版（name）、英語のみの版（name）。
• 実用的な電話番号フィールド。 すべての国について、国番号、有効な桁数、携帯電話のプレフィックス、正確な検証パターンを収録しています。共通の国番号は適切に判別され（+1、+7、+44 など）、国際形式（E.164）で出力できます。
• フォームやアプリに必要な情報をすべて 1 か所に集約： 正式名称、首都、記号付きの通貨（新しいサウジアラビア・リヤルの記号を含む）、公用語、週の開始曜日と週末、推奨カレンダー（ウンム・アル＝クラーを含む）、郵便番号のルール、住所テンプレート、緊急電話番号、プラグの種類と電圧、FIFA および IOC のコード、ISO 3166-2 の行政区画を収録しています。
• 推測ではなく、出典に基づいています。 まず公式ソース（Unicode CLDR、Google libphonenumber、世界銀行、IANA、ITU、各国政府の情報源）を参照しています。各列の出典は data/sources.json に記載しています。欠損値は推測や機械翻訳ではなく、null です。

インストール

npm、PyPI、pub.dev、Packagist、NuGet、MCP Registry で公開されています。Swift、Kotlin、Go はこのリポジトリから直接インストールできます。

スタック	インストール
JavaScript、TypeScript（Web、Node 20.10+、React Native、Bun、Deno）	npm i worldref
CDN（ビルド不要）	https://cdn.jsdelivr.net/npm/[email protected]/data/worldref.json
Swift（iOS、macOS）	Swift Package Manager：https://github.com/arj-89/worldref、1.1.2 以降、プロダクト WorldRef
Kotlin、Android	JitPack：maven("https://jitpack.io")、続いて implementation("com.github.arj-89:worldref:v1.1.2")
Python	pip install worldref
Dart、Flutter	dart pub add worldref（Flutter：flutter pub add worldref）
PHP、Laravel	composer require arj-89/worldref
Go	go get github.com/arj-89/worldref/[email protected]
C#、.NET	dotnet add package WorldRef
任意の言語	data/ およびリリースページにある JSON、CSV、SQL（Postgres、MySQL、SQLite）
AI エージェント	MCP サーバー：npx -y worldref mcp（MCP Registry には io.github.arj-89/worldref として登録）
インストール不要	1 か国：https://arj-89.github.io/worldref/api/v1/sa.json

各言語のフォルダーに使用例を含む README があります：python、Swift、kotlin、dart、php、go、csharp。

必要なものだけを使う

• データは iso2 キーを共有するモジュールに分かれています：core、nationality、phone、currency、geo、locale、address、travel、sports、さらに subdivisions があります。data/modules/で確認できます。
• 各モジュールには 3 種類のビルドがあります：.json（アラビア語と英語）、.ar.json（アラビア語のみ）、.en.json（英語のみ）。
• **JS/TS：**使用するモジュールのみをインポートすると、バンドラーにはそのファイルだけが含まれます。

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

• **その他の言語：**必要なモジュールファイルのみを読み込みます。data/worldref.jsonにはすべてのデータが含まれています。
• 1 か国、インストール不要：https://arj-89.github.io/worldref/api/v1/{iso2}.json。
• 値がない場合は null（または空のリスト）です。不明として扱い、決して補完しないでください。
• メジャーバージョン内では、フィールドの名前変更や削除はありません。

レシピ

国選択欄（ユーザーの国を先頭にし、その後は UI の言語でアルファベット順に表示）：

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

表示する内容：旗、UI の言語での国名、続いて国番号。アラビア語では、国番号を左から右へ分離して表示します（<bdi dir="ltr">+966</bdi>）。

電話番号欄（国際形式と、ユーザーが選んだ国を保存）：

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

国籍欄（国籍のある行のみ：国に加えて台湾、香港、マカオ）：

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

データベースのシード：data/sql/postgres.sql（または mysql.sql、sqlite.sql）を実行します。countries と subdivisions が作成されます。

ベストプラクティス

以下の各ルールは、8つすべてのパッケージのヘルパーに組み込まれており、tests/vectors.json の共通テストで固定されています。ヘルパーを使用してください。独自に実装する場合は、これらのルールに正確に従ってください。

検索（normalize()、search()）

• クエリと名前の両方を、同じ方法で正規化します。
• アラビア語：各単語の先頭にある「ال」を削除します（最初の単語だけではありません）。タシュキール（ファトハ、ダンマ、カスラ、スクーン、シャッダ、タンウィーン）とタトウィール（ـ）を削除し、أ إ آ ٱ は ا、ة は ه、ى は ي、ؤ は و、ئ は ي として扱います。たとえば、「الإمارات」「امارات」「الأمارات」はすべて UAE の検索結果になります。
• ラテン文字：大文字と小文字、アクセント記号を無視し、句読点をスペースとして扱います。そのため、「cote d'ivoire」で Côte d’Ivoire が見つかります。
• 数字：ほかの処理をする前に、アラビア・インド数字（٠١٢٣٤٥٦٧٨٩）とペルシア数字（۰۱۲۳۴۵۶۷۸۹）を西洋数字に変換します。
• どちらの言語の名前と別名、ISO コード（SA、SAU）、および「+」や「00」の有無を問わない電話番号の国番号（+966、00966、966）を照合します。

並べ替え（sortCountries()）

• ユーザーの国を先頭にします。プロフィールから取得し、なければデバイスの地域を使い、どちらもなければ何も固定しません。
• 次に、sort_ar または sort_en を単純な文字列比較で並べ替えます。ロケール照合（Intl.Collator("ar")、localizedStandardCompare）は使用しないでください。どちらも「ال」を無視しないため、「ال」で始まる名前がすべて ا の下に集まります。

表示

• 国旗、UI の言語での名前、電話番号の国番号の順に表示します。
• アラビア語では、電話番号の国番号と、UI 内のラテン文字を左から右に分離して表示します（<bdi dir="ltr">+966</bdi>、または U+2066 ... U+2069）。データに双方向テキストマークは含まれません。
• どちらの言語でも、UI には西洋数字（0-9）を表示します。
• ウェブでは flag_svg を使用します。Windows では国旗の絵文字が描画されません。
• 通貨：symbol（サウジアラビア・リヤル記号は U+20C1）を表示し、新しい記号に対応していないフォントでは symbol_fallback（ر.س）を使用します。

電話番号フィールド（parsePhone()、formatNational()）

• ユーザーが入力する形式を問わず受け付けます。アラビア数字または西洋数字、スペース、ハイフン、先頭の 0、「+」、「00」に対応します。
• 国際形式（e164）を、ユーザーが選択した iso2 とともに保存します。共通の電話番号の国番号（+1、+7、+44、+599 など）から、番号だけを使って国を一意に特定することはできません。
• mobile_pattern を使って携帯電話番号を検証します。mobile_distinguishable が false の場合（米国、カナダ）、携帯電話番号の形式に見えないことを理由に番号を拒否しないでください。
• formatNational() を使って表示用に整形します（5X XXX XXXX 形式）。

国籍フィールド

• nationality.nationality_en が null ではない行だけを一覧表示します（国に加えて、台湾、香港、マカオ）。
• アラビア語では、対象者に合った形式を使います。nationality_ar_m（سعودي）または nationality_ar_f（سعودية）。

データ

• null（または空のリスト）は不明を意味します。不明として表示し、ほかの場所から補完しないでください。
• 必要なモジュールだけを読み込みます。モジュールは iso2 で結合されます。
• バージョンを固定してください（#v1.1.2、@1.1.2）。名前やルールが変更されないようにします。

データポリシー

• イスラエルは、このデータセットのどのファイルにも、どの名前やコードでも含まれていません。 すべての出力に対してテストで検証されます。
• パレスチナは「فلسطين」／"Palestine" で、首都は「القدس」／"Jerusalem" です。+970 および +972（エルサレムと1948年の回線を含む）の番号は、ここではパレスチナの番号です。通貨はヨルダン・ディナールとシェケル（「شيكل」／"Shekel" と表示）です。
• 係争地はサウジアラビアの公式見解に従います。 西サハラはモロッコの一部（独立した行はありません）、コソボは含まれ、北キプロスは含まれません。また、台湾、香港、マカオは、独自のパスポートを発行する地域ですが、国籍を持ちます。
• このポリシーの変更リクエストは、議論なしでクローズされます。データの修正は、出典へのリンクを添えて歓迎します（CONTRIBUTING を参照）。

フィールド

単一言語ビルドでは、_ar／_en サフィックスが削除されます（.ar.json では name_ar が name になります）。

フィールド	モジュール	例（SA）	意味
iso2	all	SA	ISO 3166-1 alpha-2 コード（コソボは XK）。すべてのモジュールを結合するキーです。
iso3	core	SAU	ISO 3166-1 alpha-3 コード（CLDR ではコソボは XKK）。
iso_numeric	core	682	ISO 3166-1 数値コード。先頭のゼロを保持するため、テキストとして扱います。
kind	core	country	country（パレスチナ、バチカン、コソボを含む主権国家）または territory です。
name_ar	core	السعودية	アラビア語の一般的な短縮名です。
name_en	core	Saudi Arabia	英語の一般的な短縮名です。
official_name_ar	core	المملكة العربية السعودية	出典に記載されている場合の、アラビア語の正式な長称です。
official_name_en	core	Kingdom of Saudi Arabia	出典に記載されている場合の、英語の正式な長称です。
aliases_ar	core	["المملكة العربية السعودية","المملكة"...	検索に使われるその他のアラビア語名です。検索専用で、表示には使いません。
aliases_en	core	["KSA","Kingdom of Saudi Arabia","Sau...	検索に使われるその他の英語名です。検索専用で、表示には使いません。
flag	core	🇸🇦	国旗の絵文字（地域インジケーターのペア）です。Windows では表示されないため、ウェブでは flag_svg を使用してください。
flag_svg	core	flags/sa.svg	このパッケージに含まれる 4:3 の SVG 国旗のパスです。
continent	core	asia	africa、americas、asia、europe、oceania のいずれかです（CLDR 経由の国連 M49）。
groups	core	["gcc","arab_league"]	加盟グループです（gcc、arab_league）。
un_member	core	true	国連加盟国 193 か国の場合は true です。
tld	core	.sa	割り当てられている場合の国別コードトップレベルドメインです。
sort_ar	core	سعوديه	アラビア語のソートキーです。アラビア語で正しく並べ替えるには、単純な文字列比較で比較してください（「ال」、ハムザの異形、タシュキールは無視します）。
sort_en	core	saudi arabia	英語のソートキーです。単純な文字列比較で比較してください。
nationality	nationality		国籍名です。国、および TW、HK、MO に設定され、それ以外の地域では null です。
nationality.nationality_ar_m	nationality	سعودي	アラビア語の国籍名（男性形）です（سعودي）。
nationality.nationality_ar_f	nationality	سعودية	アラビア語の国籍名（女性形）です（سعودية）。
nationality.nationality_en	nationality	Saudi	英語の国籍形容詞です（Saudi）。
nationality.icao_code	nationality	SAU	パスポートに使用される ICAO Doc 9303 コードです（ほとんどは iso3。ドイツは D、コソボは RKS）。
phone	phone	[{"calling_code":"+966","leading_digi...	この行の電話番号計画です。ほとんどの行には 1 つありますが、複数ある行もあります（パレスチナ：+970 と +972）。
phone[].calling_code	phone	+966	+ を付けた国際電話番号コードです。
phone[].leading_digits	phone	null	電話番号コードを共有している場合に、国内番号の先頭に必要な数字を表す正規表現です（例：DO の +1 809|829|849）。この形式でコードを共有していない場合は null です。
phone[].primary	phone	true	この行がその電話番号コードのデフォルトの国である場合は true です。
phone[].trunk_prefix	phone	0	電話番号コードを付ける前に国内番号から削除する数字です（0501234567 の 0）。
phone[].pattern	phone	(?:[15]\d|800|92)\d{7}	有効な国内番号（すべての種類）に一致する正規表現です。国内番号全体に対して照合してください。
phone[].lengths	phone	[9,10]	有効な国内番号の桁数（すべての種類）です。
phone[].mobile_pattern	phone	579[0-8]\d{5}|5(?:[013-689]\d|7[0-8])...	有効な携帯電話番号に一致する正規表現です。国内番号全体に対して照合してください。
phone[].mobile_lengths	phone	[9]	有効な携帯電話番号の桁数です。
phone[].mobile_prefixes	phone	["50","51","53","54","55","56","57","...	携帯電話番号の先頭の数字（最大 3 桁）です。簡易チェックに使用してください。正確な検証には mobile_pattern を使用してください。
phone[].mobile_distinguishable	phone	true	携帯電話番号と固定電話番号の形式が同じ場合（米国、カナダ）は false です。
phone[].mobile_example	phone	512345678	入力欄のプレースホルダーに適した携帯電話番号の例です。
phone[].mobile_format	phone	## ### ####	携帯電話番号を表示する際の区切り形式です。# は数字を表します。
currencies	currency	[{"code":"SAR","name_ar":"ريال سعودي"...	使用されている通貨です。
currencies[].code	currency	SAR	ISO 4217 コードです。
currencies[].name_ar	currency	ريال سعودي	通貨名（アラビア語）です。
currencies[].name_en	currency	Saudi Riyal	通貨名（英語）です。
currencies[].symbol	currency	⃁	記号です（リヤル記号など、新しい Unicode 記号がある場合はそれを使用します）。
currencies[].symbol_ar	currency	ر.س.	アラビア語で表記する記号です（ر.س）。
currencies[].symbol_fallback	currency	ر.س	フォントが新しい記号に対応していない場合に表示するテキストです。
geo	geo		地理情報です。
geo.capital_ar	geo	الرياض	アラビア語の首都名です。
geo.capital_en	geo	Riyadh	英語の首都名です。
geo.lat	geo	23.7167	国の中心点の緯度です。
geo.lng	geo	44.1167	国の中心点の経度です。
geo.area_km2	geo	2149690	面積（平方キロメートル）です。
geo.population	geo	36973555	人口です。
geo.population_year	geo	2025	人口の数値の対象年です。
geo.timezones	geo	["Asia/Riyadh"]	IANA タイムゾーン名です。
geo.driving_side	geo	right	左側通行または右側通行です。
locale	locale		ロケールの慣習です。
locale.languages	locale	[{"code":"ar","name_ar":"العربية","na...	公用語です。話者数の多い順に並びます。
locale.languages[].code	locale	ar	BCP 47 言語コードです。
locale.languages[].name_ar	locale	العربية	アラビア語での言語名です。
locale.languages[].name_en	locale	Arabic	英語での言語名です。
locale.week_start	locale	sun	週の開始曜日です（sun、mon、sat など）。
locale.weekend	locale	["fri","sat"]	週末の曜日です。
locale.calendars	locale	["gregorian","islamic-umalqura","isla...	使用される暦です。優先度の高い順に並びます（gregorian、islamic-umalqura など）。
locale.measurement	locale	metric	metric、us、uk のいずれかです。
address	address		郵便住所の慣習です。
address.postal_code_format	address	#####	郵便番号の形式です。# は数字、@ は英字を表します。
address.postal_code_regex	address	^(?:\d{5})$	有効な郵便番号に一致する正規表現です。
address.postal_code_example	address	11564	郵便番号の例です。
address.address_format	address	%N%n%O%n%A%n%C %Z	住所テンプレートです。%N は氏名、%O は組織名、%A は番地、%D は地区、%C は市区町村、%S は地域、%Z は郵便番号、%X は仕分けコード、%n は改行を表します。
address.region_label_ar	address	null	最上位の地域区分をアラビア語で何と呼ぶかを示します。
address.region_label_en	address	null	最上位の地域区分を何と呼ぶかを示します（state、province、emirate など）。
travel	travel		旅行情報です。
travel.emergency	travel		公的な情報源で確認された緊急電話番号です。サービスが null の場合は general に電話してください。
travel.emergency.police	travel	999	警察です。
travel.emergency.ambulance	travel	997	救急車です。
travel.emergency.fire	travel	998	消防および民間防衛です。
travel.emergency.general	travel	911	全サービス共通の番号です（112、911、999 など）。
travel.plug_types	travel	["G"]	IEC のプラグ形状を示す文字です（A～N）。
travel.voltage	travel	[220,230]	一般家庭の電源電圧です。
travel.frequency_hz	travel	[60]	電源周波数（ヘルツ）です。
sports	sports		スポーツコードです。
sports.fifa	sports	KSA	FIFA の国コードです。
sports.ioc	sports	KSA	IOC の国コードです。
subdivisions.iso2	subdivisions	SA	国コードです。
subdivisions.code	subdivisions	SA-01	ISO 3166-2 コードです（SA-01）。
subdivisions.name_ar	subdivisions	منطقة الرياض	アラビア語の名称です。
subdivisions.name_en	subdivisions	Riyadh	英語の名称です。
subdivisions.parent	subdivisions	null	入れ子になった地域区分の場合、その親地域区分の ISO 3166-2 コードです。

よくある質問

アラビア語の国の一覧を取得するにはどうすればよいですか？ data/worldref.ar.json（名前のみの場合は data/modules/core.ar.json）を使用してください。各行の name はアラビア語です。すぐに使える選択リストの順序にするには、sort で並べ替えてください（「ال」とハムザの表記を無視します）。

アラビア語の男性形・女性形の国籍一覧はどこにありますか？ data/modules/nationality.json にあります。nationality_ar_m（سعودي）と nationality_ar_f（سعودية）、さらに nationality_en（Saudi）が含まれています。

サウジアラビアの携帯電話番号を検証するにはどうすればよいですか？ parsePhone(input, byIso2("SA")) を使用し、valid && mobile を確認してください。ルールは phone[0].mobile_pattern にあります。先頭の 0 を除いた後、50、51、53～59で始まる9桁の数字です。アラビア数字も使用できます。

一部の国で travel.emergency.police が null なのはなぜですか？ 公式情報源で確認できた番号のみを公開しています。サービスが null の場合は、general に電話してください。

商用利用できますか？ はい。コードは MIT ライセンスです。データのライセンス（Unicode、Apache-2.0、CC-BY-4.0、CC0、パブリックドメイン）はすべて、必要な場合に帰属表示を行えば商用利用が可能です。LICENSE をご覧ください。

どのくらい最新ですか？ 自動ジョブが上流の情報源を毎月（人口データは四半期ごとに）確認し、変更があり、すべてのテストに合格した場合にパッチをリリースします。バージョンは data/meta.json に記載されています。

AI エージェント向け

llms.txt と AGENTS.md から始めてください。スキーマは schema/ にあります。MCP サーバー（npx -y worldref mcp）は get_country、search_countries、validate_phone、list_subdivisions を提供します。データのみを根拠に回答し、null は不明として扱ってください。

ロードマップ

1.2.0 で予定されている新機能（後方互換性あり）：

1. 公式のアラビア語名：現在222行が空欄で、データの最大の不足項目です。
2. 両言語での行政区画の種類（region、province、emirate、state）。
3. より柔軟な検索：句読点なしや軽微な誤字を含む名前（「cote divoire」、「Kuwiat」など）。
4. 住所フォームのヘルパー：ある国の住所フォームの項目、順序、ラベルをアラビア語または英語で提供します。
5. JitPack に加え、Maven Central での Kotlin の提供。
6. 都市：アラビア語名と英語名を含み、各国および行政区画に紐付けられた新しい cities モジュール。

情報源とライセンス

コード：MIT。データ：Unicode CLDR 49（Unicode-3.0）、Google libphonenumber v9.0.42 および住所メタデータ（Apache-2.0、改変あり）、World Bank（CC-BY-4.0）、Wikidata（CC0）、CIA World Factbook 最終版および IANA（パブリックドメイン）、flag-icons（MIT）、緊急電話番号に関する政府の公式情報源。全文は LICENSES/ をご覧ください。列ごとの情報源とすべての編集上の判断については、data/sources.json をご覧ください。

引用方法：CITATION.cff をご覧ください。