Repository files navigation

Full Database of city state country available in JSON, MYSQL, PSQL, SQLITE, SQLSERVER, XML, YAML, MONGODB & CSV format.All Countries, States & Cities are Covered & Populated with Different Combinations & Versions.

• ✅Most Comprehensive - 151,024+ cities from 250 countries with timezone & multilingual support (19 languages)
• ✅Multiple Integration Options - NPM/PyPI packages, REST API, Export Tool, or direct downloads
• ✅Production Ready - Trusted by thousands of developers, monthly updates
• ✅Every Format You Need - JSON, SQL, MongoDB, CSV, XML, YAML - use what fits your stack
• ✅100% Free & Open Source - ODbL licensed, no usage restrictions, developer-friendly

Save hundreds of hours collecting and maintaining geographical data. Get accurate, structured, ready-to-use data right now.

📦 Clone Tip: Usegit clone --depth 1 for faster cloning (~1.2GB vs 5.4GB full history)

• CSC Platform Ecosystem •Integration Methods •Official Packages
• API •Export Tool •Available Formats
• Demo •Insights •Architecture
• Performance •License •Contributing
• Platforms •Support

Easily access all the tools and services in the Countries States Cities platform:

npm install @countrystatecity/countries

Features: Zero dependencies, TypeScript support, offline-first, tree-shakeable

import{Country,State,City}from'@countrystatecity/countries';constusStates=State.getStatesOfCountry('US');

📖NPM Documentation · 📂GitHub

pip install countrystatecity

Features: Easy-to-use Python interface, works with Django/Flask, offline data access

fromcountrystatecityimportCountry,State,Cityus_states=State.get_states_of_country('US')

📖PyPI Package · 📂GitHub

Dedicated timezone data package for JavaScript/TypeScript applications:

npm install @countrystatecity/timezones

📂GitHub Repository

🎉 IntroducingREST API for Countries States Cities Database.

API Documentation

Export Tool - Convert and download data in your preferred format

Features: Multiple formats, flexible selection, custom filtering by region/country, bulk downloads, real-time processing

• JSON
• MYSQL
• PSQL
• SQLITE
• SQLSERVER
• MONGODB
• XML
• YAML
• CSV

Note: DuckDB format is available via manual conversion from SQLite files. See theExport to DuckDB section for instructions.

Legend: ✅ = Available | 🗜️ = Compressed (.gz) version also available

https://dr5hn.github.io/countries-states-cities-database/

Total Regions : 6
Total Sub Regions : 22
Total Countries : 250
Total States/Regions/Municipalities : 5,038
Total Cities/Towns/Districts : 151,024
Total Timezones : 423 (97.9% IANA coverage)

Last Updated On : 18th Oct 2025

Two-phase build system: JSON (version control) → MySQL (canonical) → All export formats

📝 contributions/ → [Python Import] → 🗄️ MySQL → [PHP Export] → 📦 json/, csv/, xml/, sql/, etc.

For Contributors: Edit JSON files incontributions/ → Submit PR → GitHub Actions auto-generates all exports (no local setup needed!)

For Maintainers: MySQL as single source of truth, dynamic schema detection, one command to regenerate all formats

For Users: All formats guaranteed in sync, compressed downloads available (.gz)

How to import MongoDB database?

# First extract the tar.gz filetar -xzvf world-mongodb-dump.tar.gz# Then restore the MongoDB dumpmongorestore --host localhost:27017 --db world mongodb-dump/world

Want to export the database to DuckDB format? You can easily convert the existing SQLite files to DuckDB format using our conversion script.

First, install DuckDB Python package:

pip install duckdb

Use the provided conversion script to convert SQLite files to DuckDB format:

# Convert the complete world databasepython3 bin/scripts/export/import_duckdb.py --input sqlite/world.sqlite3 --output duckdb/world.db# Convert individual table databasespython3 bin/scripts/export/import_duckdb.py --input sqlite/regions.sqlite3 --output duckdb/regions.dbpython3 bin/scripts/export/import_duckdb.py --input sqlite/subregions.sqlite3 --output duckdb/subregions.dbpython3 bin/scripts/export/import_duckdb.py --input sqlite/countries.sqlite3 --output duckdb/countries.dbpython3 bin/scripts/export/import_duckdb.py --input sqlite/states.sqlite3 --output duckdb/states.dbpython3 bin/scripts/export/import_duckdb.py --input sqlite/cities.sqlite3 --output duckdb/cities.db

The conversion script will create DuckDB database files that maintain the same structure and data as the original SQLite files, optimized for analytical workloads.

• Countries: ~50ms | States: ~180ms | Cities by State: ~80ms | Search: ~120ms

• Contributors: Git + text editor (no local setup needed)
• Maintainers: PHP 8.0+, MySQL 5.7+, Python 3.8+, 4GB RAM, 10GB disk
• End Users: No requirements - just download!

Open Database License (ODbL) - 100% free and open source!

✅ Use commercially, modify freely, share openly • 📝 Just give credit and keep derivatives open

Quick Attribution:

Data by Countries States Cities Databasehttps://github.com/dr5hn/countries-states-cities-database | ODbL v1.0

Use our web tool to browse, search, and submit data change requests with a streamlined review process.

1. Fork & clone:git clone --depth 1 https://github.com/YOUR_USERNAME/countries-states-cities-database.git
2. Edit files incontributions/ directory (cities, states, or countries)
3. Omitid,created_at,updated_at,flag fields (auto-managed)
4. Include required fields:name,state_id,state_code,country_id,country_code,latitude,longitude
5. Submit PR with clear description and data source

Example city:

{"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"}

📖Full guide:contributions/README.md |Contribution Guidelines

Note: Only edit JSON incontributions/ - GitHub Actions auto-generates all export formats!

As always, thanks to our amazing contributors!

Made withcontrib.rocks.

Contribute towards better earthbuy the world a tree

Find and use this dataset across the web - choose the platform that fits your workflow:

Suggestions & Feedbacks are Most Welcomegadadarshan[at]gmail[dot]com

While we strive for accuracy, this community-maintained database may contain errors or not reflect latest geopolitical changes. Users should verify critical data with official sources and use at their own discretion. Licensed under ODbL - seeLICENSE for details.

Report issues:GitHub Issues

That's all Folks. Enjoy! 🌍