🌍 Countries States Cities Database

release size

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.

Why Choose This Database?

✅ 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

🌐 CSC Platform Ecosystem

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

Tool	Description	Link
NPM Package	Official JavaScript/TypeScript package	@countrystatecity/countries
Encyclopedia	Browse geographical data and country profiles	countrystatecity.org
Documentation	Complete API documentation and guides	docs.countrystatecity.in
Demo Database	Browse the full database online	demo.countrystatecity.in
API Service	Programmatic access to countries, states, cities	countrystatecity.in
Export Tool	Export data in multiple formats	export.countrystatecity.in
Update Tool	Submit and track data change requests	manager.countrystatecity.in
Status Page	Real-time service uptime and incidents	status.countrystatecity.in

🔄 Choose Your Integration Method

Method	Setup	Best For	Offline	Cost
NPM/PyPI Package	< 1 min	JS/TS/Python apps, offline use	✅	Free
REST API	< 5 min	Production apps, real-time data, any language	❌	Free tier + paid
Export Tool	< 2 min	Custom datasets, specific regions	❌	Free + credits
Direct Download	Immediate	SQL databases, one-time imports, legacy systems	✅	Free

📦 Official Packages

JavaScript/TypeScript (NPM)

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

Python (PyPI)

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

Timezones Package

Dedicated timezone data package for JavaScript/TypeScript applications:

npm install @countrystatecity/timezones

📂 GitHub Repository

API 🚀

🎉 Introducing REST API for Countries States Cities Database.

API

🛠️ Export Tool

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

Available Formats

Core Formats

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

Geographic & AI-Optimized Formats

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

Optional Formats (Manual Conversion Required)

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

Distribution Files Info

File	JSON	MYSQL	PSQL	SQLITE	SQLSERVER	MONGODB	XML	YAML	CSV	GEOJSON	TOON
Regions	✅	✅	✅	✅	✅	✅	✅	✅	✅	NA	NA
Subregions	✅	✅	✅	✅	✅	✅	✅	✅	✅	NA	NA
Countries	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
States	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Cities	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Country+States	✅	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA
Country+Cities	✅	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA
Country+State+Cities/World	✅	✅	✅	✅	✅	✅	NA	NA	NA	NA	NA

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

Demo

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

Insights

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

Repository Architecture

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)

Import MongoDB

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

Export to DuckDB

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

Prerequisites

First, install DuckDB Python package:

pip install duckdb

Convert SQLite to 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.

Performance & Benchmarks

Export Performance

Format	Export Time	World DB Size	Compressed (.gz)
CSV	~1s	40 MB	9 MB (fastest)
JSON	~4s	271 MB	18 MB
MongoDB	~1s	30 MB	20 MB (dump)
SQL	~3s	86 MB	22 MB
SQLite	~45s	89 MB	-
XML	~9s	91 MB	15 MB
YAML	~17s	68 MB	-
GeoJSON	~8s	208 MB	24 MB
Toon	~5s	23 MB	20 MB

💡 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

API Response Times (Estimated Average)

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

System Requirements

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!

📄 License

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

Contributing

🛠️ Easy Way: CSC Update Tool

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

📝 Manual Way: Edit JSON Files Directly

Fork & clone: git clone --depth 1 https://github.com/YOUR_USERNAME/countries-states-cities-database.git
Edit files in contributions/ directory (cities, states, or countries)
Omit id, created_at, updated_at, flag fields (auto-managed)
Include required fields: name, state_id, state_code, country_id, country_code, latitude, longitude
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!

Repo Activity

As always, thanks to our amazing contributors!

Made with contrib.rocks.

Make the world more Greener 🌴

Contribute towards better earth buy the world a tree

🌐 Available On Multiple Platforms

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

Platform	Best For	Access
📚 Encyclopedia	Browse country profiles, geographical data	Visit Encyclopedia
📊 Kaggle Dataset	Data science, ML projects, notebooks	Download on Kaggle
🗃️ Data.world	Data collaboration, business analytics	View on Data.world
📦 NPM Registry	JavaScript/TypeScript developers	`npm install @countrystatecity/countries`
🐙 GitHub	Contributors, raw files, issue tracking	View Repository
🌍 API Service	Production apps, real-time access	Get API Key
🛠️ Export Tool	Custom exports, specific formats	Launch Tool
📊 Status Page	Service uptime monitoring, incidents	Check Status

Follow me at

🙋‍♂️ Support My Work

Suggestions / Feedbacks

Suggestions & Feedbacks are Most Welcome
gadadarshan[at]gmail[dot]com

Disclaimer

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! 🌍

AI Architecture Analysis

Embed this Badge

Repository Summary (README)