countries-states-cities-database

Disputed and special territories

This page sets out how the database records places where sovereignty, recognition or administration is disputed or unusual, and how far the data follows that policy today. It applies to countries, states, counties and cities. Related pages: ADMINISTRATIVE_STRUCTURE.md (units and levels) and MULTI_LEVEL_TERRITORIES.md (territories that are both a country and a subdivision).

Policy

Codes are lookups, not rulings. Country and subdivision codes give stable geographic lookups. A code, country name, subdivision entry, flag, dialing code, translation or timezone does not express a position on recognition, sovereignty, a territorial claim or the legal status of a settlement.

Code catalogues. ISO 3166-1 and ISO 3166-2 are the default catalogues. XK (with XKX and 926) is a documented extension used for Kosovo; it is not an ISO assignment. Subdivision codes that ISO does not publish (Kosovo’s seven XK-* codes, Hong Kong’s eighteen HK-* district codes) are project codes. A national reform that takes effect before ISO updates its list is recorded with its effective date, its official sources and a crosswalk from the old units to the new ones.

One place partition per case. Each place record has one country, under the case rules below. A subdivision of another country that covers the same ground stays in the states list as a catalogue entry, with no places from the other country under it. A unit that overlaps a special territory only partly may still hold verified places of its own country. Names and suffixes such as (EH) and (EH-partial) are not boundary evidence. A place is never stored twice to satisfy two claims.

