Documentation menu
POST/isochrone
Access and price
| Auth | An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused. |
|---|---|
| Price | 1 call per contour, at most 4 contours per request. Class: standard, or premium for truck and ADR work. Published as unit_rules.isochrone in /pricing.json. |
| Premium | When the body asks for truck routing: "costing": "truck", a top-level adr object or "hazmat": true |
What it does
Reachability polygons for a time or distance budget from one or more locations.
An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: 1 call per contour, at most 4 contours per request.
Call it
curl -fsS -X POST "https://api.mapmap.ai/isochrone" \
-H "Authorization: Bearer $MAPMAP_KEY" \
-H "Content-Type: application/json" \
-d '{"contours":[{"time":10},{"time":20}],"costing":"truck","costing_options":{"truck":{"height":4}},"locations":[{"lat":51.5074,"lon":-0.1278}],"polygons":true}'Request body
application/json
Valhalla IsochroneRequest JSON: locations, costing, contours (each time minutes or distance km), optional polygons, denoise, generalize and costing_options. Scenario analysis: optional exclude_polygons; areas whose intersecting roads are avoided, as a JSON array of rings of [lon, lat] pairs (note the lon-first order), e.g. [[[-0.1,51.5],[-0.11,51.5],[-0.11,51.52]]], and exclude_locations, {lat, lon} objects each mapped to its nearest road(s), which are then excluded, so "close this bridge and recompute reachability" is one request. Valhalla engine only: a GraphHopper-backed deployment ignores both fields
Example: From website/public/docs/analysis.md:144
{
"contours": [
{
"time": 10
},
{
"time": 20
}
],
"costing": "truck",
"costing_options": {
"truck": {
"height": 4
}
},
"locations": [
{
"lat": 51.5074,
"lon": -0.1278
}
],
"polygons": true
}Responses
snapped_origin {lat, lon, distance_m} on the collection and on every feature's properties says where that was| Field | Type | Required | Description |
|---|---|---|---|
| engine | string | no | The routing engine that answered. |
| eta_calibration | object | no | Whether a typical-delay calibration applies to the contours (isochrones are drawn on the engine's own times). |
| features | object[] | no | One feature per contour: a Polygon (or a LineString without
polygons: true) with properties carrying the contour
(contour, metric) and its colour and fill styling. |
| snapped_origin | object | no | Where the origin snapped onto the road network (lat, lon)
and how far it moved, in metres. |
| type | string | no | Always FeatureCollection. |
Example: Recorded from the hosted gateway on 2026-11-05 with a test key: POST /isochrone, 5 minutes by car from Trafalgar Square; lists trimmed to their first items
{
"engine": "valhalla",
"eta_calibration": {
"applied": false,
"method": "gb_typical_delay_v1",
"note": "Isochrone contours are drawn on the routing engine's free-flowing times, which drive local roads at their speed limits with almost no time for junctions or congestion. Car and truck times from POST /route and POST /matrix in Great Britain include the typical delay on local roads, typically about a third more time for a trip within a town and little on motorways, so a contour here reaches further than those times would. It is not scaled to match, because the delay differs by road type and a uniform scaling would draw the wrong shape.",
"travel_times": "free_flow"
},
"features": [
{
"geometry": {
"coordinates": [
[
[
-0.126006,
51.524896
],
[
-0.146251,
51.518289
],
[
-0.153666,
51.501874
],
[
-0.145275,
51.493802
],
[
-0.121546,
51.493534
],
[
-0.108006,
51.506534
],
[
-0.104286,
51.517254
],
[
-0.126006,
51.524896
]
]
],
"type": "Polygon"
},
"properties": {
"color": "#bf4040",
"contour": 5,
"fill": "#bf4040",
"fill-opacity": 0.33,
"fillColor": "#bf4040",
"fillOpacity": 0.33,
"metric": "time",
"opacity": 0.33,
"snapped_origin": {
"distance_m": 52.2,
"lat": 51.507534,
"lon": -0.128007
}
},
"type": "Feature"
}
],
"snapped_origin": {
"distance_m": 52.2,
"lat": 51.507534,
"lon": -0.128007
},
"type": "FeatureCollection"
}application/problem+json · Problem
unauthorized); the body carries signup, docs and a one-call hint for a free keyapplication/problem+json · Problem
X-PAYMENT). Not problem+jsonapplication/json · X402PaymentRequired
scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)application/problem+json · Problem
text/plain
urn:sn-gateway:problem:no-roads-near-origin): nothing the costing can use lies within 5 km of the origin, e.g. open sea or desert. Carries max_snap_m and the requested origin. Free: not billed and draws no quotaapplication/problem+json · Problem
rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)application/problem+json · Problem
application/problem+json · Problem
request-timeout)application/problem+json · Problem
Error bodies follow the shared problem model documented on API conventions.
Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId post_isochrone