RouteResponse

warningsstring[]

Advisory notes about the computed route. Currently emitted when avoid_flood_zones is set but an endpoint lies inside a flood-prone zone — that zone cannot be excluded (the route must enter it), so it is skipped and named here instead.

Example: ["a route endpoint is inside the flood-prone zone \"Kaneshie First Light / Graphic Road\" — that zone cannot be avoided"]

distance_mnumber<double>

Total route distance in metres.

Example: 4250

duration_snumber<double>

Raw Valhalla duration in seconds (no traffic adjustment).

Example: 780

eta_snumber<double>

Traffic-adjusted ETA in seconds using Ghana time-of-day multipliers.

Example: 936

traffic_notestring

Human-readable label for the traffic condition applied.

Example: morning rush

has_tollboolean

True if the route passes through any toll roads.

Example: false

has_ferryboolean

True if the route includes a ferry crossing (e.g. Volta Lake).

Example: false

has_highwayboolean

True if the route uses any motorway/highway segments.

Example: true

coordinatesnumber[][]

Route polyline as [lng, lat] pairs.

Possible values: >= 2, <= 2

Example: [[-0.1867,5.604],[-0.185,5.605]]

steps object[]

Array [

instructionstring

Standard turn instruction.

Example: Turn right onto Ring Road Central.

verbal_alertstring

Early warning voice prompt (~500 m before the maneuver), suitable for TTS.

Example: In 500 metres, turn right onto Ring Road Central.

verbal_instructionstring

Pre-built voice prompt suitable for TTS, delivered before the maneuver.

Example: In 300 metres, turn right onto Ring Road Central.

verbal_poststring

Confirmation voice prompt after the maneuver, suitable for TTS.

Example: Continue for 2 kilometres.

instruction_landmarkstring

Landmark-enriched instruction (present when narration=landmark or both).

Example: Turn right at Accra Mall onto Ring Road Central.

landmark_confidencenumber<double>

How well-documented the referenced landmark is — not how sure the narration match itself is. Only present alongside instruction_landmark. Don't present instruction_landmark as certain when this is low.

Possible values: >= 0 and <= 1

Example: 0.78

alternate_landmarksstring[]

Runner-up landmark names close enough to the chosen one to plausibly be confused with it. Empty/absent when there was no real ambiguity. Report a wrong match with POST /v2/landmarks/{slug}/report.

Example: ["TotalEnergies Station"]

namestring

Street or road name for this step.

Example: Ring Road Central

near_landmarkstring

Name of the nearest landmark to the maneuver point (within 150m).

Example: Accra Mall

distance_mnumber<double>

Distance of this step in metres.

Example: 320.5

duration_snumber<double>

Estimated duration of this step in seconds.

Example: 45.2

traffic_factornumber<double>

Effective traffic multiplier applied to this step's duration (learned from real trips where published, else the static Accra time-of-day table) for the active time bucket.

Example: 1.7

traffic_severitystring

Congestion label for UI route-line tinting.

Possible values: [free_flow, light, moderate, heavy, severe]

Example: heavy

traffic_colorstring

Hex color the client should tint this step's polyline.

Example: #ef6c00

coordinatesnumber[][]

Polyline of this step as [lng, lat] pairs.

Possible values: >= 2, <= 2

Example: [[-0.1867,5.604],[-0.185,5.605]]

surfacestring

Dominant road surface of this step ("paved" or "unpaved"); omitted when unknown.

Possible values: [paved, unpaved]

Example: paved

surface_colorstring

Hex color the client should tint this step's polyline based on surface.

Example: #8d6e63

bearing_beforeinteger

Heading (degrees from true north) arriving into the maneuver.

Example: 35

bearing_afterinteger

Heading (degrees from true north) leaving the maneuver.

Example: 125

turn_angleinteger

Signed heading change at the maneuver, in degrees within (-180, 180]; positive = right, negative = left.

Example: -90

turn_classstring

Coarse sharpness of the maneuver.

Possible values: [straight, slight, turn, sharp, uturn]

Example: turn

lanes object[]

Lane-level guidance for this maneuver ("keep left of 3 lanes"). Only present when the road graph carries turn:lanes data at the junction; most Ghana roads don't yet, so it is usually omitted.

Array [

indicationsstring[]

Movements this lane permits ("left", "straight", "right", "slight right", ...).

Example: ["left","straight"]

activeboolean

True for the recommended lane to follow for this maneuver.

Example: true

validboolean

True for lanes usable at the start of the maneuver; may require a later lane change.

Example: false

]

]

landmarks_passed object[]

Significant landmarks along the route (present when narration=landmark or both).

Array [

slugstring

Example: accra-mall

namestring

Example: Accra Mall

sidestring

Possible values: [left, right]

Example: right

at_stepinteger

Step index where this landmark is passed.

Example: 2

centroid object

Landmark centroid for the POI detail card.

latnumber<double>

lngnumber<double>

photo_urlstring

Wikimedia Commons photo thumbnail when resolved.

phonestring

Contact phone number from OSM, when tagged.

websitestring

Official website from OSM, when tagged.

opening_hoursstring

Opening-hours string from OSM, when tagged.

]

alternatives object[]

Up to 2 alternative routes (no step details).

