Documentation / Routing, matrix, map matching and optimization
Routing, matrix, map matching and optimization
Calculate routes, travel-time matrices, isochrones, matched GPS traces, road-network positions, and stop sequences.
On this page
Compute travel times between many points
Routing returns turn-by-turn instructions and geometry, with an optional terrain elevation profile. Matrix calculates travel times and distances between origin-destination pairs. Isochrones return reachable-area polygons for specified travel-time bands.
Map matching associates a GPS trace with the road network and returns matched geometry, confidence, and OSM way IDs. Snapping finds the nearest network position. Optimization calculates a visit order while keeping the first and last stops fixed.
curl --fail-with-body -X POST https://api.mapsource.io/matrix \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" -H 'content-type: application/json' -d '{
"sources": [{"lat": 47.6062, "lon": -122.3321}],
"targets": [{"lat": 47.6205, "lon": -122.3493}, {"lat": 47.65, "lon": -122.30}],
"costing": "auto"
}'
curl --fail-with-body -X POST https://api.mapsource.io/map-match \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" -H 'content-type: application/json' -d '{
"shape": [{"lat": 47.6062, "lon": -122.3321},
{"lat": 47.6075, "lon": -122.3340},
{"lat": 47.6090, "lon": -122.3360}]
}'Endpoints and parameters
Select an endpoint for its full parameter and response reference.
| Operation | Endpoint |
|---|---|
| Compute a turn-by-turn route | POST /api/route |
| Compute a travel-time and distance matrix | POST /api/matrix |
| Compute reachable-area polygons | POST /api/isochrone |
| Fit a GPS trace to the road network | POST /api/map-match |
| Snap points to the road network | POST /api/snap |
| Solve the visit order for a set of stops | POST /api/optimize |
Application integration
Send coordinate objects with lat and lon fields and select a costing mode for the intended travel type. Preserve waypoint order for routes and GPS point order for map matching.
Check for null matrix or snapping results before further processing. For static route maps, pass the returned geometry to the rendering API. Route requests with elevation enabled include a terrain profile.
Access and limits
Route: 2–10 waypoints. Matrix: up to 25 sources, 25 targets, and 625 pairs. Isochrone: up to four bands of 1–60 minutes. Map matching: 2–1,000 trace points. Snap: up to 50 points. Optimization: 3–20 stops.
Supported costing modes are auto, bicycle, pedestrian, truck, motor_scooter, and bus. Requests consume subscription quota. An unroutable or invalid request returns HTTP 422; update the input before retrying.
See plan limits for request allowances and error handling for quota and retry behavior.
Responses and examples
Unreachable matrix pairs have null values. Map matching returns confidence scores for application-level validation. Snapping returns null when no nearby network position is found. Routing results are not certified for safety-critical navigation.
Example responses and timing measurements · Current service status
Attribution
Routing is computed from OpenStreetMap data with Valhalla. Display © OpenStreetMap contributors with any rendered result.
Questions about this guide? Contact support.