Skip to content

Thereabouts data dictionary

Thereabouts is an offline geocoder. A Parquet dataset holds the open data; binary packs built from it answer lookups through the Python, Node and command-line clients and the MCP server. This dictionary is generated from the schema file, the client code and the Rust core, so it describes exactly the tables and tools of the build that produced it.

Pack families

Each family is an installable pack that answers one kind of question. Forward families use the core pack, when installed, for city and timezone detail.

core

Reverse geocoding and city names. A latitude and longitude, or an H3 cell, gives country, subdivision, city and timezone; a town or city name gives the matching cities.

  • Tools: reverse, h3, geocode
  • Inputs: Coordinates in WGS84 degrees; an H3 cell of resolution 0 to 8 as 15 hexadecimal characters; a city name of at most 128 normalized characters.
  • Built from tables: cells, places, canonical_cities, place_to_city, names, countries, subdivisions, timezone_cells, zone_tables
  • Notes: Every other family reads the core pack for city and timezone detail when it is installed. geocode finds towns and cities by canonical, English or alternate name (the names table), never street addresses.

postal

Postal code to place.

  • Tools: postal
  • Inputs: A code and the country it belongs to. Codes repeat across countries, so the country is required. Spaces are ignored; hyphens and leading zeros are kept.
  • Built from tables: postal_codes, places, canonical_cities, place_to_city, countries, subdivisions
  • Notes: One code can name several places; the result is then ambiguous with ranked candidates.

airports

Airport code to airport.

  • Tools: airport
  • Inputs: A code and an optional scheme (iata, icao, gps, local or ident). Without a scheme, IATA then ICAO are searched. The local scheme needs a country.
  • Built from tables: airports, places, canonical_cities, place_to_city, countries, subdivisions
  • Notes: Ambiguous codes return ranked candidates; a country narrows them.

locode

UN/LOCODE to trade or transport location (port, airport, rail or road terminal).

  • Tools: locode
  • Inputs: The five-character code (two country letters and three letters or digits), or three characters plus a country.
  • Built from tables: trade_locations, places, canonical_cities, place_to_city, countries, subdivisions
  • Notes: Conflicting or malformed country hints are invalid input.

phone

International telephone number to the longest published calling prefix and its country.

  • Tools: phone
  • Inputs: A number in E.164 form with a leading plus and 1 to 15 digits; spaces, hyphens and parentheses after the plus are ignored.
  • Built from tables: phone_prefixes, phone_metadata, places, canonical_cities, place_to_city, countries, subdivisions
  • Notes: This is prefix lookup, not subscriber validation. Shared calling codes such as +1 return one candidate per country.

ip

IPv4 or IPv6 address to the published geolocation interval that contains it.

  • Tools: ip
  • Inputs: A bare address literal; ports, CIDR suffixes and IPv6 zones are invalid.
  • Built from tables: ip_ranges, places, canonical_cities, place_to_city, countries, subdivisions
  • Notes: The point is the provider's location for the interval, usually a city centre, not the device.

plates

Vehicle registration plate text to the countries, and sometimes the region, whose recorded formats it fits.

  • Tools: plate
  • Inputs: Plate text and an optional country and series.
  • Built from tables: plate_formats, plate_codes, plate_policy, plate_priors, places, canonical_cities, place_to_city, countries, subdivisions
  • Notes: Format evidence, not a vehicle registry. Without a country the result is usually ambiguous across countries.

Tools

Every tool is read-only, never installs data and never uses the network. Lookup tools return the result object described below.

reverse

Find the country, subdivision, city and timezone at a latitude and longitude.

Needs the core pack. status is matched when stored land covers the point and not_found otherwise: open water, land outside the installed coverage, or unassigned land. match says how the city was chosen: contained (inside a boundary), nearest (nearest settlement within the distant threshold) or nearest_distant (farther; treat the city as approximate), and distance_band bounds that distance in kilometres. point and cell describe the resolution 8 H3 cell that holds the input, not the input itself. With evidence, a miss explains itself (no_land, outside_coverage, unassigned) and a match shows the city_method that chose the city.

Parameter Type Required Default Description
lat number yes Latitude in degrees, -90 to 90
lon number yes Longitude in degrees, -180 to 180
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

h3

Find the stored ancestor of an H3 cell at resolution zero to eight.

Needs the core pack. Like reverse, from a cell instead of a point. Cells of resolution 3 to 8 search themselves and their stored ancestors; resolutions 0 to 2 have no stored ancestor and return not_found. A resolution above 8 or a malformed cell is invalid_input.

Parameter Type Required Default Description
cell string yes H3 cell as 15 hexadecimal characters, resolution 0 to 8
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

geocode

Finds towns and cities by name. Street addresses are not supported.

Needs the core pack. status is matched for one city and ambiguous when several share the name: candidates are ranked by population and the flat fields keep only what every candidate shares. Pass country or subdivision to narrow them, or prefer="population" to take the largest. match is exact, alternate_name (a published English or other name) or fuzzy (typo tolerant; check the returned name). A street address is unsupported_granularity.

Parameter Type Required Default Description
text string yes City or town name, not an address
country string or null no null Two-letter country code; a hard filter
subdivision string or null no null Subdivision code such as US-IL; a hard filter
limit integer no 5 Most candidates to return, 1 to 100
prefer string or null no null "population" picks the most populous of several cities
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

postal

Find a postal code in the required source country.

Needs the postal pack. Spaces are ignored; hyphens and leading zeros are kept. A code that names several places is ambiguous: candidates are ranked by population. A malformed country, such as a country name instead of its two-letter code, is invalid_input.

Parameter Type Required Default Description
code string yes The code to look up; leading zeros matter
country string yes Two-letter country code of the postal system
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

airport

Find an airport by IATA/ICAO or a specified code scheme.

Needs the airports pack. The point is the airport's own point and the city is the canonical city around it, which can differ from the name in the airport's title. The local scheme needs a country; an unknown scheme is invalid_input. A code shared by several airports is ambiguous.

Parameter Type Required Default Description
code string yes The code to look up; leading zeros matter
scheme string or null no null iata, icao, gps, local or ident; omit for IATA then ICAO
country string or null no null Two-letter country code; narrows ambiguous codes
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

locode

Find a trade location by its five-character LOCODE.

Needs the locode pack. Evidence carries the function flags, status and remarks. A malformed code or a conflicting country is invalid_input; an unknown code is not_found.

Parameter Type Required Default Description
code string yes UN/LOCODE, e.g. BEANR, or three characters with country
country string or null no null Two-letter country code when the code has three characters
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

phone

Find the longest published prefix of an international E.164 number.

Needs the phone pack. This is prefix lookup, not subscriber validation. A calling code shared by several countries, such as +1, can be ambiguous with one candidate per country unless country narrows it. A number without the leading plus is invalid_input.

Parameter Type Required Default Description
number string yes E.164 number with a leading plus and 1 to 15 digits
country string or null no null Two-letter country code; narrows a shared calling code
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

ip

