Routing: directions, matrices, isochrones and map matching

On this page

The examples use YOUR_KEY. Get a free key to run them; it takes about a minute and needs no card.Get a free key

MapIron routes across the United States by car, truck, bike or foot on OpenStreetMap roads. Four endpoints share one set of options, and every answer may be stored: indefinitely on paid plans, 30 days on Free. Routing counts against the same monthly pool as address lookups, with the same hard cap and no overage.

Free-flow travel times. There is no live or historical traffic: durations are typical free-flow estimates (every answer says "travel_times": "free_flow"). Use them for planning, service areas, catchments and distance-based pricing, not as a live ETA. There's no navigation SDK.

Endpoint	What it does	Counts
`/v1/route`	A route through 2 to 25 points in order, with distance, duration, the line and optional turn-by-turn steps. Up to 2 alternatives between two points.	1 address lookup
`/v1/matrix`	Travel time and road distance from each source to each target: up to 50 × 50, 2,500 pairs.	1 per pair
`/v1/isochrone`	Polygons of everything reachable within up to 4 travel times (to 60 minutes) or distances (to 100 km).	2 per contour
`/v1/map-match`	Snaps a GPS trace (2 to 2,000 points) to the roads it followed.	1 per 100 points

All four take GET with query parameters or POST with a JSON object of the same names. Points are lat,lon, joined with ; in a query string, or arrays of [lat, lon] in JSON.

Directions

curl "https://api.mapiron.com/v1/route?points=41.8781,-87.6298;41.9684,-87.6610&profile=car&steps=1&key=YOUR_KEY"

curl -X POST "https://api.mapiron.com/v1/route?key=YOUR_KEY" -H "content-type: application/json" \
  -d '{"points": [[29.7604, -95.3698], [29.5502, -95.0970]], "profile": "truck", "truck_height": 4.1, "avoid": "tolls"}'

The answer follows the widely used OSRM response format, so existing route-drawing code works unchanged. The route line is an encoded polyline with 6 decimal places (geometry=geojson or polyline5 if you prefer); distance is metres and duration seconds.

{
  "code": "Ok",
  "routes": [
    {
      "distance": 12874.3,
      "duration": 1012.6,
      "geometry": "o~oxmAzfdhfD...",
      "legs": [ { "distance": 12874.3, "duration": 1012.6, "steps": [], "summary": "" } ]
    }
  ],
  "waypoints": [ { "location": [-87.62979, 41.87811] }, { "location": [-87.66101, 41.96842] } ],
  "profile": "car",
  "travel_times": "free_flow",
  "attribution": "© OpenStreetMap contributors",
  "license": "Produced Work from OpenStreetMap data (ODbL 1.0). You may keep these results indefinitely. ..."
}

Options for every endpoint

Parameter	What it does
`profile`	`car` (default), `truck`, `bike` or `foot`.
`avoid`	Any of `tolls`, `highways`, `ferries`, comma-separated. Avoided where possible, not forbidden.
`truck_height`, `truck_width`, `truck_length`	Metres; with `profile=truck`, routes keep to roads tagged for that size.
`truck_weight`	Tonnes, with `profile=truck`.
`hazmat`	`1` keeps a truck off roads closed to hazardous loads.
`steps`	`1` adds turn-by-turn instructions (route and map matching).
`language`	Instruction language, such as `en-US`, `es-ES`, `fr-FR`.
`alternatives`	`1` or `2` extra routes (two points only).

Matrix

curl "https://api.mapiron.com/v1/matrix?sources=41.8781,-87.6298;41.9684,-87.6610&targets=41.8781,-87.6298;41.9684,-87.6610&key=YOUR_KEY"

Pass sources and targets, or points alone for every point to every other. null means no route between that pair.

{
  "durations": [[0, 812], [804, 0]],
  "distances": [[0, 9617], [9580, 0]],
  "units": { "durations": "seconds", "distances": "metres" },
  "profile": "car", "travel_times": "free_flow", "attribution": "...", "license": "..."
}

Isochrones

curl "https://api.mapiron.com/v1/isochrone?point=30.2672,-97.7431&minutes=10,20,30&profile=car&key=YOUR_KEY"

Use minutes= or km= (not both), up to 4 values. The answer is a GeoJSON FeatureCollection of polygons, largest first; polygons=0 returns outlines instead.

Map matching

curl -X POST "https://api.mapiron.com/v1/map-match?key=YOUR_KEY" -H "content-type: application/json" \
  -d '{"points": [[41.8781, -87.6298], [41.8790, -87.6301], [41.8802, -87.6303]], "radius": 25}'

Optional times (unix seconds, one per point) helps with noisy traces; radius (1 to 100 metres, default 25) is how far a GPS point may be from its road. The answer has the OSRM matchings and tracepoints.

Errors

Code	When
`400 bad_request`	The input is malformed or over a limit above; the message says which.
`422 no_road_nearby`	A point is too far from any road the profile can use (or outside the US).
`422 no_route`	No route joins the points for this profile.
`429 slow_down`	The routing engine is busy; retry in a second.
`504 routing_timeout`	The request took longer than 15 seconds; make it smaller.

Storing results

Routes, travel times, matrices and isochrone polygons are produced from OpenStreetMap data. Paid plans may keep them indefinitely and Free for 30 days, in your own products too, with © OpenStreetMap contributors shown where you display them. You may not use routing answers to rebuild the road network or a routing graph. Many routing APIs forbid storing results at all.

Coverage and limits

The contiguous United States, Alaska and Hawaii (the road graph is rebuilt monthly from OpenStreetMap).
No live traffic, no historical speeds, no navigation SDK.
AI assistants can use the directions, isochrone and distance_matrix tools on the MCP server.

↑ Contents