map_match
Map matching snaps raw GPS breadcrumbs to the road network. Feed a recorded trace (2–100 points) and get back the road-accurate route that was actually driven: matched geometry, distance, time, road names, and a 0–1 match confidence. matched: true only means a route was returned — gate on match_status: full when every input point was matched or interpolated onto the road network and the match is one continuous section, none when no point was, otherwise partial. coverage gives the per-point counts, unmatched_ranges (0-based input indexes that did not match) and route_sections (above 1, the geometry, distance and time cover only the first section — split the trace there). match_status is null, with coverage.unavailable_reason, when the per-point check could not be completed. Sparsely-reported traces (consecutive fixes farther apart than the default breakage distance — e.g. fleet units reporting every several minutes on a highway) can split into multiple sections; increase breakage_distance_m to keep them as one. Total matched distance is limited to 200 km per call — split longer sparse traces by distance, not only by the 100-point cap. Use for fleet trace cleanup, mileage from GPS logs, and reconstructing routes from telemetry. road_names come from the route's maneuver points, so they cover the roads the route turns onto or starts on — for the name of every segment actually travelled, use trace_attributes. For planning a route between places, use directions instead.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"shape": "<shape>"
},
"name": "map_match"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| shape | Yes | Raw GPS breadcrumb trail in travel order — 2 to 100 points of { lat, lon, time? }. `time` is optional epoch seconds; timestamps improve match quality on noisy traces. | |
| costing | No | Transport mode the trace was recorded with (default: auto) | |
| search_radius | No | Snap radius in meters around each point (1–100). Increase for noisy GPS. | |
| vehicle_profile | No | Truck preset (DRY_VAN_53, FLATBED_48, BOX_TRUCK_26, …) — same 10-profile table as directions. Implies costing=truck. | |
| breakage_distance_m | No | Maximum gap, in meters, between consecutive fixes before the trace is split into separate sections (100–20000). Increase for sparsely-reported GPS, such as fleet units reporting every several minutes on a highway. Optional — omitted uses the default. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| legs | Yes | ||
| meta | No | ||
| costing | Yes | ||
| geojson | No | ||
| matched | Yes | True when a route was returned for the trace. It does NOT mean the whole trace matched — use `match_status`. | |
| coverage | No | Per-point coverage of the trace from the matcher's own per-point status — independent of the distance-based `confidence`. Every key is always present. | |
| geometry | No | ||
| confidence | Yes | 0–1: fraction of input GPS points within the snap tolerance of the matched route. A distance heuristic: it ignores point order and which parallel roadway was matched. For the matcher's own per-point result use `match_status` / `coverage`. | |
| road_names | Yes | ||
| distance_km | Yes | ||
| match_status | No | Whole-trace match status from the matcher's own per-point results. `full`: every input point was matched or interpolated onto the road network AND the match is one continuous section. `none`: no input point was matched or interpolated. `partial`: anything else — some points unmatched, or the match broke into more than one section. null when the per-point check could not be completed; `coverage.unavailable_reason` says why. Gate on this field, not on `matched`. | |
| costing_options | No | ||
| vehicle_profile | No | ||
| duration_seconds | Yes |