Find published context for an IPv4 or IPv6 literal.

Needs the ip pack. The answer is the geolocation provider's location for the interval that contains the address, usually a city centre; it is not the location of the device. An address outside the published intervals, for example a loopback address, is not_found.

Parameter Type Required Default Description
address string yes IPv4 or IPv6 address literal, without port or mask
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

plate

Find recorded registration formats, preserving country ambiguity.

Needs the plates pack. The result is format evidence, not a vehicle registry. Without a country, plates usually fit formats of several countries and the result is ambiguous with candidates ranked by evidence (rank_basis). With a country the answer is that country, and evidence explains how much geography the code supports.

Parameter Type Required Default Description
text string yes Vehicle registration plate text
country string or null no null Two-letter country context; stays exact when given
series string or null no null Series or subdivision context for series-based plates
evidence boolean no false Add the audit evidence: why the answer or the miss, and sources

describe

Describe the open Parquet dataset behind the answers.

Without a table, lists every table with its purpose, grain, key and number of columns. With a table, returns its columns (type, nullability, units, meaning), primary key, joins to other tables, and the enumerated values of coded columns. Use it before writing SQL over the dataset.

Parameter Type Required Default Description
table string or null no null Dataset table name; omit to list every table

Resources

  • thereabouts://dictionary (application/json): Dataset tables, columns, joins and enumerations, pack families, tools and result fields. From the installed core pack when it ships one.
  • thereabouts://dictionary/markdown (text/markdown): The same dictionary as readable Markdown.

Result

Every lookup tool returns one result object. evidence appears only when requested and hint only when the input needs correction.

Field Type Meaning
status string (values: status) Typed outcome; misses and invalid query values are ordinary results
kind string (values: kind) Domain of the answer; reverse uses cell
match string or null (values: match) Published spatial method, absent for misses and invalid inputs
country Country or null Matched country or the country shared by every ambiguous candidate
state State or null Flat subdivision context, using indexed metadata
city City or null Final published canonical city or rural settlement
timezone string or null Single country-valid zone; unresolved overlap stays in evidence
point Point or null Representative query-cell centre for reverse lookups
cell string or null Canonical query H3 cell; coarse inputs retain their own resolution
distance_band DistanceBand or null Published nearest-policy interval, absent for contained results
candidates array of Result Ranked forward candidates; reverse always leaves this empty
rank_basis string or null (values: rank_basis) Forward ranking rule, absent for reverse lookups
evidence Evidence or null Opt-in audit fields, omitted from JSON when not requested
hint string or null Actionable input guidance, emitted only when a query needs correction

Country

Field Type Meaning
code string Published two-letter country code
code3 string or null Published alpha-3 code, or null when unavailable
name string Country display name from the place catalogue

State

Field Type Meaning
code string or null Published subdivision code, falling back to the place code only if no row exists
name string Subdivision table name, falling back only when the row is absent

City

Field Type Meaning
id string Stable canonical city or final rural-settlement identity
name string Published canonical display name; never reconstructed by the client
name_en string or null English name when the dataset supplies one
kind string Published settlement class such as city, town or village
population integer or null Published population, with unknown zero represented as null
point Point or null Published catalogue anchor, independent of the query cell centre

Point

Field Type Meaning
lat number Latitude in geographic degrees
lon number Longitude in geographic degrees

DistanceBand

Field Type Meaning
greater_than_km number Exclusive lower policy bound in kilometres
at_most_km number Inclusive upper policy bound in kilometres

Evidence

Field Type Meaning
stored_cell string or null Stored pack ancestor, possibly split by a timezone boundary
country_id string or null Country catalogue identity behind the spatial label
state_id string or null Subdivision catalogue identity behind the spatial label
city_id string or null Final city or settlement identity behind the spatial label
city_method string or null (values: cells.city_method) Original golden assignment method, when a city is assigned
land_method string or null (values: cells.land_method) Published land or offshore eligibility marker
reason string or null (values: evidence.reason) Detailed matched or not-found reason without changing public status
timezones array of string Unresolved zone survivors after country narrowing; empty for a unique zone
source_ids array of objects or null Source identifiers published in the city catalogue evidence

status

  • matched: Published geography or one resolved place
  • ambiguous: Several ranked places; flat fields retain only candidate consensus
  • not_found: No stored answer for the query
  • invalid_input: The query cannot be interpreted in this domain
  • unsupported_granularity: The input requests detail finer than the dataset supports

kind

  • city: A canonical city or rural settlement
  • cell: A spatial cell, including country-only reverse context
  • postal: A postal code with a published anchor
  • airport: An airport identified by a supported code
  • trade_location: A port or other transport location
  • ip_range: A published IP address interval
  • phone_prefix: A published calling-code or telephone prefix
  • plate: A vehicle registration format or series

match

  • exact: An exact normalized identifier or primary name
  • alternate_name: A published English or alternate name
  • fuzzy: A fuzzy name-index match
  • contained: The dataset publishes polygon or area containment
  • nearest: The published nearest-distance band below the distant threshold
  • nearest_distant: The published nearest-distance band above the distant threshold

evidence.reason

  • matched (reverse, h3): A stored cell supplied the geography
  • unassigned (reverse, h3): A stored cell exists but has no country, subdivision or city; the status is not_found
  • no_land (reverse, h3): The cell's block is in the pack but no land is stored at this resolution 8 cell, as in open water. In a subset pack it means no admitted land row, not a global ocean assertion
  • outside_coverage (reverse, h3): The cell's block is not in the pack, so the point is outside the pack's coverage
  • no_stored_ancestor (reverse, h3): A coarse H3 query (resolution 0 to 7) has no stored cell at or above it
  • name_exact (geocode): The normalized query equals a canonical or alternate city name
  • name_prefix (geocode): No exact name; the query is the start of a city name
  • name_trigram (geocode): No exact or prefix name; an approximate (fuzzy) name match
  • exact_code (postal, airport, locode, phone, ip): The normalized code or address equals an indexed key or falls in an indexed interval
  • country_from_key (postal): The postal observation has no linked geography, so its country comes from the country in the lookup key; no subdivision or city is inferred
  • plate_country_inferred (plate): No country was supplied; this candidate country was inferred from format evidence and no finer geography is returned
  • empty_or_too_long_input (plate): The plate text was empty after normalization or longer than the policy maximum
  • known_registration_code (plate): The code is a known registration code for the place or places listed in the evidence
  • known_state_code_no_finer_verified_unit (plate): The code identifies a state-level registration unit and no finer verified unit
  • unknown_code_or_unverified_temporal_scope (plate): The format fits, but the code is not a known registration code or its dates are unverified, so only the country is returned
  • no_matching_format (plate): No recorded plate format of the country matches the text
  • subdivision_series_context_required (plate): The country issues plates by subdivision series; pass series to narrow the geography
  • non_geographic_or_ambiguous_series (plate): A matching format carries no geographic code or is ambiguous, so no geography is returned

