Repository: dr5hn/countries-states-cities-database
Stars: 9442
README.md
🌍 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. Large exports (.gz) are on GitHub Releases, not in git.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 |
| 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 |
| CLI Tool | Command-line interface for querying CSC data | cli.countrystatecity.in |
| OpenAPI Spec | Swagger/OpenAPI specification for the REST API | GitHub |
| API Playground | Interactive Swagger UI to test API endpoints | playground.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/countriesFeatures: 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 countrystatecityFeatures: 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
Browser Package
Lightweight browser-native package with CDN lazy loading:
npm install @countrystatecity/countries-browserFeatures: jsDelivr CDN, lazy loading, no bundled data, browser-optimized
📂 GitHub
Timezones Package
Dedicated timezone data package for JavaScript/TypeScript applications:
npm install @countrystatecity/timezonesAPI 🚀
🎉 Introducing REST API for Countries States Cities Database.
🛠️ 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
Downloads
Large export files are distributed via GitHub Releases (not committed to git) to keep the repository lightweight.
Download the latest exports:
Example: download cities JSON
curl -LO https://github.com/dr5hn/countries-states-cities-database/releases/latest/download/json-cities.json.gz
gunzip json-cities.json.gzSmall files (countries, states, regions, subregions, schema) remain in the repo and can be accessed directly via raw.githubusercontent.com.
Demo
https://dr5hn.github.io/countries-states-cities-database/
Insights
Total Regions : 6 <br>
Total Sub Regions : 22 <br>
Total Countries : 250 <br>
Total States/Regions/Municipalities : 5,299 <br>
Total Cities/Towns/Districts : 153,765 <br>
Total Timezones : 427 (100% IANA coverage) <br>
Last Updated On: March 28, 2026
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 on GitHub Releases
Import MongoDB
Download the MongoDB dump from GitHub Releases and import:
Download from latest release
curl -LO https://github.com/dr5hn/countries-states-cities-database/releases/latest/download/mongodb-world-mongodb-dump.tar.gzExtract and restore
tar -xzvf mongodb-world-mongodb-dump.tar.gz
mongorestore --host localhost:27017 --db world mongodb-dump/worldExport 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 duckdbConvert 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.dbConvert 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.dbThe 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.0Contributing
🛠️ 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 | Maintainer Docs
Note: Only edit JSON in contributions/ - GitHub Actions auto-generates all export formats!
Repo Activity
As always, thanks to our amazing contributors!
<a href="https://github.com/dr5hn/countries-states-cities-database/graphs/contributors">
<img src="https://contrib.rocks/image?repo=dr5hn/countries-states-cities-database&anon=1" />
</a>
Made with contrib.rocks.
Sponsors
<p align="center">
<a href="https://cdn.jsdelivr.net/gh/dr5hn/static/sponsors.svg">
<img src='https://cdn.jsdelivr.net/gh/dr5hn/static/sponsors.svg'/>
</a>
</p>
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
<a href="https://github.com/dr5hn/"><img alt="Github @dr5hn" src="https://img.shields.io/static/v1?logo=github&message=Github&color=black&style=flat-square&label=" /></a> <a href="https://twitter.com/dr5hn/"><img alt="Twitter @dr5hn" src="https://img.shields.io/static/v1?logo=twitter&message=Twitter&color=black&style=flat-square&label=" /></a> <a href="https://www.linkedin.com/in/dr5hn/"><img alt="LinkedIn @dr5hn" src="https://img.shields.io/static/v1?logo=linkedin&message=LinkedIn&color=black&style=flat-square&label=&link=https://twitter.com/dr5hn" /></a>
🙋♂️ Support My Work
Suggestions / Feedbacks
Suggestions & Feedbacks are Most Welcome
gadadarshan[at]gmail[dot]comDisclaimer
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! 🌍