Array [

distance_mnumber<double>

Example: 4800

duration_snumber<double>

Example: 900

eta_snumber<double>

Example: 1080

coordinatesnumber[][]

Possible values: >= 2, <= 2

recommendedboolean

True when this alternative is the recommended (safer) pick.

recommend_reasonstring

Why it is recommended, e.g. "avoids a flood-prone area".

rain_notestring

Heavy-rain note for this alternative.

rain_eta_penalty_snumber<double>

ETA seconds added for heavy rain on this alternative.

flood_crossingsinteger

Number of flood-zone crossings on this alternative.

incident_countinteger

Number of active, crowdsourced hazard reports near this alternative.

has_unpavedboolean

True when the alternative includes unpaved segments.

unpaved_distance_mnumber<double>

Total unpaved distance in metres (0 when all paved).

]

recommendedboolean

True when the primary route is the recommended (safer) pick — a non-fastest option wins only when it avoids flood-prone areas or heavy rain. Absent when the fastest route is also the cleanest.

recommend_reasonstring

Plain-language reason, e.g. "avoids 2 flood-prone areas".

rain_notestring

Heavy-rain advisory for the route.

rain_eta_penalty_snumber<double>

ETA seconds added for heavy rain on the route.

flood_crossingsinteger

Number of flood-zone crossings on the route.

incident_countinteger

Number of active, crowdsourced hazard reports (accident, flooding, road_blocked, police) near the route — always populated regardless of avoid_incidents, which only controls whether the route is adjusted, not whether nearby reports are surfaced. Details are in warnings.

flood_avoidance_failedboolean

True when avoid_flood_zones was requested but no route exists that avoids the zones, so the route was computed WITHOUT them and may pass through flooding. Common on cross-town Accra trips, where the Odaw basin zones sit across most arteries. The route is still returned (a warning beats no directions) — the matching text is in warnings, but prefer this field over parsing warning strings.

Exception: if an official GMet flood warning is in effect over the route, this degraded route is NOT returned. The request is refused with 409 FLOOD_ALERT_ACTIVE instead. A route that successfully avoids the zones is unaffected and is still served during an alert.

has_unpavedboolean

True when the route includes unpaved segments. Absent when the route is fully paved OR when surface enrichment did not run (best-effort) — treat absent as "unknown".

unpaved_distance_mnumber<double>

Total unpaved distance in metres. Absent when 0.

RouteResponse

{
  "warnings": [
    "a route endpoint is inside the flood-prone zone \"Kaneshie First Light / Graphic Road\" — that zone cannot be avoided"
  ],
  "distance_m": 4250,
  "duration_s": 780,
  "eta_s": 936,
  "traffic_note": "morning rush",
  "has_toll": false,
  "has_ferry": false,
  "has_highway": true,
  "coordinates": [
    [
      -0.1867,
      5.604
    ],
    [
      -0.185,
      5.605
    ]
  ],
  "steps": [
    {
      "instruction": "Turn right onto Ring Road Central.",
      "verbal_alert": "In 500 metres, turn right onto Ring Road Central.",
      "verbal_instruction": "In 300 metres, turn right onto Ring Road Central.",
      "verbal_post": "Continue for 2 kilometres.",
      "instruction_landmark": "Turn right at Accra Mall onto Ring Road Central.",
      "landmark_confidence": 0.78,
      "alternate_landmarks": [
        "TotalEnergies Station"
      ],
      "name": "Ring Road Central",
      "near_landmark": "Accra Mall",
      "distance_m": 320.5,
      "duration_s": 45.2,
      "traffic_factor": 1.7,
      "traffic_severity": "heavy",
      "traffic_color": "#ef6c00",
      "coordinates": [
        [
          -0.1867,
          5.604
        ],
        [
          -0.185,
          5.605
        ]
      ],
      "surface": "paved",
      "surface_color": "#8d6e63",
      "bearing_before": 35,
      "bearing_after": 125,
      "turn_angle": -90,
      "turn_class": "turn",
      "lanes": [
        {
          "indications": [
            "straight"
          ],
          "active": false,
          "valid": false
        },
        {
          "indications": [
            "slight right"
          ],
          "active": true,
          "valid": false
        }
      ]
    }
  ],
  "landmarks_passed": [
    {
      "slug": "accra-mall",
      "name": "Accra Mall",
      "side": "right",
      "at_step": 2,
      "centroid": {
        "lat": 0,
        "lng": 0
      },
      "photo_url": "string",
      "phone": "string",
      "website": "string",
      "opening_hours": "string"
    }
  ],
  "alternatives": [
    {
      "distance_m": 4800,
      "duration_s": 900,
      "eta_s": 1080,
      "coordinates": [
        0
      ],
      "recommended": true,
      "recommend_reason": "string",
      "rain_note": "string",
      "rain_eta_penalty_s": 0,
      "flood_crossings": 0,
      "incident_count": 0,
      "has_unpaved": true,
      "unpaved_distance_m": 0
    }
  ],
  "recommended": true,
  "recommend_reason": "string",
  "rain_note": "string",
  "rain_eta_penalty_s": 0,
  "flood_crossings": 0,
  "incident_count": 0,
  "flood_avoidance_failed": true,
  "has_unpaved": true,
  "unpaved_distance_m": 0
}