rank_basis

  • population (geocode, postal, airport, locode, phone, ip): Candidates are ordered by city population, largest first, with a stable order for ties
  • plate_evidence (plate): Candidate countries are ordered by format evidence and a vehicle-registration prior
  • plate_evidence_without_vehicle_prior (plate): Candidate countries are ordered by format evidence alone because the pack has no vehicle prior

Error codes

  • closed_geocoder: An operation was attempted after closing a geocoder
  • corrupt_pack: A pack's checksum, record, or inventory failed validation
  • data_not_installed: No core pack is installed in the selected store
  • geocoder_error: Base class for offline geocoder failures
  • incompatible_data: The selected pack requires a different reader or family
  • internal_error: A library invariant failed, such as a poisoned lock; please report it
  • invalid_input: A value could not be encoded or looked up; the pack itself is fine
  • pack_not_found: An explicitly selected pack directory does not exist
  • resource_limit: The process ran out of file descriptors; raise the open-file limit
  • writer_error: A staging or output operation failed during dataset export
  • writer_input_error: Dataset input, options or staging state prevents export

Dataset tables

Plain Parquet files, one directory per table. Directory labels (country=XX, group=...) route files and are not stored columns; DuckDB and PyArrow add them as columns unless Hive partitioning is off. Only the keys listed are guaranteed unique, and assembly refuses a release that repeats one. Observation tables are keyed by source and source_id, one row per source record, so a code or name can repeat across rows.

Table Grain Key Feeds packs
airports One row per airport record in the pinned OurAirports file; duplicate observations are retained. source, source_id airports
blocks One row per covered resolution 3 block, including blocks that store no cells. A block absent from this table is outside the coverage of this export. block none
canonical_cities One row per canonical city or town; city_id is the place identifier of its anchor. city_id core, postal, airports, locode, phone, ip, plates
cells One row per stored H3 cell: a resolution 8 cell, or a coarser ancestor (resolution 3 to 7) that stands for all its resolution 8 descendants when they share one label. h3_uint64 core
countries One row per country or territory code in the pinned sources. country_code core, postal, airports, locode, phone, ip, plates
ip_ranges One row per published IP interval, from ip_start to ip_end inclusive. source, source_id ip
names One row per canonical city and distinct name. Names that fold to the same text, or to the city's canonical or English name, are kept once. city_id, name core
phone_metadata One row per libphonenumber territory, including the non-geographic territory 001. source, source_id phone
phone_prefixes One row per prefix description in one language file, so a prefix repeats once per language. source, source_id phone
place_to_city One row per place; every places row has exactly one mapping row. place_id core, postal, airports, locode, phone, ip, plates
places One row per reconciled place. place_id core, postal, airports, locode, phone, ip, plates
plate_codes One row per source assertion of a code; a code repeats across sources, series and validity periods. none plates
plate_formats One row per source rule; a country has one row per modeled series and source. none plates
plate_policy Exactly one row. none plates
plate_priors One row per country with a published count. country_code plates
postal_codes One row per postal-code observation; a code can repeat for different place names or variants. source, source_id postal
subdivisions One row per GeoNames first-level division code. code core, postal, airports, locode, phone, ip, plates
timezone_cells One row per timezone and H3 cell; a cell in overlapping zones has several rows, and cells are stored at resolutions 0 to 8. source, source_id core
trade_locations One row per UN/LOCODE entry in the pinned files; source_id names its file and row, and a location code can repeat across entries. source, source_id locode
zone_tables One row per entry of an IANA zone table; a timezone can appear in several tables. source, source_id core

airports

Airports and airfields from OurAirports, placed on the H3 grid and joined to the cell geography at their coordinates.

  • Grain: One row per airport record in the pinned OurAirports file; duplicate observations are retained.
  • Primary key: source, source_id
  • Feeds packs: airports

Joins:

  • airports.country_id → places.place_id: The country place of the cell the point falls in; null when the row is unlocated or unassigned
  • airports.state_id → places.place_id: The first-level subdivision place of that cell; null when none is assigned
  • airports.city_id → places.place_id: The selected settlement of that cell, a canonical city or a standalone rural settlement; null when none is assigned
Column Type Nullable Units Meaning
source string yes in Arrow; no for the logical key Configured upstream source name
source_id string yes in Arrow; no for the logical key Identifier of the original observation within its source
ident string yes OurAirports airport identifier
iata_code string yes IATA airport code, where available
icao_code string yes ICAO airport code, where available
gps_code string yes Source GPS airport code
local_code string yes Local airport code
type string yes Source-specific entity classification
name string yes Preferred display name
municipality string yes Source municipality text
country_code string yes Source or reconciled ISO-like two-letter country code
region_code string yes Source region or subdivision code
latitude double yes degrees north WGS84 latitude; positive north
longitude double yes degrees east WGS84 longitude; positive east
h3 string yes Lowercase hexadecimal H3 cell index, without 0x
h3_uint64 uint64 yes Same H3 index as an unsigned 64-bit integer
h3_resolution uint8 yes H3 level Resolution of this stored H3 index
source_release string yes Pinned upstream release or inventory identifier
license string yes Upstream licence identifier
provenance string yes JSON source evidence and transformation provenance
country_id string yes Reconciled country place identifier
state_id string yes Reconciled first-level subdivision place identifier
city_id string yes Selected settlement place ID, including standalone rural settlements; null if unassigned
cell_country_code string yes Country code assigned by the geographic cell join
cell_status string yes Cell join status: matched, unassigned, ineligible, pending or unlocated
country_disagrees bool yes Whether source and cell country codes disagree; null if not comparable

Enumerated columns:

  • cell_status
  • matched: The point's cell is stored and has a country assignment
  • unassigned: The cell is stored but no country is assigned to it
  • ineligible: The cell is outside the stored land and near-shore coverage
  • pending: No cell data exists for the point's block in this release, so no decision was made
  • unlocated: The row has no coordinates, so there is no cell to join

blocks

The block index of the cells table: every covered resolution 3 H3 block, the cells file and Parquet row group that hold its rows, and how much it stores. A reader can route a coordinate to its rows with this table alone, without manifest.json. Release assembly builds it from the cells it writes.

  • Grain: One row per covered resolution 3 block, including blocks that store no cells. A block absent from this table is outside the coverage of this export.
  • Primary key: block
  • Feeds packs: none
Column Type Nullable Units Meaning
block string no Resolution 3 H3 block in lowercase hexadecimal without 0x; equals cells.block of every row it stores
cell_group string no Resolution 1 H3 parent of the block in lowercase hexadecimal; the block's cells file sits in the directory cells/group=/
path string no The cells file that holds the block's rows, relative to the dataset directory; for a block without rows, the file whose manifest entry lists it as empty
row_group int64 yes Zero-based Parquet row group in path that holds every row of the block; null when the block stores no cells
row_count int64 no rows Cells rows stored for the block; 0 when it stores none, and lookups there then answer that the location is not on land
reference_cells int64 no H3 resolution 8 cells Resolution 8 cells that the block's stored rows stand for once compacted rows are expanded; at most 16,807

