---
title: "Generate reachability polygons (isochrones)"
method: GET
path: "/v1/isochrone"
tags: ["Routing"]
---

# Generate reachability polygons (isochrones)

`GET /v1/isochrone`

## Request

- Base URL: `https://geo.thinair.co`
- URL: `https://geo.thinair.co/v1/isochrone`
- Auth: HTTP bearer

Travel-time or travel-distance reachability polygons from an origin. Returns a GeoJSON FeatureCollection of nested Polygon contours — one per requested band. Largest natural latency budget on the API (p95 ≤500ms cache miss).

## Query parameters

- `location` string: Origin — free-text address or 'lat,lon' string.
- `lat` number: Origin latitude (paired with `lon`; alternative to `location`).
- `lon` number: Origin longitude (paired with `lat`; alternative to `location`).
- `contours_minutes` number[]: Time bands in minutes; repeatable or CSV. Each value 1..120. Max 4 bands per call.
- `contours_km` number[]: Distance bands in km; repeatable or CSV. Each value 1..200. Max 4 bands per call.
- `costing` 'auto' | 'truck' | 'bicycle' | 'pedestrian': Travel mode (default: auto).
- `preset` string: Route preset name (overrides `costing` + truck params).
- `truck_height` number: Truck height in meters.
- `truck_weight` number: Truck weight in metric tons.
- `hazmat` boolean: Hazmat-restricted routing flag.

## Response `200`

Isochrone polygons + metadata. Service returns 200 with `upstream_error` populated on routing-engine failures.

- IsochroneResponse
  - `origin` object, required
    - `lat` number, required: Latitude in decimal degrees, WGS84.
    - `lon` number, required: Longitude in decimal degrees, WGS84.
    - `label` string
  - `costing` string, required
  - `preset` string
  - `preset_note` string
  - `costing_options` object
  - `contour_values` number[], required
  - `metric` string, required
  - `geojson` object, required
    - `type` 'FeatureCollection', required
    - `features` IsochroneFeature[], required
      - `type` 'Feature', required
      - `geometry` object, required
        - `type` string, required
        - `coordinates` unknown
      - `properties` object, required
  - `meta` object, required
    - `upstream_ms` number, required
    - `feature_count` number, required
    - `cacheHit` boolean
  - `upstream_error` string, nullable
  - `structured_error` StructuredError
    - `code` string, required: Stable, snake_case identifier callers can switch on.
    - `message` string, required
    - `details` object

## Other responses

- `400`: Invalid query parameters.
- `429`: Quota exceeded or rate-limited.

---

[API](https://skmtc.dev/thinair/apis/thinair-geo-api.md) · [All operations](https://skmtc.dev/thinair/apis/thinair-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinair/apis/thinair-geo-api/revisions/8fac2d5e4b34?raw)