Routing docs

Migrate a Valhalla client

Point a Valhalla client at geolith routing: change the base URL and the path to kebab-case, add a secret API key. Request and response bodies stay the same. Available in 10 cities; what to check before you switch.

By · Updated

geolith routing takes Valhalla's request bodies and returns Valhalla's response bodies. A Valhalla client changes three things. Routing is available in 10 cities; check that your locations are inside one city first (Coverage and errors).

What changes

Valhallageolith
Base URL: http://VALHALLA_HOSTBase URL: https://api.geolith.app/v1
/route/route
/sources_to_targets/sources-to-targets
/isochrone/isochrone
/trace_route/trace-route
/trace_attributes/trace-attributes
No keyA secret key, as Authorization: Bearer

So /sources_to_targets becomes https://api.geolith.app/v1/sources-to-targets.

Paths are kebab-case only. A snake_case path is not served.

What stays

  • The request JSON, as a POST body or as ?json= on a GET.
  • The response JSON: trip, sources_to_targets, the isochrone GeoJSON and the trace answers.
  • Valhalla's error body (error_code, error, status_code, status) for request errors.

Before

const res = await fetch('http://VALHALLA_HOST/sources_to_targets', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request),
});

After

const res = await fetch('https://api.geolith.app/v1/sources-to-targets', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GEOLITH_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(request),
});

Check before you switch

  • Coverage. Locations outside the 10 cities get error 1001. Locations in two cities get error 1002.
  • Costing. auto, pedestrian and bicycle only.
  • Time. date_time types 0 and 1 only. There is no traffic data: speeds are default speeds per road class and country.
  • Size. A matrix may have at most 625 cells, an isochrone at most 4 contours, and a body at most 1 MiB, within the city's limits. Matrix span, isochrone time and distance, and trace length are capped per city, with Valhalla's own limit errors. See Limits per city.
  • Keys. Use a secret key from a server. Do not put it in a web page or an app.
  • New errors. geolith adds codes 1001, 1002 and 1004, and the key and quota errors of api.geolith.app. See Coverage and errors.
  • Units. Each 2xx answer uses routing units from your plan. See Limits, units and plans.

What we compared

In each of the 10 cities, route, matrix, isochrone and map matching answers were compared with Valhalla 3.9.1 built from the same OpenStreetMap data. The tested requests matched byte for byte. Routes the road hierarchy answers are exact. See Status and roadmap.