canonical_cities

The cities and towns that can absorb other settlements, the anchors for urban areas. Reverse lookups can also return standalone villages and other rural settlements, which are in places but not here.

  • Grain: One row per canonical city or town; city_id is the place identifier of its anchor.
  • Primary key: city_id
  • Feeds packs: core, postal, airports, locode, phone, ip, plates

Joins:

  • canonical_cities.city_id → places.place_id: The anchor place of the canonical city
  • canonical_cities.place_id → places.place_id: The reconciled place of the canonical city; equal to city_id
Column Type Nullable Units Meaning
city_id string no Canonical city/town anchor ID
place_id string no Reconciled place identifier
country_code string no Source or reconciled ISO-like two-letter country code
kind string no Canonical settlement kind
name string no Preferred display name
eligibility string no Evidence qualifying this place as a canonical city
name_en string yes Preferred name only when its provenance explicitly identifies English
latitude double no degrees north WGS84 latitude; positive north
longitude double no degrees east WGS84 longitude; positive east
population int64 yes people Source population estimate, not a current census assertion
source_ids string no JSON list of contributing source identifiers
footprint_references string no JSON references to source settlement footprints
allocation_rule string no Rule used to allocate this canonical settlement

Enumerated columns:

  • kind
  • city: A city: classified as a city by the source, or with a population of at least 100,000
  • town: A town that is not classified as a city and has a smaller population
  • eligibility
  • typed town/city and seat or population: Classified as a town or city by the source, and either a seat feature code or a population at or above the typed minimum
  • population and active settlement: Population at or above the policy minimum, and a feature code that the policy does not exclude
  • national or first-order seat: A national capital or first-order administrative seat feature code
  • explicit country policy: Named by the country's city policy
  • linked city overrides section code: A source city classification overrides the section feature code that would exclude it
  • allocation_rule
  • bounded: The city has accepted boundary footprints that own the cells inside them
  • urban_allocation; optional town_radius: No boundary: the city receives urban cells by allocation and, when enabled, cells within its town radius

cells

Reverse-geocoding labels for land and the retained near-shore band on the H3 grid: country, subdivision and city, with the evidence behind each. Cells are losslessly compacted, so a row can stand for many resolution 8 cells.

  • Grain: One row per stored H3 cell: a resolution 8 cell, or a coarser ancestor (resolution 3 to 7) that stands for all its resolution 8 descendants when they share one label.
  • Primary key: h3_uint64
  • Feeds packs: core

Joins:

  • cells.country_id → places.place_id: The country place of the cell; null when no country is assigned
  • cells.state_id → places.place_id: The first-level subdivision place of the cell; null when none is assigned
  • cells.city_id → places.place_id: The selected settlement of the cell, a canonical city or a standalone rural settlement; null when none is assigned
  • cells.block → blocks.block: The block that routes the cell to its file and Parquet row group
Column Type Nullable Units Meaning
h3 string no Lowercase hexadecimal H3 cell index, without 0x
h3_uint64 uint64 no Same H3 index as an unsigned 64-bit integer
h3_resolution uint8 no H3 level Resolution of this stored H3 index
country_id string yes Reconciled country place identifier
state_id string yes Reconciled first-level subdivision place identifier
city_id string yes Selected settlement place ID, including standalone rural settlements; null if unassigned
country_method string yes Country assignment evidence: area, or null when absent
state_method string yes Subdivision assignment evidence: area, or null when absent
city_method string yes Canonical city allocation rule, including distant-nearest classification
land_method string yes Land eligibility evidence: land or offshore
block string no Resolution 3 H3 parent of the cell (its block) in lowercase hexadecimal without 0x. Each Parquet row group holds one block, so filtering on block reads one row group

Enumerated columns:

  • country_method
  • area: The cell centre lies inside the country's boundary area
  • state_method
  • area: The cell centre lies inside the subdivision's boundary area
  • city_method
  • city_polygon: Inside an accepted municipal footprint polygon of a canonical city
  • policy_polygon: Inside an area that country policy assigns to one city
  • urban_allocation: An urban cell outside any footprint, allocated to a canonical city of its urban cluster
  • town_radius: A rural cell within a qualifying town's own radius; an optional rule that policy can disable
  • rural_polygon: Inside the boundary polygon of a standalone rural settlement
  • rural_nearest: No polygon covers the cell; the nearest settlement within the distant threshold
  • rural_nearest_distant: The nearest settlement is farther than the distant threshold and within the nearest cutoff; treat the city as approximate
  • land_method
  • land: The cell centre is on land
  • offshore: A retained near-shore water cell whose assignment is projected from nearby land

countries

Countries and territories with ISO 3166 codes, names, currency, languages, calling code and UN M49 regions, from the pinned country-codes file plus GeoNames country information, linked to the reconciled country place.

  • Grain: One row per country or territory code in the pinned sources.
  • Primary key: country_code
  • Feeds packs: core, postal, airports, locode, phone, ip, plates

Joins:

  • countries.country_id → places.place_id: The country place named by the row's country code; null when the code matches no place
  • countries.place_id → places.place_id: The single place the row resolves to; null when the link is ambiguous, unmatched or pending
Column Type Nullable Units Meaning
source string no Configured upstream source name
source_id string no Identifier of the original observation within its source
country_code string yes in Arrow; no for the logical key Source or reconciled ISO-like two-letter country code
alpha3 string yes ISO alpha-3 country code
numeric string yes ISO numeric country code represented as text
name string yes Preferred display name
calling_code string yes International telephone calling code, represented as text
currency string yes Source currency code
languages string yes Source language codes
tld string yes Country internet top-level domain
continent string yes Source continent identifier
m49 string yes UN M49 area code
region_code string yes UN M49 code of the country's region, the continent level (for example 142 for Asia); airports.region_code is an ISO 3166-2 code instead
region_name string yes UN region name
subregion_code string yes UN subregion code
subregion_name string yes UN subregion name
intermediate_region_code string yes UN intermediate region code
intermediate_region_name string yes UN intermediate region name
source_release string no Pinned upstream release or inventory identifier
license string no Upstream licence identifier
provenance string no JSON source evidence and transformation provenance
country_id string yes Reconciled country place identifier
place_id string yes Uniquely matched reconciled place; null for ambiguous or unmatched observations
link_status string yes Identifier link status: matched, ambiguous, unmatched or pending
link_method string yes Rule used for the identifier link
place_ids list<element: string> yes All candidate place identifiers; ambiguity is preserved

Enumerated columns:

  • link_status
  • matched: Exactly one candidate place; place_id is set
  • ambiguous: Several candidate places; all are in place_ids and place_id is null
  • unmatched: No candidate place was found
  • pending: The row refers to a country that is expected in the release but was not reconciled in this build
  • link_method
  • source country code: The row's own country code identifies the country
  • explicit code or administrative crosswalk: The published subdivision code maps to a place through the code crosswalk
  • GeoNames administrative identity: The row's GeoNames identifier identifies the place
  • exact country-scoped administrative alias: The normalized name equals a place alias within the same country
  • source-qualified administrative alias: A name qualified by its source administrative context equals a place alias
  • territory fixed-line prefix language: Candidate countries were narrowed by the territory's fixed-line numbering pattern
  • no numbering-pattern support; retained source candidates: No numbering pattern could narrow the candidates, so every source country is kept

