💻 Purpose of the API

The Routeplanner Routing API calculates routes between two or more locations for a variety of transport modes, including car, truck, pedestrian, bicycle, scooter, and electric vehicle. It returns detailed route information including travel time, distance, turn-by-turn instructions, the route geometry as an encoded polyline, and notices about road restrictions or conditions.

Use it to:

• Calculate the fastest or shortest route between an origin and destination
• Plan multi-stop routes with intermediate waypoints
• Generate turn-by-turn navigation instructions
• Calculate truck routes respecting physical and load restrictions
• Avoid specific road features, areas, or environmental zones
• Obtain the route polyline for display on a map (e.g. via the Mapview API)

🤔 How to use?

Base URL

https://api.company.info/routeplanner/routing

Authentication

All requests require an API key passed as a request header:

X-API-Key: YOUR_API_KEY

GET /routes

Calculate a route between an origin and a destination, with optional intermediate stops.

Required parameters

Transport modes

Waypoint format

Origin, destination, and via waypoints all use the same format:

{lat},{lng}[;placeOption=value][!waypointOption=value]

Place options (separated by ;) control how the router interprets the location:

Waypoint options (separated by !) control stop behaviour:

Examples:

# Simple coordinate
52.3676,4.9041

# Avoid ending up on wrong side of a divided road
52.531052,13.384872;sideOfStreetHint=52.530941,13.384939;matchSideOfStreet=always

# Moving vehicle with uncertain GPS position
51.611571,11.351608;course=170;radius=20;minCourseDistance=500

# Via stop with a 10-minute dwell time
51.611571,11.351608!stopDuration=600

# Pass-through waypoint (no stop, no section split)
51.611571,11.351608!passThrough=true

Multi-stop routes

To add intermediate stops, use one or more via parameters. The route will visit each stop in the order specified.

/routes?transportMode=car
       &origin=52.3676,4.9041
       &via=52.0907,5.1214
       &via=51.9244,4.4777
       &destination=51.5048,3.8598

Routing mode

ℹ️

bicycle, bus, pedestrian, scooter, and taxi modes only support fast.

Departure time

Use departureTime to account for time-dependent traffic and schedules.

Avoiding road features and areas

Use avoid to exclude certain road types or geographic areas. This is a soft preference — if no alternative exists, the router may still use the avoided feature and will note this in the response.

Avoid road features:

avoid[features]=tollRoad,tunnel,ferry

Available features: seasonalClosure, tollRoad, controlledAccessHighway, ferry, carShuttleTrain, tunnel, dirtRoad, difficultTurns

Avoid a geographic bounding box:

avoid[areas]=bbox:4.728,52.278,5.079,52.431

Avoid multiple areas (use | as separator):

avoid[areas]=bbox:4.728,52.278,5.079,52.431|bbox:4.832,52.352,4.901,52.401

Avoid environmental or congestion zones:

avoid[zoneCategories]=environmental
avoid[zoneCategories]=congestionPricing,vignette

⚠️

If the origin or destination is located within an avoided area, the router will still produce a route but will try to minimise how much of the avoided area is used.

What to include in the response (return)

By default the response includes basic route information. Use return to opt into additional data:

Example requesting polyline + instructions:

return=polyline,actions,instructions

ℹ️

actions requires polyline. instructions requires actions. turnByTurnActions requires polyline.

Truck routing

When transportMode=truck, use the truck parameter group to specify vehicle characteristics. The router will automatically avoid roads with restrictions that the vehicle cannot comply with.

Hazardous goods values: explosive, gas, flammable, combustible, organic, poison, radioactive, corrosive, poisonousInhalation, harmfulToWater, other

Example:

transportMode=truck
&truck[grossWeight]=20000
&truck[height]=400
&truck[length]=1600
&truck[shippedHazardousGoods]=flammable,gas

Alternative routes

Request up to 6 alternative routes alongside the primary route:

alternatives=3

Other parameters

Example request

Calculate a car route from Amsterdam to Rotterdam with polyline and instructions:

curl --request GET \
     --url 'https://api.company.info/routeplanner/routing/routes?transportMode=car&origin=52.3676,4.9041&destination=51.9244,4.4777&routingMode=fast&return=polyline,actions,instructions&lang=en-US' \
     --header 'X-API-Key: YOUR_API_KEY'

Example response

