Routing docs

Routing overview

geolith Routing is in development and not deployed for public use: a Rust router with a Valhalla-compatible API (route, isochrone, matrix, map matching) that answers from the routing part of a .glx file geolith builds, read in HTTP ranges. What it is, how it works, and its status.

By · Updated

Warning

Status: in development. Not deployed for public use. There is no routing endpoint on geolith.app or api.geolith.app, no hosted API and no pricing. The router and geolith's routing builder both work: on Berlin, routes on geolith-built tiles are byte-identical to Valhalla 3.9.1. A test Worker on workers.dev answers routes, but too slowly to offer yet. Until routing launches, the hosted platform offers geocoding and vector tiles (India tile set today; planet tiles in development) only. See Status and roadmap.

geolith Routing turns OpenStreetMap into a road graph and answers routing requests from it. The geolith builder writes the graph as the routing part of a .glx file. A router, written in Rust, reads that part in byte ranges and answers six endpoints with Valhalla-compatible request and response bodies: /route, /isochrone, /sources-to-targets, /trace-route, /trace-attributes and /status. A Valhalla client changes only the URL.

How it works

OpenStreetMap .osm.pbf        │        ▼geolith builder (Rust)  tag rules → parse → edges → access → turn restrictions  → enhance → hierarchy → shortcuts  → graph tiles on three grids (4°, 1°, 0.25°)        │        ▼.glx file  file header (256 bytes) → routing part:  routing header · tile index · zstd dictionary  · tiles, each a block directory + 64 KiB zstd blocks        │  HTTP range requests for the blocks a request touches        ▼router (Rust, built to WebAssembly, in a Cloudflare Worker)  snap locations → search the road hierarchy → build the answer        │        ▼Valhalla-compatible JSON
  • One file, no database. The router keeps the tile index in memory and fetches only the 64 KiB blocks of the tiles a request touches. The file can sit in R2 or on local disk.
  • Separate from search. A .glx file holds parts: SRCH for search, ROUT for routing. Search and routing are planned as two hosted files, so they update independently. See The routing part.
  • Edge only, no servers. The router library (geolith-router) is pure Rust and does no I/O of its own: it asks for the bytes it needs and the program around it fetches them. The same code runs as WebAssembly in a Cloudflare Worker reading from R2. See Self-hosting.

Pages

  • How it works: from OpenStreetMap to a response, step by step, and where each piece of data lives.
  • The routing part: the byte layout of the routing part of a .glx file and how a reader reads it.
  • API: the six Valhalla-compatible endpoints, with one example each. Not callable yet.
  • Self-hosting: the router library, the Worker app, and the latency measured on the edge.
  • Traffic and live data: historical speeds in the routing part, and live speeds and closures supplied by the caller.
  • Status and roadmap: what is done, what is in progress, what is next, and the accuracy tables.

Credit

geolith's routing builder, graph tile format and router are ported from Valhalla 3.9.1, released under the MIT license. The graph tiles in a .glx routing part are byte strings in that tile format, and the request and response bodies follow Valhalla's API.