C
teigeodata from C: a stable C ABI with pkg-config and CMake files, and a header-only reader for results.
The C library is the ABI every other binding builds on: plain functions, opaque handles, status codes, and no global state but each thread's last error. Its header is checked against the last release's on every change, so a minor release never breaks a program built against it.
Every example on this page ran
The code below is cut from one program, the tour, which CI runs on the released
public pack world-np-lite.tgd (data-2026.11.14.3) and checks line by line against the
output shown here. The output is the same in every language.
Install
From the first release: unpack teigeodata-c-<version>-<target>.tar.gz, which holds the headers,
the shared and static libraries, a pkg-config file and a CMake package.
cc tour.c $(pkg-config --cflags --libs teigeodata) -o tourfind_package(teigeodata REQUIRED)
target_link_libraries(tour PRIVATE teigeodata::teigeodata)Get a pack
Queries read packs: signed, memory-mapped files of places. This guide uses the world lite pack: the world's countries, first-level units and cities of 5,000 or more, India's districts and statutory towns, and Nepal in full, 172,339 places named in Nepali, Hindi and English (15.6 MB, CC BY 4.0):
curl -LO https://github.com/teispace/teigeodata/releases/download/data-2026.11.14.3/world-np-lite.tgd
shasum -a 256 world-np-lite.tgd # 243ae55509a538b1f61da50994a791cc78e7deb70bb4bf743b9f59d458cbe3f3An app ships a pack inside its bundle, or downloads one when a user needs it. Once the signed catalog is live, the store does that download for you: it verifies every byte and keeps the packs updated.
Read a result
Every query writes a result blob into a tg_bytes you free with tg_bytes_free.
teigeodata_reader.h (header-only, C99) reads it in place: tg_reader_init checks the layout
once, then tg_reader_find names a column and tg_reader_string, tg_reader_number,
tg_reader_int and tg_reader_is_null read a row of it without allocating. The tour wraps them
in a few helpers:
#define TEXT(s) (const uint8_t *)(s), strlen(s)
/* Exits with the thread's last error when a call failed. */
static void check(int32_t status) {
if (status == TG_OK) return;
tg_bytes message = {0};
tg_last_error(&message);
fprintf(stderr, "error %d: %.*s\n", (int)status, (int)message.len, (const char *)message.ptr);
tg_bytes_free(message);
exit(1);
}
/* A reader over a result the call just wrote into `blob`. */
static tg_reader reader(int32_t status, const tg_bytes *blob) {
check(status);
tg_reader r;
check(tg_reader_init(&r, blob->ptr, blob->len));
return r;
}
/* Column `name` of row `row`: a string ("" where null), a number, an integer. */
static tg_str str(const tg_reader *r, const char *name, uint32_t row) {
tg_str s = tg_reader_string(r, tg_reader_find(r, name), row);
if (s.ptr == NULL) s.ptr = "";
return s;
}
static double num(const tg_reader *r, const char *name, uint32_t row) {
return tg_reader_number(r, tg_reader_find(r, name), row);
}
static long long integer(const tg_reader *r, const char *name, uint32_t row) {
return (long long)tg_reader_int(r, tg_reader_find(r, name), row);
}
#define S(r, name, row) (int)str(r, name, row).len, str(r, name, row).ptrA tg_str points into the blob: copy it if you need it after tg_bytes_free.
Open a pack
An Engine holds the packs it answers from. tg_engine_open_file memory-maps a pack file and
adds it as a layer; the engine answers from every layer at once, and a higher layer wins
where two disagree. Opening is cheap: the head of the file is read and checked and the block hashes of large
sections are proved; each section is verified against its hash the first time a query reads
it.
tg_engine *engine = NULL;
check(tg_engine_new(&engine));
uint32_t layer = 0, layers = 0;
check(tg_engine_open_file(engine, TEXT(pack), &layer));
check(tg_engine_layers(engine, &layers));
printf("layers: %u\n", layers);layers: 1tg_engine_open_bytesadds a pack from bytes already in memory (a download, an app asset, the browser).tg_engine_open_file_rangeopens a pack stored uncompressed inside another file, such as an Android APK.- Each
_withform takestg_open_options: precedence over the other packs, when sections are verified (lazy, eager or trusted), whether the file is mapped or read, and which components, languages and outline level to read. tg_engine_open_filereturns the layer's number;tg_engine_removetakes it out again while other threads keep querying. One engine answers from any number of threads at once.
Search by name
tg_engine_search finds places by name, best first. It matches every name a place has, in every
script, and forgives spelling: काठमाडौं, Kathmandu and Kathamandu find the same city, and so do
typos, missing accents and abbreviations. A result row has the place columns (id, name,
kind, level, lat, lon, elevation, parent, tz, iso, population,
population_kind) and a score.
r = reader(tg_engine_search(engine, TEXT("Pokhara"), 3, &blob), &blob);
for (uint32_t i = 0; i < r.rows; i++) {
printf("%.*s %.*s %.*s %.4f, %.4f score %lld\n", S(&r, "id", i), S(&r, "name", i), S(&r, "kind", i),
num(&r, "lat", i), num(&r, "lon", i), integer(&r, "score", i));
}
tg_bytes_free(blob);tgd:np/1xhb Pokhara settlement 28.2669, 83.9680 score 132
tgd:np/1xnr Pokhara admin 28.2094, 83.9818 score 105
tgd:np/15t1 Pokhara settlement 28.0636, 82.3786 score 90The score ranks the rows of one query and means nothing across queries. It adds how well the
name matched to how important the place is, so a city ranks above a village of the same name.
limit is at most 10,000 (TG_LIMIT_MAX).
Narrow a search by its parent
Write the place's parent after a comma, as people do: "Kathmandu, Bagmati". Places
inside a unit of that name rank first; the parent can be any ancestor (a district, a province,
a country) and is matched with the same tolerance as the name.
r = reader(tg_engine_search(engine, TEXT("Kathmandu, Bagmati"), 2, &blob), &blob);
for (uint32_t i = 0; i < r.rows; i++) {
printf("%.*s %.*s %.*s %lld\n", S(&r, "id", i), S(&r, "name", i), S(&r, "kind", i), integer(&r, "level", i));
}
tg_bytes_free(blob);tgd:np/2cn Kathmandu settlement 0
tgd:np/2gm Kathmandu admin 3The city (a settlement, level 0) and the metropolitan municipality (an admin unit at level 3) share the name, and both are in Bagmati.
Rank by distance from a point
Many places share a name. tg_engine_search_with takes tg_search_options: a focus point (the
user's location, or the middle of the map they are looking at) ranks near places first. A place
at the focus gains 30 points, one focus_scale_m away 15, and the gain keeps halving with
distance (the default scale is 50 km).
/* Many places share a name; a focus (the user's location) ranks the near ones first. */
tg_search_options options = {0};
options.has_focus_lat = true;
options.focus_lat = 28.7;
options.has_focus_lon = true;
options.focus_lon = 80.6;
options.has_focus_scale_m = true;
options.focus_scale_m = 30000;
r = reader(tg_engine_search_with(engine, TEXT("Shivapur"), 3, &options, &blob), &blob);
for (uint32_t i = 0; i < r.rows; i++) {
printf("%.*s %.*s %.4f, %.4f\n", S(&r, "id", i), S(&r, "name", i), num(&r, "lat", i), num(&r, "lon", i));
}
tg_bytes_free(blob);tgd:np/2v99 Shivapur 28.5310, 80.8213
tgd:np/2raj Shivapur 28.7141, 80.9869
tgd:np/2rkx Shivapur 28.5061, 81.3032Set strict to rank by how well the name matched first (exact, loose, prefix, one edit,
substring, two edits, phonetic), then by importance and focus, instead of one combined score:
useful for an autocomplete that must show exact matches on top.
Get a place by its ID
Every place has a stable ID such as tgd:np/1xhb: the country, then a short code. IDs
survive rebuilds of the data; when two places are merged, tg_engine_get on the retired ID answers
with the survivor, so IDs you stored keep working.
r = reader(tg_engine_get(engine, TEXT("tgd:np/1xhb"), &blob), &blob);
printf("%.*s %.*s\n", S(&r, "name", 0), S(&r, "kind", 0));
printf("at %.6f, %.6f, %lld m\n", num(&r, "lat", 0), num(&r, "lon", 0), integer(&r, "elevation", 0));
printf("timezone %.*s parent %.*s\n", S(&r, "tz", 0), S(&r, "parent", 0));
tg_bytes_free(blob);Pokhara settlement
at 28.266890, 83.968000, 1006 m
timezone Asia/Kathmandu parent tgd:np/1xnrelevation is metres above mean sea level (EGM2008), tz the IANA zone and parent the
ID of the unit that holds the place. Any column may be null where the data has no value: read
each through the reader, which gives your language's null.
Walk the admin hierarchy
tg_engine_ancestors lists the units that hold a place, parent first, up to its country; tg_engine_parent
gives the first of them alone and tg_engine_children the units and places one level down.
r = reader(tg_engine_ancestors(engine, TEXT("tgd:np/1xhb"), &blob), &blob);
for (uint32_t i = 0; i < r.rows; i++) {
printf("%.*s %lld %.*s", S(&r, "kind", i), integer(&r, "level", i), S(&r, "name", i));
if (!tg_reader_is_null(&r, tg_reader_find(&r, "iso"), i)) printf(" %.*s", S(&r, "iso", i));
putchar('\n');
}
tg_bytes_free(blob);
r = reader(tg_engine_children(engine, TEXT("tgd:np/295c"), &blob), &blob);
printf("Kaski has %u children\n", r.rows);
tg_bytes_free(blob);admin 3 Pokhara
admin 2 Kaski
admin 1 Gandaki NP-P4
country 0 Nepal NP
Kaski has 5 childrenlevel is the admin level as each country defines it: 0 is a country (and a settlement,
which is not a unit), 1 a province or state, and so on down to the lowest level the data has.
Each country's ladder is in its profile on the data pages.
Reverse geocode a point
tg_engine_reverse gives the places nearest a point, nearest first, each with meters (the
great-circle distance) and bearing (degrees clockwise from north, from the place to the
point: "3.2 km at 45° from Pokhara").
r = reader(tg_engine_reverse(engine, 27.7172, 85.3240, 3, &blob), &blob);
for (uint32_t i = 0; i < r.rows; i++) {
printf("%.*s %.0f m at %.0f°\n", S(&r, "name", i), num(&r, "meters", i), num(&r, "bearing", i));
}
tg_bytes_free(blob);Narayanhiti Royal Palace 331 m at 116°
Gairidhara 375 m at 220°
Naxal 384 m at 329°For the admin units that hold a point (its district, province and country) use
tg_engine_admin_at below; reverse answers with what is near it.
Find everything within a radius
tg_engine_within_radius gives the places within a distance of a point, nearest first, with the
same meters and bearing columns, at most limit of them.
r = reader(tg_engine_within_radius(engine, 27.7172, 85.3240, 500, 10, &blob), &blob);
printf("%u places within 500 m; farthest %.0f m\n", r.rows, num(&r, "meters", r.rows - 1));
tg_bytes_free(blob);3 places within 500 m; farthest 384 mFind places near a place
tg_engine_nearby is reverse geocoding from a place you already have: the places nearest it,
itself left out.
r = reader(tg_engine_nearby(engine, TEXT("tgd:np/2cn"), 3, &blob), &blob);
for (uint32_t i = 0; i < r.rows; i++) printf("%.*s %.0f m\n", S(&r, "name", i), num(&r, "meters", i));
tg_bytes_free(blob);Bhrikuti Mandap 168 m
Bagbazar 354 m
Shahidgate 393 mAdmin units at a point, and ISO 3166 codes
tg_engine_admin_at tests the point against the admin boundaries and gives every unit that holds
it, country first. tg_engine_by_iso finds a country or a subdivision by its ISO 3166 code (NP,
NP-P4, in either case).
r = reader(tg_engine_admin_at(engine, 28.2096, 83.9856, &blob), &blob);
for (uint32_t i = 0; i < r.rows; i++) {
printf("%lld %.*s", integer(&r, "level", i), S(&r, "name", i));
if (!tg_reader_is_null(&r, tg_reader_find(&r, "iso"), i)) printf(" %.*s", S(&r, "iso", i));
putchar('\n');
}
tg_bytes_free(blob);
r = reader(tg_engine_by_iso(engine, TEXT("NP-P4"), &blob), &blob);
printf("NP-P4 is %.*s %.*s\n", S(&r, "name", 0), S(&r, "id", 0));
tg_bytes_free(blob);0 Nepal NP
1 Gandaki NP-P4
2 Kaski
3 Pokhara
NP-P4 is Gandaki tgd:np/2922Boundaries are exact polygons, so a point near a border is answered by the side it is on, not by the nearest centre. Disputed boundaries are drawn from one stated perspective; see accuracy.
Timezones: the zone, its offset and local times
tg_engine_tz_at gives the IANA zone at a point as the zone boundaries draw it. With the zone,
tg_engine_tz_offset_at gives the UTC offset at an instant (from the tzdb rules inside the pack, not
from the operating system), and tg_engine_tz_local tells whether a wall-clock time exists: unique,
gap (skipped by a daylight-saving change) or overlap (it happens twice), with the offsets
before and after.
tg_bytes area = {0}, at = {0}, local = {0}, version = {0};
tg_reader zr = reader(tg_engine_tz_at(engine, 27.7172, 85.3240, &area), &area);
tg_str zone = str(&zr, "tz", 0);
r = reader(tg_engine_tz_offset_at(engine, (const uint8_t *)zone.ptr, zone.len, 1700000000, &at), &at);
printf("%.*s %lld s east of UTC, %.*s dst %lld\n", (int)zone.len, zone.ptr, integer(&r, "seconds", 0),
S(&r, "abbr", 0), integer(&r, "dst", 0));
r = reader(tg_engine_tz_local(engine, TEXT("America/New_York"), 2026, 3, 8, 2, 30, 0, &local), &local);
printf("02:30 on 2026-03-08 in New York: %.*s %lld -> %lld\n", S(&r, "kind", 0), integer(&r, "before", 0),
integer(&r, "after", 0));
check(tg_engine_tz_version(engine, &version));
printf("tzdb %.*s\n", (int)version.len, (const char *)version.ptr);
tg_bytes_free(area);
tg_bytes_free(at);
tg_bytes_free(local);
tg_bytes_free(version);Asia/Kathmandu 20700 s east of UTC, +0545 dst 0
02:30 on 2026-03-08 in New York: gap -18000 -> -14400
tzdb 2026ftg_engine_tz_version names the tzdb release the rules come from, so you can tell when a pack is
older than a rule change; tg_engine_tz_zones lists every zone the packs hold.
Elevation at any point
tg_engine_elevation_at reads the terrain height at a point from the pack's elevation grid,
interpolated between the four samples around it: meters above EGM2008, the source product,
the grid's resolution_m and the datum. There is no row at sea or outside every grid.
r = reader(tg_engine_elevation_at(engine, 27.7172, 85.3240, &blob), &blob);
printf("%.1f m above %.*s (%.*s, %.0f m grid)\n", num(&r, "meters", 0), S(&r, "datum", 0), S(&r, "source", 0),
num(&r, "resolution_m", 0));
tg_bytes_free(blob);1304.2 m above EGM2008 (nasadem, 464 m grid)Every place also has its own elevation column. The world pack carries a coarse grid; a
country's terrain pack adds a finer one, and the engine answers from the finest grid that covers
the point.
Distance and bearing
tg_distance_m is the great-circle distance in metres (haversine on the WGS84 mean
sphere, within about 0.5% of the ellipsoid), and tg_bearing_deg the initial bearing from the
first point to the second, in degrees clockwise from north. Neither needs a pack. Between two
places you already have, tg_engine_distance takes their IDs and answers one row with meters and
bearing.
double meters = 0;
check(tg_distance_m(27.7172, 85.3240, 28.2096, 83.9856, &meters));
double heading = 0;
check(tg_bearing_deg(27.7172, 85.3240, 28.2096, 83.9856, &heading));
printf("Kathmandu to Pokhara: %.1f km, heading %.0f°\n", meters / 1000, heading);
r = reader(tg_engine_distance(engine, TEXT("tgd:np/2cn"), TEXT("tgd:np/1xhb"), &blob), &blob);
printf("place to place: %.1f km at %.0f°\n", num(&r, "meters", 0) / 1000, num(&r, "bearing", 0));
tg_bytes_free(blob);Kathmandu to Pokhara: 142.4 km, heading 293°
place to place: 146.9 km at 296°tg_engine_distance answers no row when either ID is unknown. From a point to a place, pass the
place's lat and lon to tg_distance_m. The bearing is the direction you set off in: on a
great circle it changes along the way, so the bearing back is not the reverse of this one.
A place's outline
tg_engine_boundary answers a unit's outline as one row: geojson, an RFC 7946 Feature (a
Polygon or MultiPolygon, outer rings counterclockwise and holes clockwise, seven decimals as
stored), with the lod read, its tolerance_m and the number of vertices. A place with no
outline answers its point as the geometry; an unknown ID answers no row.
r = reader(tg_engine_boundary(engine, TEXT("tgd:np/2gm"), 0, &blob), &blob);
tg_str geojson = str(&r, "geojson", 0); /* a GeoJSON Feature, for any map library */
const char *type = strstr(geojson.ptr, "\"geometry\":{\"type\":\"") + 20;
printf("%.*s of %lld vertices at level %lld\n", (int)strcspn(type, "\""), type, integer(&r, "vertices", 0),
integer(&r, "lod", 0));
printf("tolerance %.0f m, %zu bytes of GeoJSON\n", num(&r, "tolerance_m", 0), geojson.len);
tg_bytes_free(blob);Polygon of 176 vertices at level 0
tolerance 0 m, 4362 bytes of GeoJSONThe Feature goes to a map as it is: MapLibre's and Leaflet's GeoJSON sources, OpenLayers,
Shapely's shape(), Turf and JTS all read it.
- Level of detail.
lod0 is full resolution; 1 to 6 are coarser, each within itstolerance_m, with neighbouring units still sharing their borders at every level. A pack stored at full resolution only (the lite packs) answers every level as 0. A country at level 0 can be megabytes: draw a coarser level, and keep 0 for measuring. lodabove 6 isInvalidArgument; a pack installed withoutboundariesisMissingComponent.- Whether a point is inside a unit is
tg_engine_admin_at, which tests the same outlines without building them.
Errors
A call fails with one of eight stable codes, the same in every language:
| Code | Meaning |
|---|---|
InvalidArgument | An argument is outside its range: a latitude of 91, a limit over 10,000, a malformed ID. |
MissingComponent | The query needs a component the pack was installed without (search on a pack installed without search). |
Corrupt | The bytes are not a valid pack, or a section does not match its hash. |
Io | A file could not be read. |
Network | No mirror answered, or the connection broke (the store only). |
Refused | The store refused: the catalog did not verify, a pack is not installed or another needs it. |
Cancelled | A callback or a job was asked to stop. |
Internal | A bug inside teigeodata; a panic never crosses into your program. |
A query that finds nothing is not an error: it returns no rows.
Every function returns TG_OK (0) or an error code (TG_ERROR_INVALID_ARGUMENT, …);
tg_last_error gives the calling thread's message:
if (tg_engine_reverse(engine, 91, 0, 1, &blob) == TG_ERROR_INVALID_ARGUMENT) {
tg_bytes message = {0};
tg_last_error(&message);
printf("invalid argument: %.*s\n", (int)message.len, (const char *)message.ptr);
tg_bytes_free(message);
}invalid argument: (91, 0) is not a point: the latitude is outside -90 to 90 degreesThreads and memory
Handles are thread-safe: any number of threads may query one tg_engine at once. Every
tg_bytes the library returns is freed with tg_bytes_free, every handle with its _free; a
panic inside the library is caught at the boundary and returned as TG_ERROR_INTERNAL.
The whole program
Run it from a checkout of the repository, which builds what the language needs, fetches the pinned pack and compares the output:
cargo xtask docs-examples --fetch --check --lang c