Case Places belong to Overlapping catalogue entries
Taiwan TW: 22 states, 377 cities. CN-TW (state 2255) is an empty catalogue entry: its 20 unit rows (159996 to 160015) retired in #2057, each mapped to its TW state. The Japanese and Chinese country translations use the CLDR 48.2.0 form 台湾 (v5). None.
Hong Kong, Macao HK: 18 districts, 27 cities. MO: no states or cities yet (a coverage gap). CN-HK (state 2267) and CN-MO (2266) are empty catalogue entries: the 18 CN-HK district rows (159978 to 159995) retired in #2057, each mapped to its HK state. Fill the MO coverage gap.
Western Sahara EH: no states (no ISO subdivisions); 3 cities with no state in EH.json, Gueltat Zemmour 67127, Imlili 67134 and Smara 67220 (#2057, ids kept). The province rows 67064, 67089, 67154, 67182 and 67115 retired to their Moroccan states. EH coordinate bounds added. None.
Kosovo XK Serbia’s RS-KM and RS-25 to RS-29
Crimea, Sevastopol and other places in Ukraine UA none
Abkhazia, South Ossetia GE none
Transnistria MD none
Northern Cyprus CY none
Nagorno-Karabakh AZ none
Golan Heights SY none
Somaliland SO none
Kashmir the IN, PK or CN unit that administers the place none
Arunachal Pradesh IN none
Falkland Islands; South Georgia and the South Sandwich Islands FK, GS Argentina’s county 6832 Islas del Atlántico Sur, an administrative-claim entry; it does not assign these places to AR
Gibraltar GI none
West Bank, including East Jerusalem PS none
Åland AX see the status table

Names. Country display names follow a documented, versioned convention based on Unicode CLDR (edition 48.2.0 for this policy), including deliberately chosen short or variant forms: the English name for PS from v5 is CLDR’s short form “Palestine”. Each change records the CLDR edition, locale and key it used; a same-entity form that differs from the CLDR default is not an error for that reason alone. A translation that names a different entity is an error and is corrected in an ordinary release. Changing a translation that names the right entity with a political qualifier is a display-convention change: the owner checks the proposed forms and their effect on apps first, the change is announced in advance, and it ships in the next major release, because apps display these names and some markets require a particular form. native is the place’s attested local name in its own script; other local or historical forms go in translations where that language has a key. A translation names the same place in that language; it does not move the place to another country. The full naming rule is in contributions/README.md.

Clocks, dialing codes and flags. timezone follows the IANA time zone database, which can differ from a country’s usual zone (Crimea uses Europe/Simferopol). Dialing codes follow the ITU allocations and flags encode the stored code. None of these is evidence of sovereignty or of a place’s identity.

No invented codes. No country or ISO subdivision code is made up to fill a gap. The Cyprus sovereign base areas have no code; a place proved to lie only inside a base area needs its own documented exception first.

Changes. Regular data releases correct facts about the same places under the published model, including moving a proved misfiled record to its right country or state; query results change as facts are corrected. Within a major, every existing id keeps working; a crosswalk alone does not achieve that. Removing ids, moving a record to another dataset or scope, changing how a country or case is stored, and incompatible schema or query-rule changes ship only in a major release, coordinated across the exports, API and packages. A unit record stays distinct from its seat town, and both ids of a proved duplicate stay until the removal ships in a major. Every release names its fixed data snapshot, which is never overwritten, and carries its removal mappings and changed fields; a mapping says whether it is the same place merged, an administrative seat, a move to another dataset, a split or an invalid record. Ids are never reused for a different place.

Status on master

The policy above is the target. This table shows where the data stands today, so nobody reads it as a claim that every record already complies.

Case Today Still to do
Taiwan TW: 22 states, 377 cities. CN-TW (state 2255) is an empty catalogue entry: its 20 unit rows (159996 to 160015) retired in #2057, each mapped to its TW state. The Japanese and Chinese country translations use the CLDR 48.2.0 form 台湾 (v5). None.
Hong Kong, Macao HK: 18 districts, 27 cities. MO: no states or cities yet (a coverage gap). CN-HK (state 2267) and CN-MO (2266) are empty catalogue entries: the 18 CN-HK district rows (159978 to 159995) retired in #2057, each mapped to its HK state. Fill the MO coverage gap.
Western Sahara EH: no states (no ISO subdivisions); 3 cities with no state in EH.json, Gueltat Zemmour 67127, Imlili 67134 and Smara 67220 (#2057, ids kept). The province rows 67064, 67089, 67154, 67182 and 67115 retired to their Moroccan states. EH coordinate bounds added. None.
Kosovo XK: 7 states, 59 cities. Serbia’s six Kosovo units, states 5688 to 5693, hold no places. None.
Palestine PS: 16 states, 132 cities. English name “Palestine” (CLDR 48.2.0 short form) and the CLDR short forms of the ru, uk, pl, hi and ar translations (v5); the former name “Palestinian Territory Occupied” stays machine-readable as the before value in the migration files’ changed_fields.jsonl. East Jerusalem’s point fixed in #2009. Har Adar (57475) and Modiin Ilit (57514) moved to PS in #2012. Nirit (57526) and Bāqa el Gharbīya (164832) stay held for boundary review; the whole of Jerusalem stays a record distinct from its parts.
Ukraine Crimea and Sevastopol: 369 cities under UA, all on Europe/Simferopol since #2009. The ten “Gorodskoy okrug …” unit rows (109610 to 109619) retired in #2057 as the seat of their town. Reopen the 286 Crimean and Sevastopol records held in #2005 under the current Ukrainian codifier (KATOTTG), its enacted names and romanisation. All 286 still exist; 285 still share a Wikidata item with another record, and 110403 needs its own identity check.
Cyprus CY: 6 states, 96 cities. Turkish country name “Kıbrıs” since #2009. None.
Georgia, Moldova, Azerbaijan, Syria, Somalia Places stored under GE, MD, AZ, SY, SO. Membership is kept. Local-name, item, scope and clock reviews remain open where found, including dated renaming research in Azerbaijan for Askyaran (8046), Martakert (8114) and Novyy Karanlug (8125). Somalia’s state 5700 has the native name Maroodi Jeex, the name the Somaliland administration uses; whether it covers the same ground as ISO’s Woqooyi Galbeed is under review.
Kashmir, Arunachal Pradesh Places stored under IN, PK and CN units. Not yet checked place by place.
Falkland Islands; South Georgia and the South Sandwich Islands FK and GS have no states or cities yet (coverage gaps). Argentina’s county 6832 has no cities linked to it. Coverage is incomplete; county 6832’s point source and represented scope are under review.
Gibraltar GI has no states or cities yet (a coverage gap). Coverage is incomplete.
Åland AX: 16 states, 12 cities. Finland’s state 1509 (FI-01, Åland Islands) is a catalogue entry with no places. None: 1509 was restored as the same entity it denoted before #1144; #1144’s removal of duplicate Finnish place rows stands, so Åland’s places stay under AX.

Counts and ids are from contributions/ on master at dea03811 (13 October 2026), except the restoration of state 1509 (FI-01) in #2020. They describe stored rows, not complete coverage or a finished place-by-place check of identity, language, clock or point source. Changes already made have their sources and record ids in FIX_1643_SUMMARY.md; open work is listed here.

Earlier methods replaced from 13 October 2026

Older fix notes record the method used at the time; they do not authorise repeating it.

Past decisions this policy keeps