Skip to main content

RouteRequest

from objectrequired

One end of a route — supply either hex or point, not both.

hexstring

AfriHex code at resolution 7

Example: AF-GH-7-0GXTJJB0ZZZZZ
point object

Raw coordinate

lngnumber<double>
Example: -0.1867
latnumber<double>
Example: 5.604
headinginteger

Device compass bearing in degrees (0 = north). On dual-carriageway roads it disambiguates which carriageway the endpoint snaps to, so routes don't begin with a phantom U-turn. Omit when unknown.

Possible values: >= 0 and <= 359

Example: 270
to objectrequired

One end of a route — supply either hex or point, not both.

hexstring

AfriHex code at resolution 7

Example: AF-GH-7-0GXTJJB0ZZZZZ
point object

Raw coordinate

lngnumber<double>
Example: -0.1867
latnumber<double>
Example: 5.604
headinginteger

Device compass bearing in degrees (0 = north). On dual-carriageway roads it disambiguates which carriageway the endpoint snaps to, so routes don't begin with a phantom U-turn. Omit when unknown.

Possible values: >= 0 and <= 359

Example: 270
modestring

Travel mode. motor_scooter and okada are aliases for motorbike routing; omitting mode (or passing an empty string) also defaults to driving.

truck uses heavy-goods costing: it penalises tracks and living streets far harder than driving, and honours the OSM hgv, maxheight, maxweight, maxwidth and maxlength restrictions in the road graph. Pair it with truck below to route around restrictions your vehicle actually breaches.

Possible values: [driving, foot, bicycle, motor_scooter, okada, truck]

Default value: driving
Example: driving
truck object

Vehicle dimensions, only valid with mode: "truck" — sending them with any other mode is rejected rather than ignored, since a caller who supplies dimensions expects restriction-aware routing.

Every field is optional. Unset values fall back to Valhalla's own truck defaults rather than a guess: an overstated height silently rules out roads the vehicle could legally use. Units are metres and metric tonnes, matching the OSM tags they are compared against.

height_mnumber<double>

Possible values: <= 6

Example: 4.2
width_mnumber<double>

Possible values: <= 4

Example: 2.5
length_mnumber<double>

Possible values: <= 35

Example: 12
weight_tnumber<double>

Possible values: <= 100

Example: 18
axle_load_tnumber<double>

Possible values: <= 30

Example: 8
axle_countinteger

Possible values: <= 12

Example: 3
hazmatboolean
Example: false
narrationstring

Controls landmark narration in step instructions.

  • street — standard instructions only
  • landmark — rewritten to reference nearby landmarks
  • both — includes both forms

Possible values: [street, landmark, both]

Default value: street
Example: landmark
languagestring

BCP-47 language tag for verbal instructions (Valhalla supports 30+ languages).

Default value: en-US
Example: en-US
avoid_polygonsnumber[][][]

Polygons to avoid when routing. Each element is a closed exterior ring of [lng, lat] pairs. Useful for cash-in-transit safety (avoid known high-risk corridors), flood-closure rerouting, or custom no-go zones.

Possible values: >= 2, <= 2

Example: [[[-0.195,5.61],[-0.185,5.61],[-0.185,5.6],[-0.195,5.6],[-0.195,5.61]]]
avoid_locations object[]

Individual road points to avoid (snapped to nearest road segment).

  • Array [
    • latnumber<double>
    lngnumber<double>
  • ]
    • avoid_flood_zonesboolean

    Route around curated flood-prone zones — the recurring trouble spots along Accra's Odaw drainage basin (Kaneshie First Light, Kwame Nkrumah Circle/Odawna, Alajo, Agbogbloshie) and the Weija dam spillway. Turn this on during heavy rain to keep riders out of flooded interchanges. The zones are merged with any avoid_polygons you supply.

    Default value: false
    Example: true
    avoid_incidentsboolean

    Light avoidance of recent, corroborated crowdsourced hazard reports (see POST /v2/route/incidents). Only flooding and road_blocked reports with 2 or more corroborating reports are ever avoided — accident/police reports and single uncorroborated reports are always warn-only, regardless of this flag. Route warnings mentioning nearby incidents are returned either way; this flag only controls whether the route is adjusted, not whether you're told about them.

    Default value: false
    Example: true
    liteboolean

    Return a minimal payload — route polyline, distance, duration, and traffic-adjusted ETA only. No turn-by-turn steps, landmark narration, or alternative routes. Use for tracking screens and low-bandwidth clients where data cost matters more than turn instructions (typically cuts the response size by 80–90%).

    Default value: false
    Example: true
    RouteRequest
    {
      "from": {
        "hex": "AF-GH-7-0GXTJJB0ZZZZZ",
        "point": {
          "lng": -0.1867,
          "lat": 5.604
        },
        "heading": 270
      },
      "to": {
        "hex": "AF-GH-7-0GXTJJB0ZZZZZ",
        "point": {
          "lng": -0.1867,
          "lat": 5.604
        },
        "heading": 270
      },
      "mode": "driving",
      "truck": {
        "height_m": 4.2,
        "width_m": 2.5,
        "length_m": 12,
        "weight_t": 18,
        "axle_load_t": 8,
        "axle_count": 3,
        "hazmat": false
      },
      "narration": "landmark",
      "language": "en-US",
      "avoid_polygons": [
        [
          [
            -0.195,
            5.61
          ],
          [
            -0.185,
            5.61
          ],
          [
            -0.185,
            5.6
          ],
          [
            -0.195,
            5.6
          ],
          [
            -0.195,
            5.61
          ]
        ]
      ],
      "avoid_locations": [
        {
          "lat": 5.603,
          "lng": -0.187
        }
      ],
      "avoid_flood_zones": true,
      "avoid_incidents": true,
      "lite": true
    }