A comprehensive, community-maintained dataset of countries, states, cities, and postcodes — published in 11 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 : 660,381 (79 countries)
Total Timezones : 427 (100% IANA coverage)
Last Updated On: April 28, 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"Get an API key → · 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.
Other ways to use the data
NPM (JavaScript / TypeScript)
npm install @countrystatecity/countries
import { Country, State, City } from '@countrystatecity/countries'; const usStates = State.getStatesOfCountry('US');
PyPI (Python)
pip install countrystatecity-countries
from countrystatecity_countries import Country, State, City us_states = State.get_states_of_country('US')
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
@countrystatecity/countries-browser— CDN-loaded, lazy@countrystatecity/timezones— dedicated timezone data- 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)
| 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 |
| 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:
- Fork and clone (
git clone --depth 1). - Edit files under
contributions/cities/,contributions/states/,contributions/countries/, orcontributions/postcodes/. - Required for new cities:
name,state_id,state_code,country_id,country_code,latitude,longitude. Optional:timezone,wikiDataId,native. - Omit
id,created_at,updated_at,flag— auto-managed on import. - 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
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.