ip_ranges

IPv4 and IPv6 geolocation intervals from DB-IP City Lite, each with a published point joined to the cell geography. The ip pack writer rejects overlapping intervals.

  • Grain: One row per published IP interval, from ip_start to ip_end inclusive.
  • Primary key: source, source_id
  • Feeds packs: ip

Joins:

  • ip_ranges.country_id → places.place_id: The country place of the cell the point falls in; null when the row is unlocated or unassigned
  • ip_ranges.state_id → places.place_id: The first-level subdivision place of that cell; null when none is assigned
  • ip_ranges.city_id → places.place_id: The selected settlement of that cell, a canonical city or a standalone rural settlement; null when none is assigned
Column Type Nullable Units Meaning
source string yes in Arrow; no for the logical key Configured upstream source name
source_id string yes in Arrow; no for the logical key Identifier of the original observation within its source
ip_start string yes Inclusive first IP address as text
ip_end string yes Inclusive last IP address as text
country_code string yes Source or reconciled ISO-like two-letter country code
region string yes Source region name
city string yes Source city name; retained independently of the canonical city
ip_version uint8 yes address family IP address family, 4 or 6
ip_start_packed binary yes Inclusive first address, 16-byte big-endian binary; IPv4 is left zero-padded
ip_end_packed binary yes Inclusive last address, 16-byte big-endian binary; IPv4 is left zero-padded
latitude double yes degrees north WGS84 latitude; positive north
longitude double yes degrees east WGS84 longitude; positive east
h3 string yes Lowercase hexadecimal H3 cell index, without 0x
h3_uint64 uint64 yes Same H3 index as an unsigned 64-bit integer
h3_resolution uint8 yes H3 level Resolution of this stored H3 index
source_release string yes Pinned upstream release or inventory identifier
license string yes Upstream licence identifier
provenance string yes JSON source evidence and transformation provenance
country_id string yes Reconciled country place identifier
state_id string yes Reconciled first-level subdivision place identifier
city_id string yes Selected settlement place ID, including standalone rural settlements; null if unassigned
cell_country_code string yes Country code assigned by the geographic cell join
cell_status string yes Cell join status: matched, unassigned, ineligible, pending or unlocated
country_disagrees bool yes Whether source and cell country codes disagree; null if not comparable

Enumerated columns:

  • cell_status
  • matched: The point's cell is stored and has a country assignment
  • unassigned: The cell is stored but no country is assigned to it
  • ineligible: The cell is outside the stored land and near-shore coverage
  • pending: No cell data exists for the point's block in this release, so no decision was made
  • unlocated: The row has no coordinates, so there is no cell to join

names

Alternate names of canonical cities: every name the core pack's forward geocoder matches for a city beyond its canonical and English names in canonical_cities. Names come from GeoNames alternate names, GeoNames feature and ASCII names, and Overture division names of the city's own place or a declared identity alias, filtered by config/policies/names.yaml.

  • Grain: One row per canonical city and distinct name. Names that fold to the same text, or to the city's canonical or English name, are kept once.
  • Primary key: city_id, name
  • Feeds packs: core

Joins:

  • names.city_id → canonical_cities.city_id: The canonical city the name finds
  • names.place_id → places.place_id: The reconciled place whose source record carries the name; the city itself or a declared identity alias
Column Type Nullable Units Meaning
city_id string no Canonical city/town anchor ID
name string no The name as published by the source, NFC with collapsed whitespace
kind string no How the name relates to the city: english, alternate or ascii
language string yes Language tag from the source (GeoNames ISO 639 codes, Overture BCP 47 tags); null when the source gives none
country_code string no Country code of the canonical city
place_id string no Reconciled place whose source record carries the name
source string no Configured upstream source name
source_id string no The name's source row; a GeoNames alternate-name ID, a GeoNames feature ID for feature and ASCII names, or an Overture name digest
source_release string no Pinned upstream release or inventory identifier
license string no Upstream licence identifier
provenance string no JSON source evidence and transformation provenance

Enumerated columns:

  • kind
  • english: An English name (language en or an en- tag) other than the city's name_en
  • alternate: A name in another language or script, an untagged variant, or another source's name for the city
  • ascii: The ASCII spelling GeoNames publishes for the city's feature

phone_metadata

libphonenumber territory metadata: calling code, leading digits and national and international prefixes, with the original territory XML.

  • Grain: One row per libphonenumber territory, including the non-geographic territory 001.
  • Primary key: source, source_id
  • Feeds packs: phone

Joins:

  • phone_metadata.country_id → places.place_id: The country place named by the row's country code; null when the code matches no place
  • phone_metadata.place_id → places.place_id: The single place the row resolves to; null when the link is ambiguous, unmatched or pending
Column Type Nullable Units Meaning
source string no Configured upstream source name
source_id string no Identifier of the original observation within its source
territory string yes Libphonenumber territory code. A code with no country place of its own, such as AC or TA, is published as the country that covers it; manifest.json closure counts the rewritten rows
calling_code string yes International telephone calling code, represented as text
leading_digits string yes Libphonenumber leading-digit pattern
national_prefix string yes National telephone prefix
international_prefix string yes International dialling prefix pattern
metadata_xml string yes Original territory metadata XML
source_release string no Pinned upstream release or inventory identifier
license string no Upstream licence identifier
provenance string no JSON source evidence and transformation provenance
country_id string yes Reconciled country place identifier
place_id string yes Uniquely matched reconciled place; null for ambiguous or unmatched observations
link_status string yes Identifier link status: matched, ambiguous, unmatched or pending
link_method string yes Rule used for the identifier link
place_ids list<element: string> yes All candidate place identifiers; ambiguity is preserved

Enumerated columns:

  • link_status
  • matched: Exactly one candidate place; place_id is set
  • ambiguous: Several candidate places; all are in place_ids and place_id is null
  • unmatched: No candidate place was found
  • pending: The row refers to a country that is expected in the release but was not reconciled in this build
  • link_method
  • source country code: The row's own country code identifies the country
  • explicit code or administrative crosswalk: The published subdivision code maps to a place through the code crosswalk
  • GeoNames administrative identity: The row's GeoNames identifier identifies the place
  • exact country-scoped administrative alias: The normalized name equals a place alias within the same country
  • source-qualified administrative alias: A name qualified by its source administrative context equals a place alias
  • territory fixed-line prefix language: Candidate countries were narrowed by the territory's fixed-line numbering pattern
  • no numbering-pattern support; retained source candidates: No numbering pattern could narrow the candidates, so every source country is kept

phone_prefixes

libphonenumber geographic prefix descriptions: the place a telephone prefix belongs to, in each published language. Shared calling codes keep every candidate country.

  • Grain: One row per prefix description in one language file, so a prefix repeats once per language.
  • Primary key: source, source_id
  • Feeds packs: phone

