countries-states-cities-database

![banner](.github/images/banner.png) # 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](/countries-states-cities-database/LICENSE) **(attribution required)**. [![License: ODbL-1.0](https://img.shields.io/badge/License-ODbL--1.0-brightgreen.svg?style=flat-square)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/dr5hn/countries-states-cities-database.svg?style=flat-square)](https://github.com/dr5hn/countries-states-cities-database/stargazers) ![release](https://img.shields.io/github/v/release/dr5hn/countries-states-cities-database?style=flat-square) [![NPM](https://img.shields.io/npm/v/@countrystatecity/countries.svg?style=flat-square&label=npm)](https://www.npmjs.com/package/@countrystatecity/countries) [![PyPI](https://img.shields.io/pypi/v/countrystatecity-countries.svg?style=flat-square&label=pypi)](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 : 728556 (117 countries)
Total Timezones : 427 (100% IANA coverage)
Last Updated On: November 14, 2026


Build & Launch Websites Faster with MakeMySiteLive Finding a remote job? Go check remotegig.in


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](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](/countries-states-cities-database/contributions/counties/). 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

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/, 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 in that same PR. The Ledger migrations check validates the merge preview; all ids must be final at that preview.
{
  "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 · Data versioning · Disputed and special territories · Administrative structure 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

Some records also carry names or points copied from open sources that ask for credit: GeoNames (CC BY 4.0), © OpenStreetMap contributors (ODbL 1.0) and Wikidata (CC0). Points are selected per record and rounded to eight decimals; the per-record source ledgers are in .github/fixes-docs/ledgers/. Official registers matched to records (categories, codes and unit names) also ask for credit:

Country names in some languages follow Unicode CLDR 48.2: Copyright © 2015-2024 Unicode, Inc., under the Unicode License v3, whose notice must travel with copies.

Source credits and notices for 63 sources are in .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.

Sponsor on GitHub Buy a coffee

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

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

GitHub @dr5hn Twitter @dr5hn LinkedIn @dr5hn

Sponsors

Disclaimer

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


![Repo Activity](https://repobeats.axiom.co/api/embed/635051d1a8be17610a967b7b07b65c0148f13654.svg) **Thanks to our [contributors](https://github.com/dr5hn/countries-states-cities-database/graphs/contributors).**