Routing API

Turn-by-turn routes for hiking, cycling and driving, plus route optimisation, travel-time matrices, reachability areas (isochrones) and GPS-trace map matching.

Routing is available on paid plans only — Starter, Pro and Enterprise. A free-plan key gets 403 on every routing endpoint; see Errors for the exact response and Pricing for the plans.

The endpoints and request/response formats are Valhalla’s own, so existing Valhalla client libraries work. Point them at https://api.mapriot.com and add ?apiKey=<key> to the URL.

Endpoints and billing

Units are charged per request, whatever its size (within the limits). A browser’s CORS preflight (OPTIONS) request is never billed.

Quick start

curl -X POST "https://api.mapriot.com/route?apiKey=<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {"lat": 50.7360, "lon": 15.7399},
      {"lat": 50.7277, "lon": 15.6828}
    ],
    "costing": "pedestrian",
    "costing_options": {"pedestrian": {"use_marked_trails": 1}},
    "units": "kilometers"
  }'

The same request as a GET, for clients that can’t send a body:

GET https://api.mapriot.com/route?json={"locations":[{"lat":50.7360,"lon":15.7399},{"lat":50.7277,"lon":15.6828}],"costing":"pedestrian"}&apiKey=<key>

URL-encode the json value. GET requests are limited by URL length, so use POST for long location lists and GPS traces.

From a browser:

const res = await fetch('https://api.mapriot.com/route?apiKey=<key>', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    locations: [
      { lat: 50.7360, lon: 15.7399 },
      { lat: 50.7277, lon: 15.6828 },
    ],
    costing: 'pedestrian',
    costing_options: { pedestrian: { use_marked_trails: 1 } },
  }),
});
const { trip } = await res.json();

Costing models

costing selects the travel mode. costing_options.<costing> tunes it.

Valhalla’s other costings (motorcycle, motor_scooter, truck, bus, taxi) also work, but we only tune and support the three above.

pedestrian options

bicycle options

auto options

Route

POST /route?apiKey=<key>

Request

Locations

Example: marked hiking trail, Sněžka to Luční hora

{
  "locations": [
    {"lat": 50.7360, "lon": 15.7399},
    {"lat": 50.7277, "lon": 15.6828}
  ],
  "costing": "pedestrian",
  "costing_options": {"pedestrian": {"use_marked_trails": 1, "max_hiking_difficulty": 2}},
  "directions_type": "none"
}

Response (shortened)

{
  "trip": {
    "locations": [
      {"type": "break", "lat": 50.736, "lon": 15.7399, "side_of_street": "left", "original_index": 0},
      {"type": "break", "lat": 50.7277, "lon": 15.6828, "side_of_street": "right", "original_index": 1}
    ],
    "legs": [
      {
        "summary": {"length": 5.561, "time": 5162.089, "min_lat": 50.725403, "min_lon": 15.687319, "max_lat": 50.739757, "max_lon": 15.743366, "has_ferry": false},
        "shape": "yttw_Bceu_]gJoHi@mF]}Aq@kAeAa@y@CuAToE…"
      }
    ],
    "summary": {"length": 5.561, "time": 5162.089, "…": "…"},
    "status": 0,
    "status_message": "Found route between points",
    "units": "kilometers",
    "language": "en-US"
  }
}

Drawing the route on a MapLibre map:

import polyline from '@mapbox/polyline';

const coords = polyline.decode(trip.legs[0].shape, 6).map(([lat, lon]) => [lon, lat]);
map.addSource('route', { type: 'geojson', data: { type: 'LineString', coordinates: coords } });
map.addLayer({ id: 'route', type: 'line', source: 'route', paint: { 'line-color': '#D03D33', 'line-width': 4 } });

Optimized route

Reorders the intermediate locations for the shortest total travel time: a round of summit visits, huts, or delivery stops. The first and last locations stay fixed; for a round trip, repeat the start as the last location.

POST /optimized_route?apiKey=<key>

Takes the same request as /route (alternates excluded). Up to 50 locations for pedestrian and bicycle, 20 for auto.

Example: walking round of four Prague sights

{
  "locations": [
    {"lat": 50.0875, "lon": 14.4213},
    {"lat": 50.0906, "lon": 14.4003},
    {"lat": 50.0810, "lon": 14.4136},
    {"lat": 50.0755, "lon": 14.4378},
    {"lat": 50.0875, "lon": 14.4213}
  ],
  "costing": "pedestrian",
  "directions_type": "none"
}

The response has the same shape as /route. trip.locations comes back in the optimised order, and each location’s original_index points to its position in your request. For the example above, the order is 0, 3, 2, 1, 4.

Matrix (sources to targets)

Travel time and distance from every source to every target, without the route geometry. Useful for “nearest hut” searches and for sorting results by real travel time.

