Countries States Cities Database

A comprehensive, community-maintained dataset of countries, states, cities, and postcodes — published in 12 formats and free under the Open Database License (attribution required).

Total Regions : 6
Total Sub Regions : 22
Total Countries : 250
Total States/Regions/Municipalities : 5,299
Total Cities/Towns/Districts : 153,765
Total Postcodes : 844248 (125 countries)
Total Timezones : 427 (100% IANA coverage)
Last Updated On: July 29, 2026

---

---

Recommended for production

The two managed products below are the fastest path to shipping. They're actively maintained, billed for sustainability, and back the rest of the ecosystem.

REST API — api.countrystatecity.in

Query countries, states, cities, and postcodes from any language. Free tier for prototyping; paid tiers for production.

curl https://api.countrystatecity.in/v1/countries/IN/states/MH/cities \
  -H "X-CSCAPI-KEY: $YOUR_API_KEY"

Python applications can use the official sync and async client:

pip install countrystatecity-api
export CSC_API_KEY="YOUR_API_KEY"

from countrystatecity import CountryStateCity

with CountryStateCity() as client:
    states = client.get_states_of_country("IN")
    print([state["name"] for state in states[:3]])

Get a free API key → · Compare plans · Documentation · Interactive playground · OpenAPI spec · Status

Export Tool — export.countrystatecity.in

Build tailored datasets in your browser — pick country, region, format, and field selection, then download.

Launch the Export Tool →

---

Other ways to use the data

NPM (JavaScript / TypeScript)

Package	GitHub	NPM
@countrystatecity/countries	GitHub	npmjs.com
@countrystatecity/countries-browser	GitHub	npmjs.com
@countrystatecity/currencies	GitHub	npmjs.com
@countrystatecity/timezones	GitHub	npmjs.com
@countrystatecity/translations	GitHub	npmjs.com
@countrystatecity/cli	GitHub	npmjs.com

PyPI (Python)

Use countrystatecity-api for live, managed data. The suffixed packages are versioned offline snapshots.

Package	Use	GitHub	PyPI
countrystatecity-api	Live REST API client	GitHub	pypi.org
countrystatecity-countries	Offline snapshot	GitHub	pypi.org
countrystatecity-timezones	Offline snapshot	GitHub	pypi.org
countrystatecity-currencies	Offline snapshot	GitHub	pypi.org
countrystatecity-translations	Offline snapshot	GitHub	pypi.org
countrystatecity-phonecodes	Offline snapshot	GitHub	pypi.org
countrystatecity-regions	Offline snapshot	GitHub	pypi.org
countrystatecity-postal-codes	Offline snapshot	GitHub	pypi.org

Direct download (gzipped exports)

Every format ships as a .gz asset on each GitHub Release.

curl -LO https://github.com/dr5hn/countries-states-cities-database/releases/latest/download/json-cities.json.gz
gunzip json-cities.json.gz

Smaller reference files (countries, states, schema) live in the repo. Use git clone --depth 1 for a fast clone.

Other packages and platforms

• Database browser — query and explore live data
• Encyclopedia — country profiles and insights
• Community Manager — submit corrections via web UI
• CLI — terminal access
• Kaggle · Data.world

---

What's in the data

• 250 countries · 5,299 states / regions · 153,765 cities · 100k+ postcodes across ~50 countries
• 19 languages of country and state names plus native script
• 100% IANA timezone coverage for cities
• Validated foreign keys on every contribution
• Formats: JSON, MySQL, PostgreSQL, SQLite, SQL Server, MongoDB, XML, YAML, CSV, GeoJSON, TOON (LLM-optimised, ~40% fewer tokens than JSON), Parquet (columnar, analytics-ready)

Format	Export time	Size	Compressed
CSV	1s	40 MB	9 MB
MongoDB dump	1s	30 MB	20 MB
MySQL SQL	3s	86 MB	22 MB
JSON	4s	271 MB	18 MB
TOON	5s	23 MB	20 MB
Parquet	7s	31 MB	27 MB
GeoJSON	8s	208 MB	24 MB
XML	9s	91 MB	15 MB
YAML	17s	68 MB	—
SQLite	45s	89 MB	—

---

Contributing

The easiest way is the Community Manager — submit corrections through a web UI with end-to-end tracking.

To edit JSON directly:

1. Fork and clone (git clone --depth 1).
2. Edit files under contributions/cities/, contributions/states/, contributions/countries/, or contributions/postcodes/.
3. Required for new cities: name, state_id, state_code, country_id, country_code, latitude, longitude. Optional: timezone, wikiDataId, native.
4. Omit id, created_at, updated_at, flag — auto-managed on import.
5. Open a pull request with a clear data source.

{
  "name": "San Francisco",
  "state_id": 1416,
  "state_code": "CA",
  "country_id": 233,
  "country_code": "US",
  "latitude": "37.77493",
  "longitude": "-122.41942",
  "timezone": "America/Los_Angeles",
  "wikiDataId": "Q62"
}

Contributions guide · Contribution guidelines · Multi-level territories policy · The cities.type field

Don't edit the auto-generated directories (json/, csv/, xml/, yml/, sql/, etc.). They're rebuilt from MySQL on every release.

---

License and attribution

Licensed under the Open Database License (ODbL v1.0). Commercial use, modification, and redistribution all permitted. Attribution is required, and derivatives must be shared under the same license.

Data by Countries States Cities Database
https://github.com/dr5hn/countries-states-cities-database | ODbL v1.0

---

Support

If this project saves you time, please consider supporting its continued maintenance.

You can also plant a tree on behalf of the project.

Reach out: gadadarshan [at] gmail [dot] com

Sponsors

Disclaimer

Community-maintained data may contain errors or lag behind geopolitical changes. Verify critical data with official sources. Report issues.

---

Thanks to our contributors.