DOCSEARCHbyAlgolia
Submit Docs

countries-states-cities-database

repository·master·Indexed 27 days ago

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

A comprehensive, community-maintained dataset of countries, states, cities, and postcodes. It provides tools for exporting data into JSON, CSV, XML, YAML, SQL Server, NPM package, and Apple PLIST formats. The project includes a PHP CLI for database migrations and exports, as well as Python scripts for bidirectional synchronization between MySQL and JSON, DuckDB conversion, and IANA timezone mapping.

Tokens
11.2K
Snippets
47
Records
75
Agent score
95%

What's inside countries-states-cities-database

  1. Understand the Multi-Level Territories Policy

    master

    The database implements a dual-representation policy for certain overseas and autonomous territories to comply with ISO 3166 standards. These entities appear simultaneously as standalone ISO 3166-1 countries and as ISO 3166-2 subdivisions of a parent state.

    Data Structure

    For a multi-level territory (e.g., Martinique):

    1. Country Level: A row exists in countries.json with its own id, iso2, and iso3 (e.g., MQ).
    2. State Level: A row exists in states.json where country_code points to the parent (e.g., FR) and iso2/state_code matches the territory.
    3. City Level: Cities in cities/<TERRITORY_ISO2>.json reference both the territory's country_id and the territory's state_id (as a subdivision of the parent).

  2. Seed the database with geographical data

    master

    To populate your database with the comprehensive geographical data (regions, subregions, countries, states, and cities), run the seeding script.

    Note: The seeding process may take a significant amount of time due to the volume of data. Ensure you have a stable internet connection as the script fetches data from GitHub.

    npm run seed

  4. Add a new city to the database

    master

    To add a new city, navigate to contributions/cities/ and open the JSON file corresponding to the country (e.g., US.json for the United States). Append the new city object to the end of the array.

    Important: Do NOT include an id field for new cities; the build system assigns these automatically.

    {
    "name": "New City Name",
    "state_id": 1234,
    "state_code": "CA",
    "country_id": 1,
    "country_code": "US",
    "latitude": "37.77490000",
    "longitude": "-122.41940000",
    "timezone": "America/Los_Angeles"
}

  5. Download gzipped data exports directly

    master

    You can download the full dataset as gzipped .gz assets from the GitHub Releases page. For example, to download and extract the JSON cities dataset:

    curl -LO https://github.com/dr5hn/countries-states-cities-database/releases/latest/download/json-cities.json.gz
gunzip json-cities.json.gz

  6. Add a new region or subregion

    master

    Regions and subregions are added via their respective JSON files in the contributions/ directory. Omit the id field for both as it is auto-assigned.

    • Regions: Edit contributions/regions/regions.json.
    • Subregions: Edit contributions/subregions/subregions.json and include the region_id.
    // Region Example
{
    "name": "New Region",
    "translations": {
        "es": "Nueva Región"
    }
}

// Subregion Example
{
    "name": "New Subregion",
    "region_id": 1,
    "translations": {
        "es": "Nueva Subregión"
    }
}

  7. Create a new PHP CLI command

    master

    To add a new command to the bin/console interface:

    1. Create a new class in the bin/Commands/ directory.
    2. Extend Symfony\Component\Console\Command\Command.
    3. Implement configure() to set the name and description.
    4. Implement execute() for the command logic.
    5. Register the command in bin/console.
    <?php
namespace bin™Commands;

use Symfony™Component™Console™Command™Command;
use Symfony™Component™Console™Input™InputInterface;
use Symfony™Component™Console™Output™OutputInterface;

class NewExportCommand extends Command
{
    protected static $defaultName = 'export:new-format';
    protected static $defaultDescription = 'Export data to new format';

    protected function configure(): void
    {
        $this->setHelp('This command exports the database to a new format');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // Implementation
        return Command::SUCCESS;
    }
}