Database architecture
This reference describes the SQLite export in v5.2.0-export.1, published 3 November 2026. Types, indexes, constraints and file layout can differ between export formats and releases. Inspect the source file you install. The underlying dataset links regions, subregions, countries, states, counties, city records and postcodes. A city can have a null state link; city names are not unique identifiers. Coordinates describe points, not boundary polygons or validated delivery addresses.Export column names and SDK model attributes can differ. For this snapshot, country records use
phonecode, states use iso2, and cities use state_code. The Python package models expose phone_code and state_code for some of those fields. Do not infer SQL column names from an API response or package model.Core tables
regions
The pinned SQLite snapshot contains 6 rows.subregions
The pinned SQLite snapshot contains 22 rows.countries
The pinned SQLite snapshot contains 250 rows.states
The pinned SQLite snapshot contains 5,327 rows.counties
The pinned SQLite snapshot contains 14,058 rows.county_states
The pinned SQLite snapshot contains 16 rows.cities
The pinned SQLite snapshot contains 156,169 rows.postcodes
The pinned SQLite snapshot contains 728,556 rows.Relationships and constraints
subregions.region_idlinks toregions.id.- Countries can link to a region and subregion through
region_idandsubregion_id. states.country_idlinks tocountries.id. Subdivision classifications and hierarchy levels vary by country.cities.country_idlinks tocountries.id;cities.state_idandcities.county_idcan be null.- A county can use
counties.state_idand/or additional rows incounty_states. Preserve both when looking up county-to-state relationships. - Postcodes carry a required country link and optional state/city links. Read the postcode reference for coverage and validation limits.
Foreign key constraints
Inspect and verify constraints in the export for your engine. In SQLite:foreign_key_check returns violations; no rows means no violations were found. The checked snapshot returns no rows.
Common queries
Country and state names are joined from their tables rather than read from nonexistentcities.country_name or cities.state_name columns:
Data types by platform
SQLite stores JSON-bearing fields such astranslations and timezones as text in this snapshot. PostgreSQL, MySQL, MongoDB and other exports can represent these values differently. Check nulls and parse JSON only when the value is present and valid.
SQL Server uses tables in the world schema inside the selected database, such as world.cities. PostgreSQL uses public.cities. Use the appropriate engine syntax; SQL dialects and import formats are not interchangeable.