# Countries States Cities Database
A comprehensive, community-maintained dataset of **countries, states, counties, cities, and postcodes** — published in 12 formats and free under the [Open Database License](LICENSE) **(attribution required)**.
[](LICENSE)
[](https://github.com/dr5hn/countries-states-cities-database/stargazers)
[](https://www.npmjs.com/package/@countrystatecity/countries)
[](https://pypi.org/project/countrystatecity-countries/)
Total Regions : 6
Total Sub Regions : 22
Total Countries : 250
Total States/Regions/Municipalities : 5,299
Total Cities/Towns/Districts : 153,765
Total Postcodes : 725993 (116 countries)
Total Timezones : 427 (100% IANA coverage)
Last Updated On: October 19, 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.
```bash
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:
```bash
pip install countrystatecity-api
export CSC_API_KEY="YOUR_API_KEY"
```
```python
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 →**](https://app.countrystatecity.in/?utm_source=github&utm_medium=repository&utm_campaign=python_packages&utm_content=upstream_readme) ·
[Compare plans](https://countrystatecity.in/pricing/?utm_source=github&utm_medium=repository&utm_campaign=python_packages&utm_content=upstream_readme) ·
[Documentation](https://docs.countrystatecity.in/api/introduction?utm_source=github&utm_medium=repository&utm_campaign=python_packages&utm_content=upstream_readme) ·
[Interactive playground](https://playground.countrystatecity.in/) ·
[OpenAPI spec](https://github.com/dr5hn/csc-swagger) ·
[Status](https://status.countrystatecity.in/)
### Export Tool — `export.countrystatecity.in`
Build tailored datasets in your browser — pick country, region, format, and field selection, then download.
[**Launch the Export Tool →**](https://export.countrystatecity.in/)
---
## Other ways to use the data
NPM (JavaScript / TypeScript)
| Package | GitHub | NPM |
|---------|--------|-----|
| `@countrystatecity/countries` | [GitHub](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/countries) | [npmjs.com](https://www.npmjs.com/package/@countrystatecity/countries) |
| `@countrystatecity/countries-browser` | [GitHub](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/countries-browser) | [npmjs.com](https://www.npmjs.com/package/@countrystatecity/countries-browser) |
| `@countrystatecity/currencies` | [GitHub](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/currencies) | [npmjs.com](https://www.npmjs.com/package/@countrystatecity/currencies) |
| `@countrystatecity/timezones` | [GitHub](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/timezones) | [npmjs.com](https://www.npmjs.com/package/@countrystatecity/timezones) |
| `@countrystatecity/translations` | [GitHub](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/translations) | [npmjs.com](https://www.npmjs.com/package/@countrystatecity/translations) |
| `@countrystatecity/cli` | [GitHub](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/cli) | [npmjs.com](https://www.npmjs.com/package/@countrystatecity/cli) |
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](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/api) | [pypi.org](https://pypi.org/project/countrystatecity-api/) |
| `countrystatecity-countries` | Offline snapshot | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/countries) | [pypi.org](https://pypi.org/project/countrystatecity-countries/) |
| `countrystatecity-timezones` | Offline snapshot | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/timezones) | [pypi.org](https://pypi.org/project/countrystatecity-timezones/) |
| `countrystatecity-currencies` | Offline snapshot | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/currencies) | [pypi.org](https://pypi.org/project/countrystatecity-currencies/) |
| `countrystatecity-translations` | Offline snapshot | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/translations) | [pypi.org](https://pypi.org/project/countrystatecity-translations/) |
| `countrystatecity-phonecodes` | Offline snapshot | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/phonecodes) | [pypi.org](https://pypi.org/project/countrystatecity-phonecodes/) |
| `countrystatecity-regions` | Offline snapshot | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/regions) | [pypi.org](https://pypi.org/project/countrystatecity-regions/) |
| `countrystatecity-postal-codes` | Offline snapshot | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/postal_codes) | [pypi.org](https://pypi.org/project/countrystatecity-postal-codes/) |
Direct download (gzipped exports)
Countries, states, counties, cities, and postcodes are separate datasets. Counties contain official intermediate
administrative units; cities can link to them through a nullable `county_id`. See
[the county field shape and link rules](contributions/counties/README.md).
Every format ships as a `.gz` asset on each [GitHub Release](https://github.com/dr5hn/countries-states-cities-database/releases).
```bash
curl -LO https://github.com/dr5hn/countries-states-cities-database/releases/latest/download/json-cities.json.gz
gunzip json-cities.json.gz
curl -LO https://github.com/dr5hn/countries-states-cities-database/releases/latest/download/json-counties.json.gz
gunzip json-counties.json.gz
```
Smaller reference files (countries, states, counties, schema) live in the repo. Use `git clone --depth 1` for a fast clone.
Other packages and platforms
- [Database browser](https://demo.countrystatecity.in/) — query and explore live data
- [Encyclopedia](https://countrystatecity.org/) — country profiles and insights
- [Community Manager](https://manager.countrystatecity.in/) — submit corrections via web UI
- [CLI](https://cli.countrystatecity.in/) — terminal access
- [Kaggle](https://www.kaggle.com/datasets/darshangada/countries-states-cities-database/data) · [Data.world](https://data.world/dr5hn/country-state-city)
---
## What's in the data
- **250** countries · **5,329** states / regions · **14,058** counties · **153,513** cities · **840k+** postcodes across 125 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](https://github.com/toon-format/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](https://manager.countrystatecity.in/) — 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/`, `contributions/counties/`, 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. If it removes, repurposes or restores ids, include its reviewed
[ledger events keyed by `event_pr`](migrations/README.md#a-data-pr-carries-its-own-events) in that same PR.
The `Ledger migrations` check validates the merge preview; all ids must be final at that preview.
```json
{
"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](contributions/README.md) ·
[Contribution guidelines](.github/CONTRIBUTING.md) ·
[Multi-level territories policy](MULTI_LEVEL_TERRITORIES.md) ·
[Data versioning](DATA_VERSIONING.md) ·
[Disputed and special territories](DISPUTED_AND_SPECIAL_TERRITORIES.md) ·
[Administrative structure policy](ADMINISTRATIVE_STRUCTURE.md) ·
[The `cities.type` field](TYPE_FIELD.md)
> 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)](LICENSE). 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
```
Some records also carry names or points copied from open sources that ask for credit: [GeoNames](https://www.geonames.org/)
([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)), © [OpenStreetMap contributors](https://www.openstreetmap.org/copyright)
(ODbL 1.0) and [Wikidata](https://www.wikidata.org/wiki/Wikidata:Licensing) (CC0). Points are selected per record and
rounded to eight decimals; the per-record source ledgers are in [.github/fixes-docs/ledgers/](.github/fixes-docs/ledgers/).
Official registers matched to records (categories, codes and unit names) also ask for credit:
- [Statistical Office of the Slovak Republic](https://slovak.statistics.sk/wps/portal/ext/aboutus/webpage/terms/), register of spatial units REGPJ (CC BY 4.0)
- [Geodetska uprava Republike Slovenije](https://www.e-prostor.gov.si/dostopi/javni-dostop/) (GURS), register of spatial units RPE, 13 October 2026 (CC BY 4.0)
- [Maa- ja Ruumiamet](https://geoportaal.maaamet.ee/est/Ruumiandmed/Haldus-ja-asustusjaotus-p119.html), administrative and settlement division, 2 September 2026 (public data terms)
- [Central Statistics Office](https://www.cso.ie/en/aboutus/whoweare/copyrightpolicy/) and Tailte Éireann, Census 2022 built-up areas (CC BY 4.0)
- [Stats NZ](https://www.stats.govt.nz/about-us/copyright/), territorial authorities and urban-rural areas 2026 (CC BY 4.0): this work is based on Stats NZ data licensed for reuse under CC BY 4.0
- Ville de Luxembourg, quartiers on [data.public.lu](https://data.public.lu/) (CC BY 4.0)
- [Ministry for Development of Communities and Territories of Ukraine](https://mindev.gov.ua/), Codifier of administrative-territorial units and territories of territorial communities (KATOTTG), 7 July 2026 (CC BY 4.0): names and codes matched to records; CSC romanised the names under Cabinet of Ministers Resolution 55 (2010)
- [Statistics South Africa](https://www.statssa.gov.za/), Census 2011 main places, distributed by UCT Libraries: main-place codes and classes matched to records; the mapping to `type` is CSC's
Country names in some languages follow [Unicode CLDR](https://cldr.unicode.org/) 48.2: Copyright © 2015-2024 Unicode, Inc., under the [Unicode License v3](.github/licenses/Unicode-3.0.txt), whose notice must travel with copies.
Source credits and notices for 63 sources are in [.github/licenses/SOURCES.txt](.github/licenses/SOURCES.txt); export releases attach it with the other notices. The register also identifies 233 sources whose redistribution basis remains under review. Keep the applicable credits and notices when redistributing the data.
---
## Support
If this project saves you time, please consider supporting its continued maintenance.
[](https://github.com/sponsors/dr5hn)
[](https://ko-fi.com/dr5hn)
You can also [plant a tree](https://ecologi.com/darshangada?r=60f2a36e67efcb18f734ffb8) 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](https://github.com/dr5hn/countries-states-cities-database/issues).
---
**Thanks to our [contributors](https://github.com/dr5hn/countries-states-cities-database/graphs/contributors).**
