MapMatchResponse

distance_mnumber<double>

Total matched route distance in metres.

Example: 1840.5

duration_snumber<double>

Estimated travel time of the matched route in seconds.

Example: 195

coordinatesnumber[][]

Matched route geometry as [lng, lat] pairs snapped to roads.

Possible values: >= 2, <= 2

Example: [[-0.1867,5.6037],[-0.1851,5.6052]]

steps object[]

Turn-by-turn steps of the matched route.

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

]

]

gps_distance_mnumber<double>

Sum of haversine distances between consecutive input trace points (metres). Represents the raw GPS path length before snapping.

Example: 1650

divergence_rationumber<double>

matched_distance / gps_distance. A ratio near 1.0 means the GPS trace closely follows the road network. Values above ~1.3 suggest the agent went off-road or the trace contains significant GPS noise — a useful fraud and compliance signal.

Example: 1.12

MapMatchResponse

{
  "distance_m": 1840.5,
  "duration_s": 195,
  "coordinates": [
    [
      -0.1867,
      5.6037
    ],
    [
      -0.1851,
      5.6052
    ]
  ],
  "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
        }
      ]
    }
  ],
  "gps_distance_m": 1650,
  "divergence_ratio": 1.12
}