RouteRequest
Possible values: [reviewed_access]
from objectrequired
One end of a route — supply exactly one of hex, plus_code, gps_code, point, or profile_slug.
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.
GA-183-8164A 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.
6CQXJR37+F6Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.
Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.
Reject if the approved revision changed.
Possible values: >= 1
Address-profile handle; access is checked before resolving coordinates/entrances
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]
AfriHex code at resolution 7
AF-GH-7-0GXTJJB0ZZZZZpoint object
Raw coordinate
-0.18675.604Device 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
270to objectrequired
One end of a route — supply exactly one of hex, plus_code, gps_code, point, or profile_slug.
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.
GA-183-8164A 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.
6CQXJR37+F6Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.
Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.
Reject if the approved revision changed.
Possible values: >= 1
Address-profile handle; access is checked before resolving coordinates/entrances
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]
AfriHex code at resolution 7
AF-GH-7-0GXTJJB0ZZZZZpoint object
Raw coordinate
-0.18675.604Device 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
270Travel 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]
drivingdrivingtruck 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.
Possible values: <= 6
4.2Possible values: <= 4
2.5Possible values: <= 35
12Possible values: <= 100
18Possible values: <= 30
8Possible values: <= 12
3falseControls landmark narration in step instructions.
street— standard instructions onlylandmark— rewritten to reference nearby landmarksboth— includes both forms
Possible values: [street, landmark, both]
streetlandmarkBCP-47 language tag for verbal instructions (Valhalla supports 30+ languages).
en-USen-USPolygons 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
[[[-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).
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.
falsetrueLight 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.
falsetrueReturn 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%).
falsetruewaypoints 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
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.
GA-183-8164A 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.
6CQXJR37+F6Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.
Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.
Reject if the approved revision changed.
Possible values: >= 1
Address-profile handle; access is checked before resolving coordinates/entrances
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]
AfriHex code at resolution 7
AF-GH-7-0GXTJJB0ZZZZZpoint object
Raw coordinate
-0.18675.604Device 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
270Departure 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.
2026-11-10T07:30:00ZArrival 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.
2026-11-10T09:00:00Z{
"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"
}