---
title: "Valhalla-compatible route endpoint (see module docs)."
method: POST
path: "/route"
tags: ["routing"]
---

# Valhalla-compatible route endpoint (see module docs).

`POST /route`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/route`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

## Request body

- object

## Response `200`

Valhalla route response, with an `adr` echo when an ADR profile was applied, a `rationale` block when requested (`avoided[]` entries carry basis: "route_divergence"; see the module docs for the method's honesty limits), and, when `landmarks` was requested, a `landmark_instruction` on each manoeuvre where a recognisable place cleared the salience bar plus a `landmarks` summary block reporting how many were annotated, and, when `traffic` was requested, a `traffic` object on each leg plus a top-level `traffic` summary carrying the route aggregate, the coverage snapshot's freshness and the method's caveats, and, when `scenic` was requested, a top-level `scenic` block with the chosen route, its stated reason, the measured features behind it, the extra minutes it costs and every candidate that was compared with why it lost, and, on a truck route on a deployment with a baked restriction grid, a top-level `restriction_coverage` receipt naming how many grid cells the route crosses, how they are graded for restriction-tagging density, how many fall outside the grid's own extent and what absence of a recorded restriction does not prove, and, when the route crosses a UK clean-air or low-emission zone (or `avoid_zones` was set), a top-level `zones` block naming each crossed zone, whether the declared vehicle is charged, banned or compliant there, the published daily charge with its source URL and checked date, and an `estimated_charges` total kept separate from every routing cost, and, when the gateway's road walk succeeded, on each manoeuvre `speed_limit` (in the trip's `units`) plus `country` (ISO 3166-1 alpha-2), `subdivision` (ISO 3166-2), `ref` (route numbers only, `; ` separated), `road_class`, `speed_limit_unit` (`mph` or `km/h`, the road's unit, never the request's), `speed_limit_sign` (`vienna` or `mutcd`) and `speed_limit_posted` (`{"type":"known","value":30,"unit":"mph"}`, `unlimited` or `unknown`, with `"national": true` for a GB national speed limit where the map records it) and `driving_side` (`left` or `right`, from the road's country), and, on a pedestrian wheelchair route where the deployment has a surface graph (or the request set `surface_quality`), a top-level `surface_quality` block saying whether the route was computed on the surface-quality graph (`applied`, with the region, the exact rule, the data timestamp and a caveat) or why not (`reason`: outside_coverage, opted_out, surface_graph_unavailable or not_configured), and, on a wheelchair route, a grade cap or `grade_report: true`, a top-level `grade` block with the maximum grade and total ascent and descent sampled every 10 m from the elevation model, the `use_hills` preference sent and whether a requested cap was enforced

- object

## Other responses

- `400`: Invalid request, conflicting costing_options, or more than 500 locations
- `401`: Missing or invalid API key
- `422`: More waypoints than the routing engine takes in one call, AND the route cannot be split faithfully: a run of more than 20 consecutive `through`/`via`/`break_through` waypoints, a time-dependent route (`date_time.type` 0, 1 or 2), or a request for `alternates`. `detail` says which and what to change
- `429`: Quota or rate limit exceeded
- `502`: Upstream routing engine failed

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)