Indexed by TopGit from live GitHub metadata: dr5hn/countries-states-cities-database has 10.0k stars, written primarily in Python. 🌍 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
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
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).
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.
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 link to them through a nullable county_id. See
the county field shape and link rules.
Every format ships as a .gz asset on each GitHub Release.
The easiest way is the Community Manager — submit corrections through a web UI with end-to-end tracking.
To edit JSON directly:
Fork and clone (git clone --depth 1).
Edit files under contributions/cities/, contributions/states/, contributions/countries/, contributions/counties/, or contributions/postcodes/.
Required for new cities: name, state_id, state_code, country_id, country_code, latitude, longitude. Optional: timezone, wikiDataId, native.
Omitid, created_at, updated_at, flag — auto-managed on import.
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.
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
Statistical Office of the Slovak Republic, register of spatial units REGPJ (CC BY 4.0)
Geodetska uprava Republike Slovenije (GURS), register of spatial units RPE, 13 October 2026 (CC BY 4.0)
Maa- ja Ruumiamet, administrative and settlement division, 2 September 2026 (public data terms)
Central Statistics Office and Tailte Éireann, Census 2022 built-up areas (CC BY 4.0)
Stats NZ, 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 (CC BY 4.0)
Ministry for Development of Communities and Territories of Ukraine, 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, Census 2011 main places, distributed by UCT Libraries: main-place codes and classes matched to records; the mapping to type is CSC's
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.
You can also plant a tree 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.
How active is development on dr5hn/countries-states-cities-database?
The most recent commit recorded on dr5hn/countries-states-cities-database was 3 months ago, based on the GitHub push timestamp. The repository has 3.1k forks — one of the better signals of community interest.
How many stars does dr5hn/countries-states-cities-database have?
dr5hn/countries-states-cities-database has 10.0k GitHub stars — refresh the page for the live number, or check github.com/dr5hn/countries-states-cities-database. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What language is dr5hn/countries-states-cities-database written in?
dr5hn/countries-states-cities-database is written primarily in Python. GitHub's language field is based on the largest share of bytes in the default branch.
What license does dr5hn/countries-states-cities-database use?
dr5hn/countries-states-cities-database is released under the ODbL-1.0 license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
What topics is dr5hn/countries-states-cities-database associated with?
GitHub's repository topics for dr5hn/countries-states-cities-database: "cities", "countries", "country", "csv", "geographical-data", "psql", "regions", "state", "states", "world". TopGit's editorial category is open-source.
Where can I see dr5hn/countries-states-cities-database in action?
The project maintains a homepage at http://countrystatecity.in/. The README tab on this page also usually contains screenshots and a quickstart.
Where do I read more about dr5hn/countries-states-cities-database?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/dr5hn/countries-states-cities-database is the definitive source.
Read full README in the tab above.
Curious whether countries-states-cities-database is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about countries-states-cities-database.