This directory contains the source JSON files for contributing to the Countries States Cities Database.
contributions/
βββ regions/
β βββ regions.json (6 regions)
βββ subregions/
β βββ subregions.json (22 subregions)
βββ countries/
β βββ countries.json (250 countries)
βββ states/
β βββ states.json (5,000+ states/provinces)
βββ cities/
βββ AD.json (Andorra cities)
βββ US.json (United States cities)
βββ IN.json (India cities)
βββ ... (209 country files)
Find the country file: Navigate to contributions/cities/ and open the file for your country (e.g., US.json for United States)
Add your city at the end of the array:
{
"name": "New City Name",
"state_id": 1234,
"state_code": "CA",
"country_id": 1,
"country_code": "US",
"latitude": "37.77490000",
"longitude": "-122.41940000",
"timezone": "America/Los_Angeles"
}
β οΈ Important: Do NOT include an id field for new cities! The build system will automatically assign IDs.
id field{
"id": 1234, β Keep this unchanged!
"name": "Updated City Name", β Edit as needed
"state_id": 1234,
"state_code": "CA",
...
}
Edit contributions/countries/countries.json and add your country:
{
"name": "New Country",
"iso2": "NC",
"iso3": "NCO",
"capital": "Capital City",
...
}
Note: Omit the id field for new countries - it will be auto-assigned.
Edit contributions/states/states.json and add your state:
{
"name": "New State",
"country_id": 1,
"country_code": "US",
"state_code": "NS",
...
}
Note: Omit the id field for new states - it will be auto-assigned.
Edit contributions/regions/regions.json and add your region:
{
"name": "New Region",
"translations": {
"es": "Nueva RegiΓ³n"
}
}
Note: Omit the id field for new regions - it will be auto-assigned.
Edit contributions/subregions/subregions.json and add your subregion:
{
"name": "New Subregion",
"region_id": 1,
"translations": {
"es": "Nueva SubregiΓ³n"
}
}
Note: Omit the id field for new subregions - it will be auto-assigned.
For External Contributors:
Simply create a pull request with your JSON changes! You donβt need to run any build scripts locally.
What happens after you submit:
Important:
contributions/ directory| Field | Required | Description | Example |
|---|---|---|---|
id |
Auto | Unique identifier (omit for new cities) | 1234 |
name |
β Yes | Official city name | "San Francisco" |
state_id |
β Yes | ID of parent state; null only for a city of a country with no states (e.g. Western Sahara), together with state_code |
1416 |
state_code |
β Yes | ISO code of parent state; null exactly when state_id is null |
"CA" |
country_id |
β Yes | ID of parent country | 233 |
country_code |
β Yes | ISO2 code of parent country | "US" |
latitude |
β Yes | Latitude coordinate | "37.77490000" |
longitude |
β Yes | Longitude coordinate | "-122.41940000" |
timezone |
No | IANA timezone | "America/Los_Angeles" |
translations |
No | Name translations object | {"es": "San Francisco"} |
wikiDataId |
No | WikiData identifier | "Q62" |
created_at |
No | Creation timestamp (ISO 8601) | "2019-10-05T23:18:06" |
updated_at |
No | Last update timestamp (ISO 8601) | "2025-10-08T14:42:36" |
flag |
Auto | Active status flag (managed by system) | 1 |
Note: The created_at and updated_at fields are optional. If omitted, MySQL will use default values. When provided, use ISO 8601 format with βTβ separator.
Timezone Support: The timezone field uses IANA timezone identifiers. If omitted for new cities, it can be automatically populated using the bin/scripts/validation/add_timezones.py script, which determines the timezone from latitude/longitude coordinates.
name is the placeβs English or international name (#1379).native is the recordβs attested local name in the language and script used locally, from a source whose terms allow
it to be redistributed. In India, use the recordβs own code-matched local-language name in the LGD where it exists, or
a licensed official local naming source, and keep a verified Hindi form in translations.hi. Where several local
languages apply, say in the PR which one you chose and why, and keep the other attested local forms in their language
keys. Never pick a script from the country or state alone. If the evidence is missing, stale, about a namesake or
unresolved, hold the record; never fill the gap with a machine transliteration.translations hold only an attested name of this same place in that language: from a licensed naming source, or a
checked label on the placeβs own, verified Wikidata item. Check the recordβs identity and scope, what the label means
and the language key; an item match alone is not enough. A language may use the placeβs name unchanged, if that form
is attested. For new or actively reviewed values, leave out a key with no attested name; consumers should fall back
to name. Unresolved existing name copies follow the
evidence-led transition. Do not
machine-translate, and do not copy a label from another place (for example Kazanβs name on a village called
Kazanskaya).translations follow the versioned Unicode CLDR convention, with its documented short and
variant choices, in DISPUTED_AND_SPECIAL_TERRITORIES.md. A naming PR records
the CLDR edition, locale and key it used.To find the correct state_id and state_code:
contributions/states/states.jsonid and iso2 valuesExample:
{
"id": 1416,
"name": "California",
"country_id": 233,
"country_code": "US",
"state_code": "CA",
"iso2": "US-CA"
}
To find the correct country_id and country_code:
contributions/countries/countries.jsonid and iso2 valuesExample:
{
"id": 233,
"name": "United States",
"iso2": "US",
"iso3": "USA"
}
contributions/ directoryThank you for contributing! π