dr5hn /countries-states-cities-database

🌍 Discover our global repository of countries, states, and cities! 🏙️ Get comprehensive data in JSON, SQL, PSQL, SQLSERVER, MONGODB, SQLITE, XML, YAML, and CSV formats. Access ISO2, ISO3 codes, country code, capital, native language, timezones (for countries), and more. #countries #states #cities

★ 10,021⑂ 3,051👁 106⑃ 1,450● 695▤ 147
PythonODbL-1.0Created 2018-07-20countrystatecity.in/
Download: v5.2.0-export.1v5.2.0-export.1 ↓12026-11-03
+8
Daily
10,021
stars
3,051
forks
106
watchers
1,450
prs
695
issues
147
releases

README

!banner

 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 (attribution required).



!release





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

---


  
  


---

 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 → ·
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)

Countries, states, counties, cities, and postcodes are separate datasets. Counties contain official intermediate
administrative units; cities can li

Top issues

Discussions

Latest release

v5.2.0-export.1 v5.2.0-export.1 2026-11-03
v5.2.0-export.1 - November 03, 2026

Data export build for v5.2.0.

 Data Statistics
- Regions: 6
- Subregions: 22
- Countries: 250
- States: 5327
- Counties: 14058
- Cities: 156169
- Postcodes: 728556

 Formats
JSON, MySQL, PostgreSQL, SQLite, SQL Server, XML, YAML, CSV, GeoJSON, Toon, MongoDB, Parquet

 Licence and credits
ODbL 1.0, attribution required. Some values come from sources that ask for credit (see the README). Their
notices are attached as NOTICE-.txt and must be kept with every copy of this data.

 Migration files
Each migrations-from-.tar.gz says how ids changed since that relea

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON