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 placeambiguous: Several ranked places; flat fields retain only candidate consensusnot_found: No stored answer for the queryinvalid_input: The query cannot be interpreted in this domainunsupported_granularity: The input requests detail finer than the dataset supports
kind¶
city: A canonical city or rural settlementcell: A spatial cell, including country-only reverse contextpostal: A postal code with a published anchorairport: An airport identified by a supported codetrade_location: A port or other transport locationip_range: A published IP address intervalphone_prefix: A published calling-code or telephone prefixplate: A vehicle registration format or series
match¶
exact: An exact normalized identifier or primary namealternate_name: A published English or alternate namefuzzy: A fuzzy name-index matchcontained: The dataset publishes polygon or area containmentnearest: The published nearest-distance band below the distant thresholdnearest_distant: The published nearest-distance band above the distant threshold
evidence.reason¶
matched(reverse, h3): A stored cell supplied the geographyunassigned(reverse, h3): A stored cell exists but has no country, subdivision or city; the status is not_foundno_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 assertionoutside_coverage(reverse, h3): The cell's block is not in the pack, so the point is outside the pack's coverageno_stored_ancestor(reverse, h3): A coarse H3 query (resolution 0 to 7) has no stored cell at or above itname_exact(geocode): The normalized query equals a canonical or alternate city namename_prefix(geocode): No exact name; the query is the start of a city namename_trigram(geocode): No exact or prefix name; an approximate (fuzzy) name matchexact_code(postal, airport, locode, phone, ip): The normalized code or address equals an indexed key or falls in an indexed intervalcountry_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 inferredplate_country_inferred(plate): No country was supplied; this candidate country was inferred from format evidence and no finer geography is returnedempty_or_too_long_input(plate): The plate text was empty after normalization or longer than the policy maximumknown_registration_code(plate): The code is a known registration code for the place or places listed in the evidenceknown_state_code_no_finer_verified_unit(plate): The code identifies a state-level registration unit and no finer verified unitunknown_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 returnedno_matching_format(plate): No recorded plate format of the country matches the textsubdivision_series_context_required(plate): The country issues plates by subdivision series; pass series to narrow the geographynon_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 tiesplate_evidence(plate): Candidate countries are ordered by format evidence and a vehicle-registration priorplate_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 geocodercorrupt_pack: A pack's checksum, record, or inventory failed validationdata_not_installed: No core pack is installed in the selected storegeocoder_error: Base class for offline geocoder failuresincompatible_data: The selected pack requires a different reader or familyinternal_error: A library invariant failed, such as a poisoned lock; please report itinvalid_input: A value could not be encoded or looked up; the pack itself is finepack_not_found: An explicitly selected pack directory does not existresource_limit: The process ran out of file descriptors; raise the open-file limitwriter_error: A staging or output operation failed during dataset exportwriter_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 unassignedairports.state_id→places.place_id: The first-level subdivision place of that cell; null when none is assignedairports.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_statusmatched: The point's cell is stored and has a country assignmentunassigned: The cell is stored but no country is assigned to itineligible: The cell is outside the stored land and near-shore coveragepending: No cell data exists for the point's block in this release, so no decision was madeunlocated: 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 citycanonical_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:
kindcity: A city: classified as a city by the source, or with a population of at least 100,000town: A town that is not classified as a city and has a smaller populationeligibilitytyped 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 minimumpopulation and active settlement: Population at or above the policy minimum, and a feature code that the policy does not excludenational or first-order seat: A national capital or first-order administrative seat feature codeexplicit country policy: Named by the country's city policylinked city overrides section code: A source city classification overrides the section feature code that would exclude itallocation_rulebounded: The city has accepted boundary footprints that own the cells inside themurban_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 assignedcells.state_id→places.place_id: The first-level subdivision place of the cell; null when none is assignedcells.city_id→places.place_id: The selected settlement of the cell, a canonical city or a standalone rural settlement; null when none is assignedcells.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_methodarea: The cell centre lies inside the country's boundary areastate_methodarea: The cell centre lies inside the subdivision's boundary areacity_methodcity_polygon: Inside an accepted municipal footprint polygon of a canonical citypolicy_polygon: Inside an area that country policy assigns to one cityurban_allocation: An urban cell outside any footprint, allocated to a canonical city of its urban clustertown_radius: A rural cell within a qualifying town's own radius; an optional rule that policy can disablerural_polygon: Inside the boundary polygon of a standalone rural settlementrural_nearest: No polygon covers the cell; the nearest settlement within the distant thresholdrural_nearest_distant: The nearest settlement is farther than the distant threshold and within the nearest cutoff; treat the city as approximateland_methodland: The cell centre is on landoffshore: 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 placecountries.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_statusmatched: Exactly one candidate place; place_id is setambiguous: Several candidate places; all are in place_ids and place_id is nullunmatched: No candidate place was foundpending: The row refers to a country that is expected in the release but was not reconciled in this buildlink_methodsource country code: The row's own country code identifies the countryexplicit code or administrative crosswalk: The published subdivision code maps to a place through the code crosswalkGeoNames administrative identity: The row's GeoNames identifier identifies the placeexact country-scoped administrative alias: The normalized name equals a place alias within the same countrysource-qualified administrative alias: A name qualified by its source administrative context equals a place aliasterritory fixed-line prefix language: Candidate countries were narrowed by the territory's fixed-line numbering patternno 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 unassignedip_ranges.state_id→places.place_id: The first-level subdivision place of that cell; null when none is assignedip_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_statusmatched: The point's cell is stored and has a country assignmentunassigned: The cell is stored but no country is assigned to itineligible: The cell is outside the stored land and near-shore coveragepending: No cell data exists for the point's block in this release, so no decision was madeunlocated: 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 findsnames.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:
kindenglish: An English name (language en or an en- tag) other than the city's name_enalternate: A name in another language or script, an untagged variant, or another source's name for the cityascii: 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 placephone_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_statusmatched: Exactly one candidate place; place_id is setambiguous: Several candidate places; all are in place_ids and place_id is nullunmatched: No candidate place was foundpending: The row refers to a country that is expected in the release but was not reconciled in this buildlink_methodsource country code: The row's own country code identifies the countryexplicit code or administrative crosswalk: The published subdivision code maps to a place through the code crosswalkGeoNames administrative identity: The row's GeoNames identifier identifies the placeexact country-scoped administrative alias: The normalized name equals a place alias within the same countrysource-qualified administrative alias: A name qualified by its source administrative context equals a place aliasterritory fixed-line prefix language: Candidate countries were narrowed by the territory's fixed-line numbering patternno 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 placephone_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_statusmatched: Exactly one candidate place; place_id is setambiguous: Several candidate places; all are in place_ids and place_id is nullunmatched: No candidate place was foundpending: The row refers to a country that is expected in the release but was not reconciled in this buildlink_methodsource country code: The row's own country code identifies the countryexplicit code or administrative crosswalk: The published subdivision code maps to a place through the code crosswalkGeoNames administrative identity: The row's GeoNames identifier identifies the placeexact country-scoped administrative alias: The normalized name equals a place alias within the same countrysource-qualified administrative alias: A name qualified by its source administrative context equals a place aliasterritory fixed-line prefix language: Candidate countries were narrowed by the territory's fixed-line numbering patternno 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 placeplace_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:
methodself: The place is its own city: a canonical city, or a settlement that no city absorbsspatial_absorption: The settlement lies inside a canonical city's extent and maps to that citypolicy_part: Country policy names the place as a part of a city and maps it thereidentity_alias: Country policy declares the place another identity of the same citynon_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 selectedplaces.sovereign_id→places.place_id: The sovereign country place; null when not applicableplaces.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_statussource: The code is as published by the sourceuser-assigned: A code assigned by users rather than by ISO, used for Kosovo (XK)parent_methodGeoNames ADM1 identity crosswalk: The place's GeoNames first-level code identifies exactly one subdivisioncity anchor in state area: Several subdivisions share the code; the one whose area contains the place's anchor pointsettlement_classcity: Classified as a city by the sourcetown: Classified as a town by the sourcevillage: Classified as a village by the sourcehamlet: Classified as a hamlet by the sourcecity_exclusioninsufficient settlement evidence: A locality without enough settlement evidence to be a city or townadministrative container of a larger linked settlement: A district that contains a much larger linked settlementrolecountry: A countrystate: A first-level subdivisioncity: A canonical citytown: A canonical townsettlement: A settlement that is not a canonical city or towndistrict: An administrative district or a locality without settlement evidencenormalization_methodself: The place is its own city: a canonical city, or a settlement that no city absorbsspatial_absorption: The settlement lies inside a canonical city's extent and maps to that citypolicy_part: Country policy names the place as a part of a city and maps it thereidentity_alias: Country policy declares the place another identity of the same citynon_settlement: A country, state or district: not a settlement, so city_id is nullsettlement_kindcountry: A countrystate: A first-level subdivisiondistrict: An administrative districtcity: A canonical city, or a standalone settlement the source classifies as a citytown: A canonical town, or a standalone settlement the source classifies as a towncity_part: A place that the mapping absorbs into another cityvillage: A standalone settlement classified as a villagehamlet: A standalone settlement classified as a hamletsettlement: 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:
scoperegistration_unit: The source lists the code as issued by this registration unitentity_association: Wikidata associates the code with an entity; never used for geographyseries_statuscurrent: The source describes the code as in current usehistoric: The source describes a former series or allocationunknown: 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 unassignedpostal_codes.state_id→places.place_id: The first-level subdivision place of that cell; null when none is assignedpostal_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_statusmatched: The point's cell is stored and has a country assignmentunassigned: The cell is stored but no country is assigned to itineligible: The cell is outside the stored land and near-shore coveragepending: No cell data exists for the point's block in this release, so no decision was madeunlocated: 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 placesubdivisions.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_systemGeoNames-admin1: GeoNames country-dot-admin1 codes such as BE.BRUlink_statusmatched: Exactly one candidate place; place_id is setambiguous: Several candidate places; all are in place_ids and place_id is nullunmatched: No candidate place was foundpending: The row refers to a country that is expected in the release but was not reconciled in this buildlink_methodsource country code: The row's own country code identifies the countryexplicit code or administrative crosswalk: The published subdivision code maps to a place through the code crosswalkGeoNames administrative identity: The row's GeoNames identifier identifies the placeexact country-scoped administrative alias: The normalized name equals a place alias within the same countrysource-qualified administrative alias: A name qualified by its source administrative context equals a place aliasterritory fixed-line prefix language: Candidate countries were narrowed by the territory's fixed-line numbering patternno 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 unassignedtrade_locations.state_id→places.place_id: The first-level subdivision place of that cell; null when none is assignedtrade_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_statusmatched: The point's cell is stored and has a country assignmentunassigned: The cell is stored but no country is assigned to itineligible: The cell is outside the stored land and near-shore coveragepending: No cell data exists for the point's block in this release, so no decision was madeunlocated: 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:
tablezone.tab: One row per timezone and country, as in the classic zone tablezone1970.tab: Timezones that agree since 1970 are merged and list all their countrieszonenow.tab: Timezones that agree from now on are merged