Routing API (not callable yet) | geolith Routing docs

Status: in development, not deployed for public use. None of these endpoints is callable yet. Neither geolith.app nor api.geolith.app answers them, and there is no hosted API and no pricing. The router answers every example below on a test deployment; this page describes the bodies so you can check a client against them.

Valhalla-compatible

Request and response bodies are Valhalla's, as documented in the Valhalla API reference. Paths are kebab-case only: a Valhalla client changes only the path (for example /sources_to_targets becomes /sources-to-targets). Each endpoint takes the request JSON as a POST body, or as ?json= on a GET.

Endpoint	Answers
`/route`	A route between two or more locations
`/isochrone`	Areas reachable within a time or a distance
`/sources-to-targets`	A time and distance matrix
`/trace-route`	A route matched to a GPS trace
`/trace-attributes`	The edges and their attributes along a GPS trace
`/status`	The service version and the available actions

Costing: auto, pedestrian and bicycle.
Time: date_time types 0 (current) and 1 (depart at) use historical speeds; see Traffic and live data. Types 2 (arrive by) and 3 (invariant) return error 199 for now.
Traffic: live speeds and closures are supplied by the program that runs the router. No hosted service collects them.
Instructions: maneuvers carry text and spoken (verbal_*) instructions, in English only.

ROUTER_HOST below stands for a router you run yourself; see Self-hosting. The examples show the requests; the responses are Valhalla's shapes.

/route

curl -X POST "https://ROUTER_HOST/route" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      { "lat": 52.5163, "lon": 13.3777 },
      { "lat": 52.5079, "lon": 13.3376 }
    ],
    "costing": "auto",
    "units": "kilometers"
  }'

The response is a trip with its legs, each with maneuvers, a summary (length and time) and a shape encoded as a polyline with precision 6.

/isochrone

curl -X POST "https://ROUTER_HOST/isochrone" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [{ "lat": 52.5163, "lon": 13.3777 }],
    "costing": "pedestrian",
    "contours": [{ "time": 10 }],
    "polygons": true
  }'

The response is GeoJSON: one feature per contour, as lines or polygons.

/sources-to-targets

curl -X POST "https://ROUTER_HOST/sources-to-targets" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{ "lat": 52.5163, "lon": 13.3777 }],
    "targets": [
      { "lat": 52.5079, "lon": 13.3376 },
      { "lat": 52.5200, "lon": 13.4050 }
    ],
    "costing": "auto"
  }'

The response holds the time and distance from every source to every target.

/trace-route

curl -X POST "https://ROUTER_HOST/trace-route" \
  -H "Content-Type: application/json" \
  -d '{
    "shape": [
      { "lat": 52.5163, "lon": 13.3777 },
      { "lat": 52.5160, "lon": 13.3740 },
      { "lat": 52.5155, "lon": 13.3700 }
    ],
    "costing": "auto",
    "shape_match": "map_snap"
  }'

The response is a trip, like /route, along the matched roads.

/trace-attributes

curl -X POST "https://ROUTER_HOST/trace-attributes" \
  -H "Content-Type: application/json" \
  -d '{
    "shape": [
      { "lat": 52.5163, "lon": 13.3777 },
      { "lat": 52.5160, "lon": 13.3740 },
      { "lat": 52.5155, "lon": 13.3700 }
    ],
    "costing": "auto",
    "shape_match": "map_snap"
  }'

The response lists the matched edges with their attributes and the matched points.

/status

curl "https://ROUTER_HOST/status"

{
  "version": "3.9.1",
  "available_actions": [
    "status",
    "route",
    "isochrone",
    "sources-to-targets",
    "trace-route",
    "trace-attributes"
  ],
  "tileset_last_modified": 1794106434
}

Errors

Errors take Valhalla's error body: error_code, error, status_code and status. For example, a date_time of type 2 or 3 returns error 199.