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
+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 liTop issues
#2153[Data clarification]: Original identities and coordinates of Lagong (161578) and Sungai Tengi (161597), Selangor7 comments · 2026-10-31#2052Volunteering to maintain: M49 backfill, China division codes & city/district hierarchy4 comments · 2026-10-16#1627[Feature]: Translation for country capitals and currency names3 comments · 2026-09-14#2051[Feature]: Add national administrative division codes (division_code) to states and cities2 comments · 2026-10-16#1643Data-correctness audit of cities: wrong coordinates, states, duplicates2 comments · 2026-09-29#2197[Data Addition]: Add missing counties in El Oro, Ecuador1 comments · 2026-11-12
Discussions
#1354Open API Spec1 comments · 2026-03-21#1344Wrong data in json but correct data in contributions folder1 comments · 2026-02-02#1325Find country when I only know the city name?1 comments · 2025-12-24#1211Special Thanks: Countries-States-Cities Database by Dr5hn0 comments · 2025-10-17#1126wikidataid is wrong for a lot of cities0 comments · 2025-10-13#1116Kosovo cities1 comments · 2025-10-08#1104state_code field missing in states1 comments · 2025-09-25#1029New Feature regarding0 comments · 2025-05-19
Latest release
v5.2.0-export.1 v5.2.0-export.1 2026-11-03v5.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