Route between coordinates, optionally avoiding your own zones
get_routePlan car, bike, foot, or truck routes between two or more points, with distance, duration, and turn-by-turn steps.
Instructions
A driving, cycling, walking or truck route from the first location to the last, via any in between, with distance, duration and turn-by-turn steps.
COST: a route is 10 LOOKUPS on the standard plans, not one (a custom plan may charge less; X-Lookups-Remaining is always the truth). Everything it returns is included in that, so do not call it in a loop to compare options without saying so.
Durations are FREE-FLOW: the road network at its own speed limits, with NO live or historical traffic. Never present one as an arrival time in traffic — for that, say a traffic-aware service (Google, Mapbox) is needed.
The route line is NOT returned unless routeGeometry is set, because an encoded polyline is thousands of characters that no one reads. Ask for it only when something will draw it.
Locations are SNAPPED to the nearest routable road, and locations[] in the response says how far each one moved. A large snapDistanceMeters means the answer starts somewhere else than asked — worth repeating to the user.
avoidSets and exposureSets name BOUNDARY SETS on the account (list_boundary_sets), not ad-hoc shapes. avoid routes around every zone in those sets; exposure leaves the route alone and reports how far it ran inside each zone. A zone containing one of the locations cannot be avoided for that route: it is skipped and reported in avoid.skipped.
TRUCKS (Pro only): a truck over 9 t, or with no weightTonnes, is capped at 80 km/h, as South African law caps goods vehicles; a lighter truck keeps car speeds. The vehicle’s height, width, length, weight, axle load and hazmat are checked against road limits where OpenStreetMap records them, which is not everywhere — a good start, not a legal clearance.
Limits by plan: 2 locations and 1 alternative on the free plans, up to 25 and 2 on Pro; alternatives need exactly 2 locations. Over a cap the answer is 403, and nothing is billed. A location with no road near it, or two places with no road between them, is 422 — and that one IS billed, because the route was attempted.
Not for: distance matrices, isochrones or live traffic (none exist yet), and not for which-area-is-this questions — that is lookup_location, at one lookup.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Travel mode. Defaults to car. "truck" is Pro only; see TRUCKS above. | |
| steps | No | Turn-by-turn steps per leg. Defaults to true here; set false for distance and time only. | |
| vehicle | No | Truck dimensions and load. Only with mode "truck"; rejected otherwise. Give weightTonnes: without it the truck is treated as heavy (over 9 t) and capped at 80 km/h. | |
| geometry | No | DEPRECATED: use routeGeometry, which takes the same values. Removed in 1.0. | |
| language | No | Language for the step instructions, e.g. "en-GB", "de-DE", "fr-FR". Defaults to en-US. | |
| avoidSets | No | Names of boundary sets on this account to route AROUND. Every zone in them is excluded. | |
| locations | Yes | Origin, any stops in order, then destination. 2 on the free plans, up to 25 on Pro. | |
| alternatives | No | Also return up to this many other routes. Exactly 2 locations only. Plan-capped. | |
| exposureSets | No | Names of boundary sets to MEASURE against: the route is unchanged, and the answer says how many metres of it ran inside each zone. | |
| routeGeometry | No | The route line. Defaults to none. Ask for polyline6 or geojson only when something will draw it: it is long, and an assistant cannot read it usefully. |