Skip to Content
teigeodata
Reference

Engine

Open packs answering place queries.

Open packs answering place queries. Every method takes &self: one engine answers from any number of threads at once, and adding a pack publishes a new snapshot while queries go on.

Place results are blobs with the columns id, name, kind, level, lat, lon, elevation, parent, tz, iso, population and population_kind (stated or modelled; absent values are null), plus score for a search and meters and bearing for a reverse lookup.

Every query returns a result blob; read it with your language's Reader. Pick a language in any tab and every tab on the site follows.

new

An engine with no packs.

pub fn new() -> Self

open_file

Opens the pack at path (memory-mapped) and adds it. Returns its layer ID, for remove: unique in this engine, counting up from 0.

Errors. ErrorCode::Io if the file cannot be read, ErrorCode::Corrupt if it is not a valid pack.

pub fn open_file(&self, path: &str) -> Result<u32>

open_file_with

Opens the pack at path with these options and adds it. Returns its layer ID, as open_file.

Errors. As open_file, and ErrorCode::InvalidArgument for an outline level above 255.

pub fn open_file_with(&self, path: &str, options: &OpenOptions) -> Result<u32>

open_file_range

Opens the pack stored whole in length bytes at offset of the file at path (memory-mapped) and adds it: a pack bundled as an uncompressed asset of an Android app (noCompress; the path is the APK, the offset and length its AssetFileDescriptor's), or one inside any container that stores it uncompressed. The offset need not be aligned. Returns its layer ID, as open_file.

Errors. ErrorCode::Io if the file cannot be read or the range is not inside it, ErrorCode::Corrupt if the range is not a valid pack.

pub fn open_file_range(&self, path: &str, offset: u64, length: u64) -> Result<u32>

open_file_range_with

As open_file_range, with these options.

Errors. As open_file_range, and ErrorCode::InvalidArgument for an outline level above 255.

pub fn open_file_range_with(&self, path: &str, offset: u64, length: u64, options: &OpenOptions) -> Result<u32>

open_bytes

Adds a pack from its bytes (copied). Returns its layer ID, as open_file.

Errors. ErrorCode::Corrupt if the bytes are not a valid pack.

pub fn open_bytes(&self, bytes: &[u8]) -> Result<u32>

open_bytes_with

Adds a pack from its bytes (copied) with these options. Returns its layer ID, as open_file.

Errors. As open_bytes, and ErrorCode::InvalidArgument for an outline level above 255.

pub fn open_bytes_with(&self, bytes: &[u8], options: &OpenOptions) -> Result<u32>

remove

Removes the pack with this layer ID; false if no pack has it. Queries already running finish on the snapshot they started with; the pack's memory is released after them.

pub fn remove(&self, layer: u32) -> bool

layers

The number of packs.

pub fn layers(&self) -> u32

get

The place with this ID (tgd:np/1), or no row; a retired ID gives its survivor.

Errors. ErrorCode::InvalidArgument if id is not a place ID; ErrorCode::Corrupt if a section read is corrupt.

pub fn get(&self, id: &str) -> Result<Blob>

parent

The place's parent as the packs answer for it (one row), or no row for a root or an unknown ID.

Errors. ErrorCode::InvalidArgument if id is not a place ID; ErrorCode::Corrupt if a section read is corrupt.

pub fn parent(&self, id: &str) -> Result<Blob>

ancestors

The place's ancestors, parent first up to the country; no rows for a root or an unknown ID.

Errors. As parent.

pub fn ancestors(&self, id: &str) -> Result<Blob>

children

The place's children, by ID; no rows for a leaf or an unknown ID.

Errors. As parent.

pub fn children(&self, id: &str) -> Result<Blob>

nearby

The places nearest the place with this ID, not counting it, nearest first, at most limit, with meters and bearing (from each place to it); no rows for an unknown ID.

Errors. ErrorCode::InvalidArgument if id is not a place ID or limit exceeds LIMIT_MAX; ErrorCode::Corrupt if a section read is corrupt.

pub fn nearby(&self, id: &str, limit: u32) -> Result<Blob>

Places matching query, best first, at most limit; "Name, Parent" ranks a named parent first. The score column compares only within one query.

Errors. ErrorCode::InvalidArgument if limit exceeds LIMIT_MAX; ErrorCode::Corrupt if a section read is corrupt.

pub fn search(&self, query: &str, limit: u32) -> Result<Blob>

search_with

search ranked by options: near a focus point, or in strict match order.

Errors. ErrorCode::InvalidArgument if limit exceeds LIMIT_MAX, the focus is off the globe or has one coordinate only, or its scale is not positive; ErrorCode::Corrupt if a section read is corrupt.

pub fn search_with(&self, query: &str, limit: u32, options: &SearchOptions) -> Result<Blob>

reverse

The places nearest the point, nearest first, at most limit, with meters and bearing (degrees clockwise from north, from each place to the point).

Errors. ErrorCode::InvalidArgument for a point off the globe or a limit above LIMIT_MAX; ErrorCode::Corrupt if a section read is corrupt.

pub fn reverse(&self, lat: f64, lon: f64, limit: u32) -> Result<Blob>

within_radius

The places within radius_m metres of the point (great-circle), nearest first, at most limit, with meters and bearing (from each place to the point).

Errors. ErrorCode::InvalidArgument for a point off the globe, a negative or non-finite radius, or a limit above LIMIT_MAX; ErrorCode::Corrupt if a section read is corrupt.

pub fn within_radius(&self, lat: f64, lon: f64, radius_m: f64, limit: u32) -> Result<Blob>

admin_at

The admin units holding the point, country first.

Errors. ErrorCode::InvalidArgument for a point off the globe; ErrorCode::Corrupt if a section read is corrupt.

pub fn admin_at(&self, lat: f64, lon: f64) -> Result<Blob>

elevation_at

The terrain height at the point, as one row: meters above the datum (bilinear between the DEM samples around it), source (the DEM product's key, null where the pack does not state it), resolution_m (the sample spacing north to south) and datum (EGM2008). No row where no pack has terrain there (the sea, outside every grid).

Errors. ErrorCode::InvalidArgument for a point off the globe; ErrorCode::Corrupt if a grid read is corrupt.

pub fn elevation_at(&self, lat: f64, lon: f64) -> Result<Blob>

postal_lookup

The places postal code code names, one row per code and place, with the code's postal, scheme, code_kind, valid_from and valid_to columns. scheme names one scheme (np, gb); empty means every scheme whose rule accepts the input. The code may be typed with or without separators, in any case, or in another script's digits. Retired codes are returned too, with their validity.

Errors. ErrorCode::Corrupt if a section read is corrupt.

pub fn postal_lookup(&self, code: &str, scheme: &str) -> Result<Blob>

postal_prefix

Up to limit postal codes starting with prefix, with their places (autocomplete), in code order per scheme; scheme as in postal_lookup.

Errors. ErrorCode::InvalidArgument if limit exceeds LIMIT_MAX; ErrorCode::Corrupt if a section read is corrupt.

pub fn postal_prefix(&self, prefix: &str, scheme: &str, limit: u32) -> Result<Blob>

postal_codes_of

The postal codes of the place with this ID; no rows for an unknown ID.

Errors. ErrorCode::InvalidArgument if id is not a place ID; ErrorCode::Corrupt if a section read is corrupt.

pub fn postal_codes_of(&self, id: &str) -> Result<Blob>

postal_at

The postal codes of the point: those of the deepest admin unit holding it that an admin-aligned scheme gives codes to, with its parts (a ward's code; the point is in one of them). No rows where no unit holding the point has such codes.

Errors. ErrorCode::InvalidArgument for a point off the globe; ErrorCode::Corrupt if a section read is corrupt.

pub fn postal_at(&self, lat: f64, lon: f64) -> Result<Blob>

tz_at

The time-zone area holding the point (one row; its tz column is the IANA zone), or no row where no pack answers.

Errors. ErrorCode::InvalidArgument for a point off the globe; ErrorCode::Corrupt if a section read is corrupt.

pub fn tz_at(&self, lat: f64, lon: f64) -> Result<Blob>

tz_offset_at

The UTC offset in force in zone (a tzdb name or link, Asia/Kathmandu) at unix_seconds, from the first layer whose zone rules hold the zone: one row with seconds east of UTC, dst (1 when tzdb counts it as daylight saving time) and abbr (+0545, EDT); no row where no layer holds the zone.

Errors. ErrorCode::InvalidArgument for an instant outside the years ±9,999; ErrorCode::MissingComponent if the rules that would hold the zone were not installed; ErrorCode::Corrupt if they are corrupt.

pub fn tz_offset_at(&self, zone: &str, unix_seconds: i64) -> Result<Blob>

tz_local

The offsets a civil time may have in zone: one row with kind (unique, gap for a time a transition skips, overlap for one that happens twice), before and after in seconds east of UTC (the offsets before and after the transition: for an overlap the earlier and the later instant's; for a unique time both the same); no row where no layer holds the zone.

Errors. ErrorCode::InvalidArgument for a date that is not one of the years ±9,999 or a time out of range; otherwise as Engine::tz_offset_at.

pub fn tz_local(&self, zone: &str, year: i32, month: u32, day: u32, hour: u32, minute: u32, second: u32) -> Result<Blob>

tz_zones

Every zone name (tzdb names and links) the layers' zone rules hold, in byte order: one zone column.

Errors. ErrorCode::MissingComponent if no installed layer has rules and one has rules that were not installed.

pub fn tz_zones(&self) -> Result<Blob>

tz_rules_start

The earliest instant zone's rules cover, in Unix seconds: one unix row (its first transition, before which tzdb knows only local mean time; the year −9,999 for a zone that never changed); no row where no layer holds the zone.

Errors. As Engine::tz_offset_at.

pub fn tz_rules_start(&self, zone: &str) -> Result<Blob>

tz_version

The tzdb release (2026f) of the first layer with zone rules; empty without rules.

pub fn tz_version(&self) -> String

by_iso

The place whose ISO 3166 code is code (NP, NP-P3, either case), or no row.

Errors. ErrorCode::InvalidArgument if code is not an ISO 3166 code; ErrorCode::Corrupt if a section read is corrupt.

pub fn by_iso(&self, code: &str) -> Result<Blob>

boundary

The outline of the place with this ID at level of detail lod, as one row: id, lod (the level read: 0 from a pack stored at full resolution only), tolerance_m (how far it may stray from the full-resolution outline), vertices and geojson, an RFC 7946 Feature ready for a map: a Polygon or MultiPolygon (outer rings counterclockwise, holes clockwise), or the place's Point when it has no outline. Level 0 is full resolution and 1 to COARSEST_LOD coarser; neighbours share their borders at every level. A whole country at level 0 can be megabytes: ask a coarser level to draw it small. No row for an unknown ID.

Errors. ErrorCode::InvalidArgument if id is not a place ID or lod exceeds COARSEST_LOD; ErrorCode::MissingComponent without boundaries; ErrorCode::Corrupt if a section read is corrupt.

pub fn boundary(&self, id: &str, lod: u32) -> Result<Blob>

distance

The great-circle distance between the places with these IDs, as one row: meters on the mean Earth sphere and bearing, the initial bearing from from to to in degrees clockwise from north. No row when either ID is unknown. From a point, use distance_m and bearing_deg with the place's lat and lon.

Errors. ErrorCode::InvalidArgument if an ID is not a place ID; ErrorCode::Corrupt if a section read is corrupt.

pub fn distance(&self, from: &str, to: &str) -> Result<Blob>

On this page