{
  "routes": [
    {
      "id": "1793a897-0843-4957-ab63-c61e0f13aff2",
      "sections": [
        {
          "id": "c3e300ab-a880-4fab-9bb2-702355b2bf6b",
          "type": "vehicle",
          "departure": {
            "time": "2024-06-01T09:00:00+02:00",
            "place": {
              "type": "place",
              "location": { "lat": 52.3676, "lng": 4.9041 }
            }
          },
          "arrival": {
            "time": "2024-06-01T09:48:00+02:00",
            "place": {
              "type": "place",
              "location": { "lat": 51.9244, "lng": 4.4777 }
            }
          },
          "summary": {
            "duration": 2880,
            "length": 76000
          },
          "polyline": "BG2znmkDi89wZ...",
          "actions": [
            {
              "action": "depart",
              "duration": 120,
              "instruction": "Head south on Damrak. Go for 500 m.",
              "offset": 0
            },
            {
              "action": "arrive",
              "duration": 0,
              "instruction": "Arrive at your destination.",
              "offset": 892
            }
          ],
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

Understanding the response

Routes and sections A route consists of one or more sections. With a direct trip (no via stops), there is typically one section. Each via stop with stopDuration > 0 creates a new section. Pass-through waypoints (passThrough=true) do not split the route into sections.

summary Contains duration (seconds) and length (meters) for the section.

polyline The route geometry in Flexible Polyline encoding. Pass this directly to the Mapview API to render the route as a map image.

actions A list of maneuvers in sequence. Each action has a type (e.g. depart, arrive, turn, roundaboutExit), a duration, an instruction string, and an offset indicating its position in the polyline.

Notices If the route violates a restriction (e.g. a truck route passes a weight-restricted bridge), a notice is included in the response with a severity of critical or warning. Always check for notices in truck routing use cases.

GET /routes/{routeHandle} ⚠️ Alpha

Retrieve and decode a previously calculated route using a route handle.

A route handle is returned when routeHandle is included in the return parameter of a /routes request. It encodes the calculated route so it can be retrieved later without recalculating.

⚠️

This endpoint is in Alpha state and subject to breaking changes. The handle is only valid as long as the service uses the same map data version as when the route was originally calculated.

Not supported on this endpoint: origin, destination, via, alternatives, routingMode — these are encoded in the handle from the original calculation.

⚠️ Possible errors

ℹ️

Route calculation errors (e.g. origin could not be matched) are not returned as HTTP errors — they appear as notices in the 200 response with severity: critical.

🛠️ Try it yourself!

Test the API directly in our API reference.

🔤 Glossary

Section A continuous segment of a route. A route with no via stops has one section. Each stopping via waypoint adds a new section.

Polyline The route geometry encoded as a Flexible Polyline string. Can be passed to the Mapview API to render the route as a static map image.

Route handle An encoded string representing a previously calculated route. Allows the route to be retrieved later without recalculation, as long as the underlying map data has not changed.

Notice A message in the route response indicating that a restriction or condition applies. A critical notice means the route violates a hard restriction (e.g. a truck weight limit). A warning means a softer condition was encountered.

Pass-through waypoint A via waypoint that the route passes through without stopping, without splitting into a new section, and without requiring a direction change.

ADR tunnel category A European classification (B, C, D, E) specifying which hazardous goods are permitted in which tunnels. Required for truck routing with hazardous cargo.

Flexible Polyline A compact encoding format for sequences of geographic coordinates. See the Mapview API documentation for details on how to use the polyline to render a route image.

❓ FAQ

How do I get turn-by-turn instructions? Add return=polyline,actions,instructions to your request. Instructions require actions, and actions require polyline — all three must be requested together.

Can I calculate a route with multiple stops? Yes, use one or more via parameters between origin and destination. The route will visit each via stop in the order specified.

What is the difference between via with stopDuration and passThrough? A via with stopDuration creates a real stop — the route pauses there for the specified time and the trip is split into separate sections. A passThrough via simply constrains the route to pass through that point without stopping or creating a new section.

Why does my truck route include a restricted road? If no alternative exists, the router will include the restricted road and include a notice with severity: critical in the response. Always check for notices in truck routing applications.

How do I render the route on a map? Request return=polyline and pass the returned polyline string to the Routeplanner Mapview API (GET /route?polyline=...).

What happens if the origin cannot be matched to a road? The route calculation fails but the API still returns HTTP 200. The failure is communicated as a notice with code: couldNotMatchOrigin and severity: critical in the response. Check for notices before consuming route data.

Can I save a route and retrieve it later? Yes, include routeHandle in the return parameter. Store the returned handle and use GET /routes/{routeHandle} to retrieve the route later. Note that handles are invalidated when the underlying map data is updated.

Which transport modes support alternative routes? All modes support alternatives, but note that bicycle, bus, pedestrian, scooter, and taxi only support fast routing mode, which may limit the variety of alternatives returned.