# Routing: directions, matrices, isochrones and map matching

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

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

```bash
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

```bash
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

```bash
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

```bash
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](https://mapiron.com/docs/mcp).

---
Source: https://mapiron.com/docs/routing · Map data © OpenStreetMap contributors · Index: https://mapiron.com/llms.txt