Skip to main content

RouteRequest

destination_policystring

Possible values: [reviewed_access]

from objectrequired

One end of a route — supply exactly one of hex, plus_code, gps_code, point, or profile_slug.

gps_codestring

A GhanaPostGPS digital address, with or without dashes. It is looked up in the GhanaPostGPS registry and the route uses the centre of its cell. An unknown or malformed code returns 400 VALIDATION_ERROR.

Example: GA-183-8164
plus_codestring

A full Plus Code (Open Location Code), case-insensitive. The route uses the centre of its cell (about 14 m across for a 10-digit code). Short codes are rejected as ambiguous; expand them first with GET /v2/pluscode/{code}?ref=lat,lng.

Example: 6CQXJR37+F6
location_idstring

Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.

entrance_idstring

Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.

entrance_revisioninteger

Reject if the approved revision changed.

Possible values: >= 1

profile_slugstring

Address-profile handle; access is checked before resolving coordinates/entrances

entrance_typestring

Optional explicit entrance for profile_slug. Otherwise defaults to truck/main gate selection, then profile point.

Possible values: [main, truck_gate, loading_dock, visitor, staff, pedestrian, compound]

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 exactly one of hex, plus_code, gps_code, point, or profile_slug.

gps_codestring

A GhanaPostGPS digital address, with or without dashes. It is looked up in the GhanaPostGPS registry and the route uses the centre of its cell. An unknown or malformed code returns 400 VALIDATION_ERROR.

Example: GA-183-8164
plus_codestring

A full Plus Code (Open Location Code), case-insensitive. The route uses the centre of its cell (about 14 m across for a 10-digit code). Short codes are rejected as ambiguous; expand them first with GET /v2/pluscode/{code}?ref=lat,lng.

Example: 6CQXJR37+F6
location_idstring

Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.

entrance_idstring

Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.

entrance_revisioninteger

Reject if the approved revision changed.

Possible values: >= 1

profile_slugstring

Address-profile handle; access is checked before resolving coordinates/entrances

entrance_typestring

Optional explicit entrance for profile_slug. Otherwise defaults to truck/main gate selection, then profile point.

Possible values: [main, truck_gate, loading_dock, visitor, staff, pedestrian, compound]

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
    waypoints object[]

    Intermediate stops between from and to, visited in order. Each takes the same forms as from/to (hex, point or profile; no entrance fields). The route splits into one leg per stop, returned in legs. Multi-stop routes return no alternatives. Up to 18 stops (20 locations in total). For the best visiting order across stops, use POST /v2/route/optimized.

    Possible values: <= 18

  • Array [
  • gps_codestring

    A GhanaPostGPS digital address, with or without dashes. It is looked up in the GhanaPostGPS registry and the route uses the centre of its cell. An unknown or malformed code returns 400 VALIDATION_ERROR.

    Example: GA-183-8164
    plus_codestring

    A full Plus Code (Open Location Code), case-insensitive. The route uses the centre of its cell (about 14 m across for a 10-digit code). Short codes are rejected as ambiguous; expand them first with GET /v2/pluscode/{code}?ref=lat,lng.

    Example: 6CQXJR37+F6
    location_idstring

    Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.

    entrance_idstring

    Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.

    entrance_revisioninteger

    Reject if the approved revision changed.

    Possible values: >= 1

    profile_slugstring

    Address-profile handle; access is checked before resolving coordinates/entrances

    entrance_typestring

    Optional explicit entrance for profile_slug. Otherwise defaults to truck/main gate selection, then profile point.

    Possible values: [main, truck_gate, loading_dock, visitor, staff, pedestrian, compound]

    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
  • ]
  • depart_atstring<date-time>

    Departure time (RFC 3339). The traffic-adjusted ETA (eta_s, and each leg's eta_s) is computed for this time of day instead of now; the response carries depart_at and arrive_at. Does not change the path. Mutually exclusive with arrive_by.

    Example: 2026-11-10T07:30:00Z
    arrive_bystring<date-time>

    Arrival deadline (RFC 3339). The API works back to the departure time, using the traffic model for the time of day the trip would be driven, and returns it as depart_at (arrive_at equals this value). A warning is added when that departure has already passed. Mutually exclusive with depart_at.

    Example: 2026-11-10T09:00:00Z
    RouteRequest
    {
    "destination_policy": "reviewed_access",
    "from": {
    "gps_code": "GA-183-8164",
    "plus_code": "6CQXJR37+F6",
    "location_id": "string",
    "entrance_id": "string",
    "entrance_revision": 0,
    "profile_slug": "string",
    "entrance_type": "main",
    "hex": "AF-GH-7-0GXTJJB0ZZZZZ",
    "point": {
    "lng": -0.1867,
    "lat": 5.604
    },
    "heading": 270
    },
    "to": {
    "gps_code": "GA-183-8164",
    "plus_code": "6CQXJR37+F6",
    "location_id": "string",
    "entrance_id": "string",
    "entrance_revision": 0,
    "profile_slug": "string",
    "entrance_type": "main",
    "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,
    "waypoints": [
    {
    "gps_code": "GA-183-8164",
    "plus_code": "6CQXJR37+F6",
    "location_id": "string",
    "entrance_id": "string",
    "entrance_revision": 0,
    "profile_slug": "string",
    "entrance_type": "main",
    "hex": "AF-GH-7-0GXTJJB0ZZZZZ",
    "point": {
    "lng": -0.1867,
    "lat": 5.604
    },
    "heading": 270
    }
    ],
    "depart_at": "2026-11-10T07:30:00Z",
    "arrive_by": "2026-11-10T09:00:00Z"
    }