Map Matching Tool
map_matching_toolSnap noisy GPS traces to roads, bike paths, or walkways using Mapbox Map Matching. Clean recorded trip and fleet tracking data by returning routes aligned to the road network with confidence scores.
Instructions
Snap a recorded GPS trace to roads using Mapbox Map Matching API. Takes a dense, noisy coordinate sequence (2-100 points, recorded seconds or tens of meters apart) and returns a clean route aligned with actual roads, bike paths, or walkways. Useful for analyzing recorded trips, cleaning fleet tracking data, or processing fitness activity traces. Not for routing between a few places or addresses: points kilometers apart fail to match, so use directions_tool for that. Returns confidence scores, matched geometry, and optional traffic/speed annotations.
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": {
"coordinates": "<coordinates>"
},
"name": "map_matching_tool"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | Routing profile for different modes of transport. Options: - driving: automotive based on road network - driving-traffic: automotive with current traffic conditions - walking: pedestrian/hiking - cycling: bicycle | driving |
| overview | No | Format of the returned geometry. Options: - full: Returns full geometry with all points - simplified: Returns simplified geometry - false: No geometry returned | full |
| radiuses | No | Array of maximum distances (in meters, greater than 0 and up to 50) each coordinate can snap to the road network. If provided, must have the same length as coordinates array. Default is 5 meters. Use smaller values (1-10m) for clean GPS traces, larger values (20-50m) for noisy GPS traces. | |
| geometries | No | Format of the returned geometry. Options: - geojson: GeoJSON LineString (recommended) - polyline: Polyline with precision 5 - polyline6: Polyline with precision 6 | geojson |
| timestamps | No | Array of Unix timestamps (in seconds) corresponding to each coordinate. If provided, must have the same length as coordinates array and be in ascending order. Used to improve matching accuracy based on speed. | |
| annotations | No | Additional data to include in the response. Options: - speed: Speed limit per segment (km/h) - distance: Distance per segment (meters) - duration: Duration per segment (seconds) - congestion: Traffic level per segment (low, moderate, heavy, severe) | |
| coordinates | Yes | Array of coordinate objects with longitude and latitude properties representing a GPS trace. Must include at least 2 and up to 100 coordinate pairs. Coordinates should be in the order they were recorded. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| matchings | No | ||
| tracepoints | No | ||
| mapboxRender | No | Map-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry. |