Skip to Content
teigeodata

Packs and components

What is inside a pack, how it is verified, the components you can leave out, and how packs stack as layers.

A pack is one file (.tgd) of places and everything known about them: names, heights, the hierarchy, boundaries, timezones, postal codes and the search index. Packs are built by the forge from open sources, signed, and published in releases.

Built to be mapped

A pack is laid out to be read where it lies: the engine memory-maps the file and reads the bytes it needs, with no parsing step and no copy into the heap. Opening a 15 MB pack reads its head (at most 16 KiB) and proves the block hashes of its large sections, and nothing else; a query touches only the pages it reads, which the operating system shares between processes and drops under memory pressure.

  • Verified as it is read. Every section carries a BLAKE3 hash in the head, and every 16 KiB block of a large section has its own. By default a section, or a block, is checked the first time a query reads it (Verify::Lazy); Eager checks everything when the pack opens.
  • Signed. Released packs are signed with Ed25519 over the head, which holds every section's hash. tgd verify --key checks a signature; the store checks every pack it installs against the signed catalog. The data pre-releases published so far are not signed yet: check them by the SHA-256 their release lists, until the signing key is made for 1.0.
  • Forward compatible. A reader skips sections it does not know, so older code keeps reading newer packs, and a pack states the oldest reader that can open it.

Components

A pack is cut into components, each a set of sections. Install, download or link only the ones your app uses; a query that needs a component you left out fails with MissingComponent instead of answering wrongly.

ComponentWhat it holdsNeeds
pointIDs, coordinates, kinds, the spatial index and retired IDs
namesEvery name of every placepoint
searchThe name search indexnames
substringSearch from three or more characters inside a wordsearch
adminParents, children and ISO 3166 codespoint
boundariesThe outlines of admin units, as shared arcspoint
admin-indexThe admin units at any pointboundaries
elevationEach place's heightpoint
dem, dem-coarseElevation grids: a country's terrain, and a coarse grid of the world
timezoneEach place's timezonepoint, tz-rules
timezone-indexThe timezone at any pointpoint, tz-rules
tz-rulesThe tzdb rules: offsets at any instant, local times
postalPostal codes, current and formerpoint
extraOptional fields and cold datapoint

The world lite pack, by component (disk and compressed wire bytes, data-2026.11.14.3):

ComponentDiskWireDownload with what it needs
point1.60 MB1.06 MB1.06 MB
elevation0.32 MB0.23 MB1.29 MB
admin0.71 MB0.28 MB1.34 MB
names4.60 MB1.83 MB2.91 MB
search4.47 MB2.91 MB5.81 MB
timezone0.06 MB0.01 MB1.14 MB
boundaries2.19 MB2.03 MB3.11 MB
admin-index1.07 MB0.80 MB3.91 MB
tz-rules0.08 MB0.06 MB0.07 MB
dem-coarse0.53 MB0.52 MB0.52 MB

So an app that only finds the nearest named place to a point needs point and names: 2.9 MB on the wire instead of 9.8 MB. The libraries are cut the same way: each language's build can leave out the code of components it does not use (the WebAssembly package has a smaller -lookup build without name search).

A pack also splits by language (install the names of up to eight languages besides the base names) and by outline detail (install a country's boundaries down to a level, simplified to a tolerance in metres). OpenOptions and the store's install options take the same choices.

Layers

An engine answers from several packs at once; each is a layer. Where layers hold the same place, one rule decides which answers: the higher priority you give, then the newer release, then the more specific pack (a country over the world), then the pack's address as a last tie-break, and the baseline always last. So a detailed country pack overrides the world pack inside that country, while the world pack still answers everywhere else. The answers do not depend on the order the packs were added (a CI gate splits packs and compares). Typical stacks:

  • One world pack bundled with the app: every country, its first-level units and its cities, and the full detail of the countries you serve.
  • A world baseline plus country packs downloaded on demand: the user opens "Dubai", the app installs the UAE pack, and the engine answers from both.
  • Terrain packs (dem) added over the coarse world grid where heights must be precise.

Layers can be added and removed while other threads query: each change publishes a new snapshot, and queries already running finish on the one they started with.

Where packs come from

Today, packs are published as data pre-releases on GitHub, with checksums: download one and open it. Once the signed catalog is live, the store finds, downloads, verifies and updates packs for you.

On this page