Skip to Content
teigeodata

Results

Every query returns its rows as named columns in one compact blob, read in place by the same Reader in every language.

Every query of the bindings returns its rows as one result blob: a few bytes of header, then each column stored contiguously. One blob crosses from the engine into your language in a single copy, however many rows it holds, and a Reader reads it in place: whole columns as arrays with no per-row work, or each row as your language's map or record.

from teigeodata.blob import Reader

for place in Reader(engine.search("Pokhara", 3)):   # each row: a dict
    print(place["name"], place["lat"], place["lon"])

reader = Reader(engine.reverse(27.7172, 85.324, 100))  # whole columns, no per-row objects
lats, lons = reader.numbers("lat"), reader.numbers("lon")

The same Reader everywhere

Rows and shapeA whole columnEach row
Pythonreader.rows, reader.columns, hasnumbers, strings, nulls, columniterate: dict
Node.js, WebAssemblyrows, columns, hasnumbers (typed array), strings, nulls, columniterate: object
Swiftrows, columns, hasnumbers, strings, nulls, columniterate: Record
Kotlin and Javarows(), columns(), hasnumbers, strings, nulls, columniterate: Map
Dartrows, columns, hasnumbers, strings, nulls, columniterate: Map
GoRows(), Columns(), HasValues[T], Strings, Nulls, ColumnRecords(): map
Ctg_reader_init, tg_reader_findtg_reader_string, _number, _int, _is_null
C++rows(), columns(), hasnumbers, strings, nulls, columniterate: Row
.NETRows, Columns, HasValues<T> (span), Strings, Nulls, Columniterate: dictionary

Rust's typed engine returns Place values instead; teigeodata-api gives Rust the blobs too.

Place columns

Every query that returns places has these columns:

ColumnTypeNull when
idstringnever
namestringthe place has no name in the languages installed
kindstringthe place's kind is one this reader does not know (a newer pack)
levelintegernever (0 for anything that is not an admin unit)
lat, lonnumber (degrees)never
elevationinteger (metres, EGM2008)no height is known
parentstring (an ID)a root (a country, a timezone area), or a pack without the admin hierarchy
tzstring (an IANA zone)the pack has no timezones there
isostring (ISO 3166)the place has no ISO code
populationinteger (people)no count is known, the place is a former unit, or the layer was installed without extra
population_kindstring: stated (a source's count) or modelled (a population grid over an admin unit)as population

and some queries add their own:

QueryAdded columns
search, search_withscore: compares the rows of one query only
reverse, within_radius, nearbymeters (great-circle distance), bearing (degrees clockwise from north, from the place to the point)
postal queriespostal, scheme, code_kind, valid_from, valid_to

Queries that do not return places have their own columns: elevation_at (meters, source, resolution_m, datum), tz_offset_at (seconds, dst, abbr), tz_local (kind, before, after), tz_zones (zone), distance (meters, bearing), boundary (id, lod, tolerance_m, vertices, geojson). The reference lists every query.

Nulls, numbers and strings

  • Null is not zero. A whole number column reads a null row as zero; check nulls(column) (or read rows, where nulls are your language's null) before trusting a 0.
  • Numbers keep their type. A column is stored as 8, 16, 32 or 64-bit integers or 32 or 64-bit floats; the readers give each in the language's natural type. 64-bit integers are exact to 2^53 where a language has only doubles (JavaScript).
  • Strings are UTF-8, stored once per distinct value where a column repeats (kind, tz): reading them costs a lookup, not a decode per row.

The format

A blob starts with the magic TGB1, the row count, the column count and the total length (16 bytes), then one 40-byte descriptor per column: its name, type, where its values are, where its strings or dictionary are, and where its null bitmap is. Every offset is checked when the reader is made, so no read can leave the blob, even for bytes from an untrusted source. The format is specified in bindings and tested in every language against the same fixtures, including malformed blobs each reader must refuse.

On this page