🌍 Countries States Cities Database

Full Database of city state country available in 11 formats: JSON, MYSQL, PSQL, SQLITE, SQLSERVER, XML, YAML, MONGODB, CSV, GEOJSON & TOON. 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 (~1.2GB vs 5.4GB full history)

Table of Contents

• 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
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 Documentation

🛠️ 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

• DuckDB - Available via manual conversion from SQLite files. 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 : 423 (100% IANA coverage)

Last Updated On : 03th Dec 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: DuckDB or SQLite for fast analytical queries

API Response Times (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+, 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

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

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.

Sponsors

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