Joins:

  • phone_prefixes.country_id → places.place_id: The country place named by the row's country code; null when the code matches no place
  • phone_prefixes.place_id → places.place_id: The single place the row resolves to; null when the link is ambiguous, unmatched or pending
Column Type Nullable Units Meaning
source string no Configured upstream source name
source_id string no Identifier of the original observation within its source
prefix string yes Telephone prefix as text; preserve leading zeros
calling_code string yes International telephone calling code, represented as text
language string yes Language of the prefix description
description string yes Source geographic prefix description
country_codes list<element: string> no Associated country codes; list of text codes. A code with no country place of its own is published once, as the country that covers it; manifest.json closure counts the rewritten rows
source_release string no Pinned upstream release or inventory identifier
license string no Upstream licence identifier
provenance string no JSON source evidence and transformation provenance
country_id string yes Reconciled country place identifier
place_id string yes Uniquely matched reconciled place; null for ambiguous or unmatched observations
link_status string yes Identifier link status: matched, ambiguous, unmatched or pending
link_method string yes Rule used for the identifier link
place_ids list<element: string> yes All candidate place identifiers; ambiguity is preserved

Enumerated columns:

  • link_status
  • matched: Exactly one candidate place; place_id is set
  • ambiguous: Several candidate places; all are in place_ids and place_id is null
  • unmatched: No candidate place was found
  • pending: The row refers to a country that is expected in the release but was not reconciled in this build
  • link_method
  • source country code: The row's own country code identifies the country
  • explicit code or administrative crosswalk: The published subdivision code maps to a place through the code crosswalk
  • GeoNames administrative identity: The row's GeoNames identifier identifies the place
  • exact country-scoped administrative alias: The normalized name equals a place alias within the same country
  • source-qualified administrative alias: A name qualified by its source administrative context equals a place alias
  • territory fixed-line prefix language: Candidate countries were narrowed by the territory's fixed-line numbering pattern
  • no numbering-pattern support; retained source candidates: No numbering pattern could narrow the candidates, so every source country is kept

place_to_city

The reviewed mapping from every place to the city or standalone settlement that represents it. Use it to roll places up to canonical cities.

  • Grain: One row per place; every places row has exactly one mapping row.
  • Primary key: place_id
  • Feeds packs: core, postal, airports, locode, phone, ip, plates

Joins:

  • place_to_city.place_id → places.place_id: The mapped place
  • place_to_city.city_id → places.place_id: The representing city or settlement; null for non-settlements
Column Type Nullable Units Meaning
place_id string no Reconciled place identifier
city_id string yes Selected settlement place ID, including standalone rural settlements; null if unassigned
method string no Mapping rule: self, spatial_absorption, policy_part, identity_alias or non_settlement
evidence string yes JSON evidence supporting the allocation

Enumerated columns:

  • method
  • self: The place is its own city: a canonical city, or a settlement that no city absorbs
  • spatial_absorption: The settlement lies inside a canonical city's extent and maps to that city
  • policy_part: Country policy names the place as a part of a city and maps it there
  • identity_alias: Country policy declares the place another identity of the same city
  • non_settlement: A country, state or district: not a settlement, so city_id is null

places

The reconciled place catalogue behind every identifier: countries, subdivisions, canonical cities and towns, other settlements and districts, with names, population and provenance. Treat place identifiers as opaque and do not compare them across releases.

  • Grain: One row per reconciled place.
  • Primary key: place_id
  • Feeds packs: core, postal, airports, locode, phone, ip, plates

Joins:

  • places.parent_id → places.place_id: The parent place (country or subdivision); null when none was selected
  • places.sovereign_id → places.place_id: The sovereign country place; null when not applicable
  • places.normalized_city_id → places.place_id: The city or settlement representing this place, as in place_to_city.city_id
Column Type Nullable Units Meaning
place_id string yes in Arrow; no for the logical key Reconciled place identifier
name_en string yes Preferred name only when its provenance explicitly identifies English
local_name string yes Source local/default name, without an inferred translation
country_code string yes Source or reconciled ISO-like two-letter country code
code string yes Published entity code
code_status string yes Recorded source/code status, including user-assigned for XK; codes are not invented
parent_id string yes Reconciled parent place identifier
parent_method string yes Evidence used to select the parent
sovereign_id string yes Sovereign country place identifier
sovereign_code string yes Sovereign country code
sovereign_name string yes Sovereign country display name
population int64 yes people Source population estimate, not a current census assertion
geonames_id string yes GeoNames identifier represented as text
geonames_admin1 string yes GeoNames first-level administrative code
feature_code string yes GeoNames feature code
source_subtype string yes Original source feature subtype
settlement_class string yes Reconciled settlement classification
city_exclusion string yes Reason this place is excluded from canonical city eligibility
overture_ids list<element: string> yes Contributing Overture entity identifiers
wikidata_ids list<element: string> yes Contributing Wikidata entity identifiers
source_ids string yes JSON list of contributing source identifiers
provenance string yes JSON source evidence and transformation provenance
name_provenance string yes JSON evidence for the selected names
link string yes JSON identity-link method and evidence, or JSON null
name string yes Preferred display name
role string yes Reconciled place role
normalized_city_id string yes Selected settlement place ID; standalone rural settlements can map to themselves
normalization_method string yes Rule used to select the normalized settlement identity
settlement_kind string yes Canonical settlement classification

Enumerated columns:

  • code_status
  • source: The code is as published by the source
  • user-assigned: A code assigned by users rather than by ISO, used for Kosovo (XK)
  • parent_method
  • GeoNames ADM1 identity crosswalk: The place's GeoNames first-level code identifies exactly one subdivision
  • city anchor in state area: Several subdivisions share the code; the one whose area contains the place's anchor point
  • settlement_class
  • city: Classified as a city by the source
  • town: Classified as a town by the source
  • village: Classified as a village by the source
  • hamlet: Classified as a hamlet by the source
  • city_exclusion
  • insufficient settlement evidence: A locality without enough settlement evidence to be a city or town
  • administrative container of a larger linked settlement: A district that contains a much larger linked settlement
  • role
  • country: A country
  • state: A first-level subdivision
  • city: A canonical city
  • town: A canonical town
  • settlement: A settlement that is not a canonical city or town
  • district: An administrative district or a locality without settlement evidence
  • normalization_method
  • self: The place is its own city: a canonical city, or a settlement that no city absorbs
  • spatial_absorption: The settlement lies inside a canonical city's extent and maps to that city
  • policy_part: Country policy names the place as a part of a city and maps it there
  • identity_alias: Country policy declares the place another identity of the same city
  • non_settlement: A country, state or district: not a settlement, so city_id is null
  • settlement_kind
  • country: A country
  • state: A first-level subdivision
  • district: An administrative district
  • city: A canonical city, or a standalone settlement the source classifies as a city
  • town: A canonical town, or a standalone settlement the source classifies as a town
  • city_part: A place that the mapping absorbs into another city
  • village: A standalone settlement classified as a village
  • hamlet: A standalone settlement classified as a hamlet
  • settlement: A standalone settlement without a source class

