# dr5hn/countries-states-cities-database

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/dr5hn-countries-states-cities-database).**

9,291 stars · 2,964 forks · Python · odbl-1.0

## Links

- GitHub: https://github.com/dr5hn/countries-states-cities-database
- Homepage: http://countrystatecity.in/
- awesome-repositories: https://awesome-repositories.com/repository/dr5hn-countries-states-cities-database.md

## Topics

`cities` `countries` `country` `csv` `geographical-data` `psql` `regions` `state` `states` `world`

## Description

This project is a comprehensive geographic location dataset and reference library providing standardized data for countries, states, and cities. It serves as a source of truth for regional hierarchies, ISO codes, coordinates, and timezone information, available as both a relational SQL database and a document-based JSON library.

The project includes a custom dataset export tool that functions as a filtering engine. This allows for the generation of tailored geographic files in JSON, CSV, and GeoJSON formats by selecting only the specific regions or fields required.

The dataset covers global address validation and the implementation of cascading dropdown menus for user profiles and shipping addresses. It supports the deployment of location data across multiple relational and document database platforms, as well as integration via SDKs and APIs to retrieve city, state, and country metadata.

## Tags

### Data & Databases

- [Geographic Datasets](https://awesome-repositories.com/f/data-databases/geographic-datasets.md) — Ships comprehensive geographic datasets in multiple formats for integration into external systems. ([source](https://docs.countrystatecity.in/))
- [City Data](https://awesome-repositories.com/f/data-databases/city-data.md) — Provides city-level data including coordinates and timezones filtered by country or state. ([source](https://docs.countrystatecity.in/api/introduction))
- [Geographic Data](https://awesome-repositories.com/f/data-databases/data-retrieval/geographic-data.md) — Provides a comprehensive dataset of countries, states, and cities including ISO codes and timezones. ([source](https://docs.countrystatecity.in/))
- [Embedded Geographic Datasets](https://awesome-repositories.com/f/data-databases/embedded-geographic-datasets.md) — Allows applications to access localized geographical information and type-safe models without making network requests. ([source](https://docs.countrystatecity.in/))
- [Geographic Data APIs](https://awesome-repositories.com/f/data-databases/geographic-data-apis.md) — Provides standardized endpoints and search terms to retrieve detailed information about countries, cities, and timezones. ([source](https://cdn.jsdelivr.net/gh/dr5hn/countries-states-cities-database@master/README.md))
- [Geographic Dataset Downloads](https://awesome-repositories.com/f/data-databases/geographic-dataset-downloads.md) — Provides raw geographic data in SQL, JSON, CSV, and GeoJSON formats for local storage or analysis. ([source](https://cdn.jsdelivr.net/gh/dr5hn/countries-states-cities-database@master/README.md))
- [Geographic Reference Data](https://awesome-repositories.com/f/data-databases/geographic-reference-data.md) — Serves as a source of truth for implementing regional hierarchies and validating user profiles.
- [Hierarchical Data Models](https://awesome-repositories.com/f/data-databases/hierarchical-data-models.md) — Organizes global location data into a strict parent-child hierarchy from regions down to cities.
- [Geographic Metadata](https://awesome-repositories.com/f/data-databases/retrieval-metadata/geographic-metadata.md) — Provides hierarchical datasets of regions and cities including population data. ([source](https://docs.countrystatecity.in/database/schema))
- [State and Province Data](https://awesome-repositories.com/f/data-databases/state-and-province-data.md) — Provides lists of states, provinces, and regions filtered by country. ([source](https://docs.countrystatecity.in/api/introduction))
- [Data Export](https://awesome-repositories.com/f/data-databases/data-export.md) — Allows users to generate custom data exports by selecting only the required fields and formats. ([source](https://docs.countrystatecity.in/tools/overview))
- [Custom Dataset Filtering](https://awesome-repositories.com/f/data-databases/data-export-formats/custom-dataset-filtering.md) — Provides a filtering engine to generate tailored geographic files in JSON, CSV, or SQL.
- [Geographic](https://awesome-repositories.com/f/data-databases/data-processing-pipelines/data-serialization/json-libraries/geographic.md) — Provides document-based JSON data files for embedding location information directly into applications.
- [Geographic Database Deployments](https://awesome-repositories.com/f/data-databases/geographic-database-deployments.md) — Enables the deployment of comprehensive location data across multiple relational and document database platforms. ([source](https://docs.countrystatecity.in/llms.txt))
- [Geographic SQL Databases](https://awesome-repositories.com/f/data-databases/geographic-sql-databases.md) — Provides a relational SQL data source for populating databases with regional hierarchies and population statistics.
- [Custom Dataset Generators](https://awesome-repositories.com/f/data-databases/in-memory-data-stores/columnar-formats/custom-dataset-generators.md) — Ships a filtering engine to generate tailored geographic files in JSON, CSV, and GeoJSON formats.
- [Dataset Exporters](https://awesome-repositories.com/f/data-databases/in-memory-data-stores/columnar-formats/dataset-exporters.md) — Provides a browser-based tool to export tailored datasets by selecting specific countries, regions, and fields. ([source](https://cdn.jsdelivr.net/gh/dr5hn/countries-states-cities-database@master/README.md))
- [Geographic Data Exporters](https://awesome-repositories.com/f/data-databases/query-translators/multi-format-exports/geographic-data-exporters.md) — Provides a filtering engine to generate tailored geographic files in JSON, CSV, and GeoJSON formats.
- [Relational-to-Document Conversions](https://awesome-repositories.com/f/data-databases/tabular-data-frameworks/relational-transformations/relational-to-document-conversions.md) — Converts normalized SQL database tables into JSON, CSV, and GeoJSON formats for diverse application use.

### Part of an Awesome List

- [Country and Regional Data](https://awesome-repositories.com/f/awesome-lists/data/country-and-regional-data.md) — Offers comprehensive libraries for retrieving regional, international, and postal data. ([source](https://docs.countrystatecity.in/api/sdks))
- [Data Import Packages](https://awesome-repositories.com/f/awesome-lists/data/data-import-packages.md) — Provides language-specific packages to easily import standardized country, state, and city datasets into projects. ([source](https://cdn.jsdelivr.net/gh/dr5hn/countries-states-cities-database@master/README.md))
- [Geographic and Location](https://awesome-repositories.com/f/awesome-lists/data/geographic-and-location.md) — Provides a comprehensive dataset of countries, states, and cities with ISO codes and coordinates.

### Development Tools & Productivity

- [Dataset Contribution Workflows](https://awesome-repositories.com/f/development-tools-productivity/dataset-contribution-workflows.md) — Implements a community workflow for submitting geographical corrections and updates subject to review. ([source](https://docs.countrystatecity.in/llms.txt))
- [Multi-Format Data Exports](https://awesome-repositories.com/f/development-tools-productivity/multi-format-data-exports.md) — Supports exporting geographic datasets into various relational, document, and exchange formats for different technology stacks. ([source](https://docs.countrystatecity.in/database/overview))

### Software Engineering & Architecture

- [Contribution Workflows](https://awesome-repositories.com/f/software-engineering-architecture/contribution-workflows.md) — Manages community contributions to the dataset through a standardized validation and review process.
- [Version-Controlled Datasets](https://awesome-repositories.com/f/software-engineering-architecture/version-controlled-datasets.md) — Implements a review-based workflow using version control to maintain the accuracy of geographic datasets.

### User Interface & Experience

- [Address Validation](https://awesome-repositories.com/f/user-interface-experience/address-validation.md) — Serves as a source of truth for verifying regional hierarchies and postal data during address input.
- [Cascading Selectors](https://awesome-repositories.com/f/user-interface-experience/navigation-components/dropdown-menus/cascading-selectors.md) — Supports the implementation of dependent selectors for country-state-city regional hierarchies.
- [Dependent Selectors](https://awesome-repositories.com/f/user-interface-experience/selection-management-components/dependent-selectors.md) — Enables the creation of dependent dropdown menus where parent location choices filter available child options. ([source](https://docs.countrystatecity.in/api/examples))

### Web Development

- [Static Data Distributions](https://awesome-repositories.com/f/web-development/static-asset-management/static-data-distributions.md) — Distributes geographic data as pre-compiled static files and modules to eliminate runtime network dependencies.