# 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](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 : 844248 (125 countries)
Total Timezones : 427 (100% IANA coverage)
Last Updated On: June 21, 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"
```
[**Get an API key →**](https://countrystatecity.in/) ·
[Documentation](https://docs.countrystatecity.in/) ·
[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)
| Package | GitHub | PyPI |
|---------|--------|------|
| `countrystatecity-countries` | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/countries) | [pypi.org](https://pypi.org/project/countrystatecity-countries/) |
| `countrystatecity-timezones` | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/timezones) | [pypi.org](https://pypi.org/project/countrystatecity-timezones/) |
| `countrystatecity-currencies` | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/currencies) | [pypi.org](https://pypi.org/project/countrystatecity-currencies/) |
| `countrystatecity-translations` | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/translations) | [pypi.org](https://pypi.org/project/countrystatecity-translations/) |
| `countrystatecity-phonecodes` | [GitHub](https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/phonecodes) | [pypi.org](https://pypi.org/project/countrystatecity-phonecodes/) |
Direct download (gzipped exports)
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
```
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](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,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](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/`, 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.
```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) ·
[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
```
---
## 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).**
