This repository provides a comprehensive, multi-format database of countries, states, and cities, saving developers and researchers significant time. It offers accurate geographical data in 11 formats, catering to diverse technical stacks and integration needs with a focus on open-source accessibility.

How It Works

The project uses a two-phase build system: JSON files are the canonical source, processed into MySQL, and then exported to all other formats, ensuring consistency. Contributors edit JSON files and submit PRs, triggering GitHub Actions to auto-generate exports, simplifying the workflow.

Quick Start & Requirements

• Installation: Via NPM (npm install @countrystatecity/countries), PyPI (pip install countrystatecity), REST API (countrystatecity.in), or direct downloads.
• Prerequisites: Standard environments for NPM/PyPI. Contributors need Git/text editor. Maintainers require PHP 8.0+, MySQL 5.7+, Python 3.8+, 4GB RAM, 10GB disk. End-users have no specific requirements.
• Links: Documentation (docs.countrystatecity.in), Demo (demo.countrystatecity.in), API (countrystatecity.in), Export Tool (export.countrystatecity.in).

Highlighted Details

• Data Scope: Covers 250 countries, 5,299 states, 153,765 cities, with 100% IANA timezone coverage and 19-language support.
• Format Variety: Supports JSON, MYSQL, PSQL, SQLITE, SQLSERVER, MONGODB, XML, YAML, CSV, GEOJSON, and TOON (optimized for LLMs, ~40% token reduction).
• Integration: Offers NPM/PyPI packages, a REST API, and an export tool for flexible data access.
• Performance: Fast exports (CSV ~1s, MongoDB ~1s) and responsive API (Countries ~50ms).

Maintenance & Community

Actively maintained via GitHub PRs. Data change requests can be submitted through a web tool. Community feedback is welcomed via email. A status page monitors uptime.

Licensing & Compatibility

Licensed under Open Database License (ODbL) v1.0. It permits commercial use, modification, and distribution, provided attribution is given and derivatives are shared under the same license.

Limitations & Caveats

As a community resource, data accuracy may vary; users should verify critical information. Certain combined data formats (e.g., Country+States) are exclusively available in JSON.