plate_codes

Registration-code assertions: a code printed on vehicle plates and the registration unit or entity it names, from pinned national pages, Wikipedia revisions and Wikidata. Every row keeps its source URL and licence.

  • Grain: One row per source assertion of a code; a code repeats across sources, series and validity periods.
  • Primary key: none
  • Feeds packs: plates

Joins:

  • plate_codes.country_code → countries.country_code: The country or territory issuing the plates
Column Type Nullable Units Meaning
country_code string no ISO-like two-letter code of the issuing country or territory
code string no The code as the source spells it, with leading zeros and native script
name_en string yes English label of the registration unit, as published
name_local string yes Local-language label of the registration unit, as published
unit_kind string no Source unit kind, such as district, state or registration_office; plate_policy maps it to a place or state level
scope string no Whether the code identifies a registration unit or only associates an entity
series_status string no Temporal status of the assertion
series_id string yes Source series identifier the assertion belongs to
subdivision_scope string yes Narrower context the assertion requires, such as a state series
subdivision_codes list<element: string> no ISO 3166-2 identifiers the source gives for the unit; empty when none
source string no Configured upstream source name
source_url string no URL of the pinned document or query the assertion comes from
license string no Licence identifier of that document

Enumerated columns:

  • scope
  • registration_unit: The source lists the code as issued by this registration unit
  • entity_association: Wikidata associates the code with an entity; never used for geography
  • series_status
  • current: The source describes the code as in current use
  • historic: The source describes a former series or allocation
  • unknown: The source does not establish the status

plate_formats

Plate syntax rules: a full-match regular expression per country and series, with the relaxed form that tolerates separators only where the source shows them, the scripts it uses and its specificity. Each rule is checked against its pinned source document when built; rules whose documents are not pinned are left out.

  • Grain: One row per source rule; a country has one row per modeled series and source.
  • Primary key: none
  • Feeds packs: plates

Joins:

  • plate_formats.country_code → countries.country_code: The country or territory issuing the plates
Column Type Nullable Units Meaning
country_code string no ISO-like two-letter code of the issuing country or territory
series_id string no Source series identifier
series_status string no Temporal status of the series as the format policy records it: current, or historic (a former series, which needs an explicit series to supply geography)
pattern string no Full-match regular expression over the normalized plate text
relaxed_pattern string no The pattern with separators optional or varied only at the positions the source shows
code_group string yes Name of the capture group holding the registration code; null for series without one
scripts list<element: string> no Script names the pattern uses, from plate_policy script_patterns
fixed_national_marks list<element: string> no Literal national marks within the serial
specificity_bits double no bits Information heuristic of the pattern against a 36-character baseline; not a count of valid plates
provenance string no JSON source fields of the pinned document: URL, licence, attribution, revision, digest and retrieval time
source string no Configured upstream source name
source_file string no Pinned file name of the source document
source_url string no URL of the pinned source document
license string no Licence identifier of that document

plate_policy

The frozen plate matching and ranking policy (input normalization, code separators, unit-kind levels, script patterns, weights, geographic restrictions and the Unicode decimal digits used for code equality), from config/policies/plate_country/inference.yaml.

  • Grain: Exactly one row.
  • Primary key: none
  • Feeds packs: plates
Column Type Nullable Units Meaning
policy_json string no The policy as one JSON object

plate_priors

Observed road motor vehicle counts per country, the weak prior that orders candidate countries for a plate without a country. Empty when no vehicle-stock source is pinned; the plates pack then ranks by format evidence alone.

  • Grain: One row per country with a published count.
  • Primary key: country_code
  • Feeds packs: plates

Joins:

  • plate_priors.country_code → countries.country_code: The counted country or territory
Column Type Nullable Units Meaning
country_code string no ISO-like two-letter code of the counted country or territory
vehicles uint64 no vehicles Published road motor vehicle count; definitions and dates differ between countries
year int64 no calendar year Year of the published count
source_label string no Country label as the source table prints it
source string no Configured upstream source name
source_url string no URL of the pinned source document
license string no Licence identifier of that document
provenance string no JSON source fields and the table row the count comes from

postal_codes

GeoNames postal codes with place names, administrative names and a located point joined to the cell geography. Codes keep their spaces and leading zeros.

  • Grain: One row per postal-code observation; a code can repeat for different place names or variants.
  • Primary key: source, source_id
  • Feeds packs: postal

Joins:

  • postal_codes.country_id → places.place_id: The country place of the cell the point falls in; null when the row is unlocated or unassigned
  • postal_codes.state_id → places.place_id: The first-level subdivision place of that cell; null when none is assigned
  • postal_codes.city_id → places.place_id: The selected settlement of that cell, a canonical city or a standalone rural settlement; null when none is assigned
Column Type Nullable Units Meaning
source string yes in Arrow; no for the logical key Configured upstream source name
source_id string yes in Arrow; no for the logical key Identifier of the original observation within its source
country_code string yes Source or reconciled ISO-like two-letter country code
postal_code string yes Postal code as text; preserve spaces and leading zeros
place_name string yes Source postal place name
admin1_name string yes Original level-1 administrative name
admin1_code string yes Original level-1 administrative code
admin2_name string yes Original level-2 administrative name
admin2_code string yes Original level-2 administrative code
admin3_name string yes Original level-3 administrative name
admin3_code string yes Original level-3 administrative code
accuracy string yes Original source positional-accuracy category, not metres
variant string yes Original postal observation variant
latitude double yes degrees north WGS84 latitude; positive north
longitude double yes degrees east WGS84 longitude; positive east
h3 string yes Lowercase hexadecimal H3 cell index, without 0x
h3_uint64 uint64 yes Same H3 index as an unsigned 64-bit integer
h3_resolution uint8 yes H3 level Resolution of this stored H3 index
source_release string yes Pinned upstream release or inventory identifier
license string yes Upstream licence identifier
provenance string yes JSON source evidence and transformation provenance
country_id string yes Reconciled country place identifier
state_id string yes Reconciled first-level subdivision place identifier
city_id string yes Selected settlement place ID, including standalone rural settlements; null if unassigned
cell_country_code string yes Country code assigned by the geographic cell join
cell_status string yes Cell join status: matched, unassigned, ineligible, pending or unlocated
country_disagrees bool yes Whether source and cell country codes disagree; null if not comparable

Enumerated columns:

  • cell_status
  • matched: The point's cell is stored and has a country assignment
  • unassigned: The cell is stored but no country is assigned to it
  • ineligible: The cell is outside the stored land and near-shore coverage
  • pending: No cell data exists for the point's block in this release, so no decision was made
  • unlocated: The row has no coordinates, so there is no cell to join

subdivisions

First-level administrative divisions as published by GeoNames admin1 codes, linked to the reconciled subdivision places.

  • Grain: One row per GeoNames first-level division code.
  • Primary key: code
  • Feeds packs: core, postal, airports, locode, phone, ip, plates

