Routing

Routing finds a driving, walking, or cycling route through 2 to 20 stops, visited in the order you give. Each response has the total distance and travel time, the same for each leg between stops, and a line you can draw on a map.

Routing uses the routing scope and costs one request, from the shared free allowance first. A route with no path between the stops isn't billed.

Get a route

POST /v1/route takes a JSON body with the waypoints and a travel mode.

curl "https://api.mapricot.com/v1/route" \
  -H "Authorization: Bearer $MAPRICOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "waypoints": [
      { "lat": 43.7396, "lon": 7.4275 },
      { "lat": 43.734, "lon": 7.4222 }
    ],
    "mode": "walk"
  }'

{  "routes": [    {      "distanceMeters": 1044,      "durationSeconds": 739,      "polyline": "{{slrAmyidMzImEvQwGlE}ATJXDTC@Ab@Qb@[`Au@~@k@|@a@nAi@hAa@d@Kp@QpAUpAIhF[~AMlAFlA`@j@RrAz@nAbAlA`AXr@lC|CfAx@jC~DlAhCvCzG|C~O\\vEZdELbEJzBLpCd@pJFnAt@xKRtDDd@ZvCv@pGb@~BNx@rHlZv@pDj@bCTv@fApDThAXxAp@zEDzBPtHv@pMt@hNHx@RxBRrBdFfb@pG~h@n@|JtBhb@Dh@\\tD`@dC^j@^i@OmDCcAy@LHv@Fz@nBU|B_@d@a@~AsA]uBp@mBtC|BtBtA`H`EnB|@pAl@xGtBfDz@bCd@rC^hFb@vH@nHSdCUxCy@fCgAtBwAtCiCpDsFvCmEbBkAvRaDlHkArMwBd@Cb@Af@F`@LxCjAdBh@hAThALv@DB?",      "legs": [        {          "distanceMeters": 1044,          "durationSeconds": 739        }      ]    }  ],  "attribution": [    {      "source": "openstreetmap",      "text": "© OpenStreetMap contributors",      "url": "https://www.openstreetmap.org/copyright"    }  ]}

Distances are whole meters and durations whole seconds. There is one entry in legs for each pair of consecutive waypoints. When no path connects the waypoints, the response is {"routes": []} and isn't billed.

Draw the route

polyline is an encoded polyline with six decimal places of precision. Decode it with precision 6; Google's routes use 5, so decoders default to 5. The polyline decoder shows a polyline on a map. With MapLibre and the @mapbox/polyline package, loaded from jsDelivr in a module script:

import polyline from "https://cdn.jsdelivr.net/npm/@mapbox/polyline@1.2.1/+esm";

const coordinates = polyline
  .decode(route.polyline, 6)
  .map(([lat, lon]) => [lon, lat]);

map.addSource("route", {
  type: "geojson",
  data: { type: "Feature", geometry: { type: "LineString", coordinates } },
});
map.addLayer({
  id: "route",
  type: "line",
  source: "route",
  paint: { "line-color": "#fd7e14", "line-width": 5 },
});

See map tiles to set up the map itself, and drawing a route on a MapLibre map for a whole map with stops to drag.

What routing doesn't include

Routes don't include live traffic, public transit, turn-by-turn instructions, toll costs, or route matrices, and stops aren't reordered for you. Each mode has a maximum route distance; a request over it returns 400 and isn't billed.

Data

Routing runs on Valhalla with a road network built from OpenStreetMap for the whole planet. OpenStreetMap data is licensed ODbL. If your app shows a route, show the credit in the response's attribution.

See the API reference for errors and limits.