Skip to content
Documentation menu
docs / api / post-isochrone
Isochrones

POST/isochrone

Access and price

AuthAn API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused.
Price1 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.
PremiumWhen 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

bash
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

json
{
  "contours": [
    {
      "time": 10
    },
    {
      "time": 20
    }
  ],
  "costing": "truck",
  "costing_options": {
    "truck": {
      "height": 4
    }
  },
  "locations": [
    {
      "lat": 51.5074,
      "lon": -0.1278
    }
  ],
  "polygons": true
}

Responses

200GeoJSON FeatureCollection of contour geometries, drawn from the origin snapped onto the nearest road the costing can use (ferries excluded, at most 5 km away). snapped_origin {lat, lon, distance_m} on the collection and on every feature's properties says where that was
FieldTypeRequiredDescription
enginestringnoThe routing engine that answered.
eta_calibrationobjectnoWhether a typical-delay calibration applies to the contours (isochrones are drawn on the engine's own times).
featuresobject[]noOne 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_originobjectnoWhere the origin snapped onto the road network (lat, lon) and how far it moved, in metres.
typestringnoAlways 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

json
{
  "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"
}
400Invalid request

application/problem+json · Problem

401Missing or invalid API key. Also: No key, or a missing, malformed, unknown, revoked or expired one (unauthorized); the body carries signup, docs and a one-call hint for a free key

application/problem+json · Problem

402Beyond the included volume with no way to pay this call: an x402 body naming how to pay (provisional key past its allowance, prepaid balance below the price, or a rejected X-PAYMENT). Not problem+json

application/json · X402PaymentRequired

403The key may not call this: a browser key outside its scope (scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)

application/problem+json · Problem

413The request declares a body larger than 1048576 bytes (plain text, not problem+json)

text/plain

422No roads near this point (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 quota

application/problem+json · Problem

429Quota or rate limit exceeded. Also: Per-key rate limit (rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)

application/problem+json · Problem

502Upstream routing engine failed

application/problem+json · Problem

504The request did not finish within the gateway's request deadline (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