Joins:

  • subdivisions.country_id → places.place_id: The country place named by the row's country code; null when the code matches no place
  • subdivisions.place_id → places.place_id: The single place the row resolves to; null when the link is ambiguous, unmatched or pending
Column Type Nullable Units Meaning
source string no Configured upstream source name
source_id string no Identifier of the original observation within its source
code string yes in Arrow; no for the logical key Published entity code
code_system string yes Namespace of the published administrative code
country_code string yes Source or reconciled ISO-like two-letter country code
name string yes Preferred display name
type string yes Source-specific entity classification
parent_code string yes Original source parent administrative code
geoname_id string yes GeoNames identifier represented as text
name_ascii string yes Source ASCII name
source_release string no Pinned upstream release or inventory identifier
license string no Upstream licence identifier
provenance string no JSON source evidence and transformation provenance
country_id string yes Reconciled country place identifier
place_id string yes Uniquely matched reconciled place; null for ambiguous or unmatched observations
link_status string yes Identifier link status: matched, ambiguous, unmatched or pending
link_method string yes Rule used for the identifier link
place_ids list<element: string> yes All candidate place identifiers; ambiguity is preserved

Enumerated columns:

  • code_system
  • GeoNames-admin1: GeoNames country-dot-admin1 codes such as BE.BRU
  • link_status
  • matched: Exactly one candidate place; place_id is set
  • ambiguous: Several candidate places; all are in place_ids and place_id is null
  • unmatched: No candidate place was found
  • pending: The row refers to a country that is expected in the release but was not reconciled in this build
  • link_method
  • source country code: The row's own country code identifies the country
  • explicit code or administrative crosswalk: The published subdivision code maps to a place through the code crosswalk
  • GeoNames administrative identity: The row's GeoNames identifier identifies the place
  • exact country-scoped administrative alias: The normalized name equals a place alias within the same country
  • source-qualified administrative alias: A name qualified by its source administrative context equals a place alias
  • territory fixed-line prefix language: Candidate countries were narrowed by the territory's fixed-line numbering pattern
  • no numbering-pattern support; retained source candidates: No numbering pattern could narrow the candidates, so every source country is kept

timezone_cells

IANA timezone membership on the H3 grid, derived from timezone-boundary-builder polygons. Membership is independent of land eligibility and zones can overlap.

  • Grain: One row per timezone and H3 cell; a cell in overlapping zones has several rows, and cells are stored at resolutions 0 to 8.
  • Primary key: source, source_id
  • Feeds packs: core
Column Type Nullable Units Meaning
source string no Configured upstream source name
source_id string no Identifier of the original observation within its source
tzid string no IANA timezone identifier
h3 string no Lowercase hexadecimal H3 cell index, without 0x
h3_uint64 uint64 no Same H3 index as an unsigned 64-bit integer
h3_resolution uint8 no H3 level Resolution of this stored H3 index
source_release string no Pinned upstream release or inventory identifier
license string no Upstream licence identifier
provenance string no JSON source evidence and transformation provenance

trade_locations

UN/LOCODE trade and transport locations (ports, airports, rail and road terminals) with codes, function flags and optional coordinates, joined to the cell geography where they have a point.

  • Grain: One row per UN/LOCODE entry in the pinned files; source_id names its file and row, and a location code can repeat across entries.
  • Primary key: source, source_id
  • Feeds packs: locode

Joins:

  • trade_locations.country_id → places.place_id: The country place of the cell the point falls in; null when the row is unlocated or unassigned
  • trade_locations.state_id → places.place_id: The first-level subdivision place of that cell; null when none is assigned
  • trade_locations.city_id → places.place_id: The selected settlement of that cell, a canonical city or a standalone rural settlement; null when none is assigned
Column Type Nullable Units Meaning
source string yes in Arrow; no for the logical key Configured upstream source name
source_id string yes in Arrow; no for the logical key Identifier of the original observation within its source
locode string yes UN/LOCODE identifier
country_code string yes Source or reconciled ISO-like two-letter country code
location string yes UN/LOCODE location component
name string yes Preferred display name
name_ascii string yes Source ASCII name
subdivision_code string yes Source subdivision component
function string yes UN/LOCODE function flags
status string yes UN/LOCODE record status
iata_code string yes IATA airport code, where available
date string yes Original source record date string
change string yes UN/LOCODE change marker
remarks string yes Original source remarks
coordinates_raw string yes Original source coordinate text
latitude double yes degrees north WGS84 latitude; positive north
longitude double yes degrees east WGS84 longitude; positive east
h3 string yes Lowercase hexadecimal H3 cell index, without 0x
h3_uint64 uint64 yes Same H3 index as an unsigned 64-bit integer
h3_resolution uint8 yes H3 level Resolution of this stored H3 index
source_release string yes Pinned upstream release or inventory identifier
license string yes Upstream licence identifier
provenance string yes JSON source evidence and transformation provenance
country_id string yes Reconciled country place identifier
state_id string yes Reconciled first-level subdivision place identifier
city_id string yes Selected settlement place ID, including standalone rural settlements; null if unassigned
cell_country_code string yes Country code assigned by the geographic cell join
cell_status string yes Cell join status: matched, unassigned, ineligible, pending or unlocated
country_disagrees bool yes Whether source and cell country codes disagree; null if not comparable

Enumerated columns:

  • cell_status
  • matched: The point's cell is stored and has a country assignment
  • unassigned: The cell is stored but no country is assigned to it
  • ineligible: The cell is outside the stored land and near-shore coverage
  • pending: No cell data exists for the point's block in this release, so no decision was made
  • unlocated: The row has no coordinates, so there is no cell to join

zone_tables

Rows of the IANA zone tables, linking each timezone identifier to its countries and a representative point.

  • Grain: One row per entry of an IANA zone table; a timezone can appear in several tables.
  • Primary key: source, source_id
  • Feeds packs: core
Column Type Nullable Units Meaning
source string no Configured upstream source name
source_id string no Identifier of the original observation within its source
table string yes Original timezone table name
tzid string yes IANA timezone identifier
country_codes string yes Associated country codes; comma-separated text
comments string yes Original timezone comments
coordinates_raw string yes Original source coordinate text
latitude double yes degrees north WGS84 latitude; positive north
longitude double yes degrees east WGS84 longitude; positive east
h3 string yes Lowercase hexadecimal H3 cell index, without 0x
h3_uint64 uint64 yes Same H3 index as an unsigned 64-bit integer
h3_resolution uint8 yes H3 level Resolution of this stored H3 index
source_release string no Pinned upstream release or inventory identifier
license string no Upstream licence identifier
provenance string no JSON source evidence and transformation provenance

Enumerated columns:

  • table
  • zone.tab: One row per timezone and country, as in the classic zone table
  • zone1970.tab: Timezones that agree since 1970 are merged and list all their countries
  • zonenow.tab: Timezones that agree from now on are merged