---
title: "Travel-time contours from a block or point"
method: GET
path: "/v1/isochrone"
tags: ["isochrone"]
---

# Travel-time contours from a block or point

`GET /v1/isochrone`

## Request

- Base URL: `https://api.close.city`
- URL: `https://api.close.city/v1/isochrone`
- Auth: HTTP bearer

Travel-time contours around a census block (by GEOID) or a lat/lon point.
Supply `block` XOR `lon`+`lat`, and `minutes` XOR `contours` (up to 4
ascending levels). `format=geojson` returns contour polygons (largest first);
`format=blocks` returns the reachable blocks with their travel minutes.
Metered at 10 tokens per contour level with a `ck_` key; unmetered for a Close+
member `mt_` bearer.

## Query parameters

- `block` string, nullable: 15-digit census block GEOID
- `lon` number, nullable: Longitude (WGS84)
- `lat` number, nullable: Latitude (WGS84)
- `mode` string: walk | bike | transit
- `direction` string: to | from
- `minutes` integer, nullable: Single threshold, 1-60
- `contours` string, nullable: Up to 4 ascending thresholds, e.g. 15,30,45
- `format` string: geojson | blocks
- `v` string, nullable: Opaque CDN cache-buster; echoed

## Response `200`

Successful Response

- union
  - IsochroneGeoJSON: GET /v1/isochrone?format=geojson (routers.isochrone._geojson_body). Features are ordered largest contour first (painter's order).
    - `assumptions` IsochroneAssumptions, required: Routing assumptions echoed from the store. Keys are store-defined; the current set is listed but extra keys are allowed. (routers.isochrone._assumptions)
      - `max_trip_duration_min` integer, nullable
      - `transit_departure` string, nullable
      - `transit_percentile` integer, nullable
      - `transit_window_min` integer, nullable
    - `block` string, required: 15-digit origin/destination block GEOID
    - `direction` string, required: 'to' or 'from'
    - `features` IsochroneFeature[], required
      - `geometry` object, nullable: GeoJSON geometry, or null when the contour is empty
      - `properties` IsochroneFeatureProperties, required
        - `contour` integer, required: Contour level in minutes
        - `mode` string, required
        - `reachable_blocks` integer, required
      - `type` string, required
    - `mode` string, required
    - `type` string, required
    - `v` string, nullable: Echoed cache-buster, when supplied
    - `version` string, required: Store version key
  - IsochroneBlocks: GET /v1/isochrone?format=blocks (routers.isochrone._blocks_body).
    - `assumptions` IsochroneAssumptions, required: Routing assumptions echoed from the store. Keys are store-defined; the current set is listed but extra keys are allowed. (routers.isochrone._assumptions)
      - `max_trip_duration_min` integer, nullable
      - `transit_departure` string, nullable
      - `transit_percentile` integer, nullable
      - `transit_window_min` integer, nullable
    - `block` string, required
    - `blocks` IsochroneBlock[], required
      - `geoid` string, required
      - `travel_min` integer, required
    - `direction` string, required
    - `mode` string, required
    - `reachable_blocks` integer, required
    - `v` string, nullable
    - `version` string, required

## Other responses

- `304`: Not modified (If-None-Match matched the ETag); no body, no tokens charged
- `400`: Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex, missing-origins, too-many-origins)
- `401`: Missing or invalid API key (missing-key, invalid-key)
- `403`: Key disabled (account-disabled)
- `404`: Resource not found (block-not-found, poi-not-found, place-not-found, point-not-covered, no-isochrone-data, direction-not-available)
- `429`: Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After
- `503`: Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After

---

[API](https://skmtc.dev/close-city/apis/close-api.md) · [All operations](https://skmtc.dev/close-city/apis/close-api/llms.txt) · [OpenAPI document](https://skmtc.dev/close-city/apis/close-api/revisions/a70e7c778d65?raw)