Valhalla Routing API

Valhalla is an open-source routing engine that provides turn-by-turn directions, time/distance matrices, isochrones, map matching, and more, across auto, bicycle, and pedestrian travel modes. Valhalla uses dynamic costing, allowing routing parameters to be customized per request rather than baked into the routing graph at build time.

The Interline Routing Platform exposes Valhalla endpoints at:

https://transit.land/api/v2/routing/valhalla/{endpoint}

Pass your API key as the apikey query parameter or apikey header. For GET requests, the JSON payload is passed as the json query parameter. For POST requests, it is sent as the request body with Content-Type: application/json.

# GET
curl --get "https://transit.land/api/v2/routing/valhalla/route" \
  -H "apikey: YOUR_API_KEY" \
  --data-urlencode 'json={...}'

# POST
curl -X POST "https://transit.land/api/v2/routing/valhalla/route" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Requests follow the same request/response format as the open-source Valhalla project. See the Valhalla API documentation for full parameter references for each endpoint.

Routing graph

The global Valhalla routing graph is updated approximately daily using Interline Valhalla Tilepacks, which are built from the latest updates to OpenStreetMap and also include Tilezen elevation tiles.

Travel modes (costings)

The Valhalla endpoints support the following travel modes via the costing parameter:

For full details on each costing model and its options, see the Valhalla costing models reference.

Endpoints

Route (/route)

Plan a turn-by-turn route between two or more locations.

curl --get "https://transit.land/api/v2/routing/valhalla/route" \
  -H "apikey: YOUR_API_KEY" \
  --data-urlencode 'json={"locations":[{"lat":37.789,"lon":-122.401},{"lat":37.782,"lon":-122.447}],"costing":"bicycle"}'

Reference: Valhalla turn-by-turn API reference

Optimized Route (/optimized_route)

Find an optimized route through multiple locations (traveling salesman problem). Returns a route that visits all specified locations in the most efficient order.

curl -X POST "https://transit.land/api/v2/routing/valhalla/optimized_route" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locations":[{"lat":37.789,"lon":-122.401},{"lat":37.776,"lon":-122.418},{"lat":37.782,"lon":-122.447}],"costing":"auto"}'

Reference: Valhalla optimized route API reference

Matrix (/sources_to_targets)

Compute a time and distance matrix between a set of source locations and a set of target locations.

curl --get "https://transit.land/api/v2/routing/valhalla/sources_to_targets" \
  -H "apikey: YOUR_API_KEY" \
  --data-urlencode 'json={"sources":[{"lat":37.789,"lon":-122.401}],"targets":[{"lat":37.782,"lon":-122.447},{"lat":37.776,"lon":-122.418}],"costing":"pedestrian"}'

Reference: Valhalla matrix API reference

Isochrone (/isochrone)

Compute isochrone (equal-travel-time) or isodistance contours around one or more locations. Returns a GeoJSON FeatureCollection.

curl --get "https://transit.land/api/v2/routing/valhalla/isochrone" \
  -H "apikey: YOUR_API_KEY" \
  --data-urlencode 'json={"locations":[{"lat":37.789,"lon":-122.401}],"costing":"pedestrian","contours":[{"time":10}]}'

Reference: Valhalla isochrone API reference

Map Matching (/trace_route, /trace_attributes)

Match a sequence of GPS coordinates to the road network. /trace_route returns a route with turn-by-turn instructions; /trace_attributes returns detailed attributes for each matched edge.

curl -X POST "https://transit.land/api/v2/routing/valhalla/trace_route" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shape":[{"lat":37.789,"lon":-122.401},{"lat":37.787,"lon":-122.408},{"lat":37.785,"lon":-122.415}],"costing":"pedestrian","shape_match":"map_snap"}'

curl -X POST "https://transit.land/api/v2/routing/valhalla/trace_attributes" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shape":[{"lat":37.789,"lon":-122.401},{"lat":37.787,"lon":-122.408},{"lat":37.785,"lon":-122.415}],"costing":"pedestrian","shape_match":"map_snap"}'

Reference: Valhalla map matching API reference

Locate (/locate)

Return detailed information about the road network near one or more input coordinates.

curl --get "https://transit.land/api/v2/routing/valhalla/locate" \
  -H "apikey: YOUR_API_KEY" \
  --data-urlencode 'json={"locations":[{"lat":37.789,"lon":-122.401}],"costing":"auto"}'

Reference: Valhalla locate API reference

Expansion (/expansion)

Return a GeoJSON representation of the graph traversal performed for an isochrone or shortest-path search. Useful for debugging and visualizing routing behavior.

curl --get "https://transit.land/api/v2/routing/valhalla/expansion" \
  -H "apikey: YOUR_API_KEY" \
  --data-urlencode 'json={"locations":[{"lat":37.789,"lon":-122.401}],"costing":"pedestrian","action":"isochrone","contours":[{"time":5}]}'

Reference: Valhalla expansion API reference

Centroid (/centroid)

Find the optimal meeting point (centroid) for a set of locations — the point that minimizes total travel time from all origins.

curl -X POST "https://transit.land/api/v2/routing/valhalla/centroid" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locations":[{"lat":37.789,"lon":-122.401},{"lat":37.782,"lon":-122.447},{"lat":37.776,"lon":-122.418}],"costing":"pedestrian"}'

Reference: Valhalla centroid API reference