POST /sources_to_targets?apiKey=<key>

sources × targets may be at most 2,500 pairs.

Example

{
  "sources": [{"lat": 50.0875, "lon": 14.4213}],
  "targets": [{"lat": 50.0906, "lon": 14.4003}, {"lat": 50.0755, "lon": 14.4378}],
  "costing": "pedestrian"
}

Response

{
  "sources_to_targets": [
    [
      {"from_index": 0, "to_index": 0, "time": 1678, "distance": 2.031},
      {"from_index": 0, "to_index": 1, "time": 1764, "distance": 2.29}
    ]
  ],
  "sources": [{"lat": 50.087561, "lon": 14.42161}],
  "targets": [{"lat": 50.090539, "lon": 14.400531}, {"lat": 50.075499, "lon": 14.437752}],
  "units": "kilometers"
}

time is in seconds and distance in units. Both are null for a pair with no connection.

Isochrone

Areas reachable from a point within given times or distances, e.g. “everything within a 2-hour walk of this car park”.

POST /isochrone?apiKey=<key>

Example: 30- and 60-minute walk from Sněžka

{
  "locations": [{"lat": 50.7360, "lon": 15.7399}],
  "costing": "pedestrian",
  "contours": [{"time": 30}, {"time": 60}],
  "polygons": true
}

Response: a GeoJSON FeatureCollection you can add straight to a map as a source. Each feature has properties.contour (the value), properties.metric (time or distance) and styling hints (fill, color, fillOpacity). Coordinates are [lon, lat]. Larger contours come first.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {"contour": 60.0, "metric": "time", "color": "#bf4040", "fill": "#bf4040", "fillOpacity": 0.33},
      "geometry": {"type": "Polygon", "coordinates": [[[15.7479, 50.752474], [15.746552, 50.752347], "…"]]}
    }
  ]
}

Map matching

Snap a recorded GPS trace (e.g. a GPX track) onto the path network.

• /trace_route returns the matched path as a route, with the same response as /route, including directions.
• /trace_attributes returns the matched edges with their attributes: surface, SAC scale, trail marking, names, OSM way ids and more.

POST /trace_route?apiKey=<key>
POST /trace_attributes?apiKey=<key>

At most 16,000 trace points and 200 km per request.

Example: which parts of a hike follow marked trails

{
  "shape": [
    {"lat": 50.73597, "lon": 15.74},
    {"lat": 50.7365, "lon": 15.74056},
    {"lat": 50.73599, "lon": 15.74136},
    {"lat": 50.73524, "lon": 15.74216},
    {"lat": 50.73637, "lon": 15.743}
  ],
  "costing": "pedestrian",
  "shape_match": "map_snap",
  "filters": {
    "attributes": ["edge.names", "edge.length", "edge.surface", "edge.sac_scale", "edge.way_id", "edge.hiking_network"],
    "action": "include"
  }
}

Response (/trace_attributes, shortened)

{
  "units": "kilometers",
  "edges": [
    {
      "way_id": 390385744,
      "names": ["Jubilejní cesta"],
      "length": 0.191,
      "surface": "paved",
      "sac_scale": 0,
      "hiking_network": {"international": false, "national": true, "regional": true, "local": false, "marked": true}
    }
  ],
  "shape": "_utw_Bieu_]aJiHi@mF…"
}

edge.hiking_network is a MapRiot extension: it reports which levels of waymarked hiking route (iwn/nwn/rwn/lwn) the edge belongs to, and marked is true if it belongs to any of them.

Locate

The nearest roads and paths to one or more coordinates, as the router would snap to them. Useful to check whether a point is reachable before routing to it.

POST /locate?apiKey=<key>

Response

[
  {
    "input_lat": 50.08,
    "input_lon": 14.42,
    "edges": [
      {"way_id": 192075532, "correlated_lat": 50.080021, "correlated_lon": 14.419847, "side_of_street": "left", "percent_along": 0.55066}
    ],
    "nodes": []
  }
]

Limits

A request over a limit returns 400 with a Valhalla error, e.g. {"error_code": 154, "error": "Path distance exceeds the max distance limit"}. For long hikes, route each day as a separate request. Contact us if you need higher limits.

Request rate

On top of the shape limits above, each API key has a request rate limit. /route, /trace_route and /trace_attributes share one budget; /isochrone, /sources_to_targets and /optimized_route share a much tighter one, because they are far more expensive to serve.

Going over returns 429 with a Retry-After header and a JSON body. See rate limits for the full contract.

Request size

POST bodies are capped at 512 KB (413 above that). A 5,000-point trace sent as raw lat/lon objects is about 180 KB, so only a request that is already over the shape limits can hit this.

Errors

Common Valhalla error_codes:

Full list: Valhalla status codes.