Full Database of city state country available in 11+ formats: JSON, MYSQL, PSQL, SQLITE, SQLSERVER, XML, YAML, MONGODB, CSV, GEOJSON, TOON & more. All Countries, States & Cities are Covered & Populated with Different Combinations & Versions.

• ✅ Most Comprehensive - 153K+ cities from 250 countries with 100% timezone coverage & 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, GeoJSON, Toon - 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: Use git clone --depth 1 for faster cloning (shallow clone ~1.5GB vs ~9GB 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';
const usStates = State.getStatesOfCountry('US');

📖 NPM Documentation · 📂 GitHub

pip install countrystatecity

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

from countrystatecity import Country, State, City
us_states = State.get_states_of_country('US')

📖 PyPI Package · 📂 GitHub

Dedicated timezone data package for JavaScript/TypeScript applications:

npm install @countrystatecity/timezones

📂 GitHub Repository

🎉 Introducing REST API for Countries States Cities Database.

API

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 - Lightweight data interchange format
• MYSQL - MySQL database dumps with complete schema
• PSQL - PostgreSQL database exports
• SQLITE - Portable, self-contained database files
• SQLSERVER - Microsoft SQL Server compatible scripts
• MONGODB - NoSQL document collections + dump
• XML - Structured markup language format
• YAML - Human-readable configuration format
• CSV - Spreadsheet-compatible tabular data

• GEOJSON - RFC 7946 standard for geographic features (Point geometry)
• TOON - Token-Oriented Object Notation for LLM consumption (~40% fewer tokens vs JSON) 📖 Format Spec

• DuckDB - Convert from SQLite files using provided script (not auto-generated). See Export to DuckDB for instructions.

Legend: ✅ = Available | NA = Not applicable for this format

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

Total Regions : 6
Total Sub Regions : 22
Total Countries : 250
Total States/Regions/Municipalities : 5,299
Total Cities/Towns/Districts : 153,765
Total Timezones : 427 (100% IANA coverage)

Last Updated On: December 13, 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 in contributions/ → 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 file
tar -xzvf world-mongodb-dump.tar.gz

# Then restore the MongoDB dump
mongorestore --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 database
python3 bin/scripts/export/import_duckdb.py --input sqlite/world.sqlite3 --output duckdb/world.db

# Convert individual table databases
python3 bin/scripts/export/import_duckdb.py --input sqlite/regions.sqlite3 --output duckdb/regions.db
python3 bin/scripts/export/import_duckdb.py --input sqlite/subregions.sqlite3 --output duckdb/subregions.db
python3 bin/scripts/export/import_duckdb.py --input sqlite/countries.sqlite3 --output duckdb/countries.db
python3 bin/scripts/export/import_duckdb.py --input sqlite/states.sqlite3 --output duckdb/states.db
python3 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.

💡 Format Recommendations:

• Web/Mobile Apps: Use JSON or CSV for easy parsing
• Databases: Import SQL, PSQL, or SQLite files directly
• GIS/Mapping: Use GeoJSON for Leaflet, Mapbox, or PostGIS
• AI/LLM Projects: Use TOON format to reduce token usage by ~40%
• Analytics: SQLite for ready-to-use queries, or convert to DuckDB for advanced analytics

• 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+ (with PyMySQL), Composer, 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 Database
https://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 in contributions/ directory (cities, states, or countries)
3. Omit id, 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 | Maintainer Docs

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

As always, thanks to our amazing contributors!

Made with contrib.rocks.

Contribute towards better earth buy the world a tree

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

Suggestions & Feedbacks are Most Welcome
gadadarshan[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 - see LICENSE for details.

Report issues: GitHub Issues

That's all Folks. Enjoy! 🌍