Calculate an isochrone or isodistance

Signed in? Open this endpoint in the dashboard playground, which uses your organization automatically. Signed out, use Try in Playground below with your API key.

GET

/isoline

GET

/isoline

Calculates the area reachable from an origin within one or more travel-time or travel-distance limits (Valhalla isochrone).

To calculate, provide lat, lon, type, mode and one or more range values.
With type=time, each range is seconds. With type=distance, ranges are meters (units=metric) or miles (units=imperial).
Up to 10 ranges; the response holds one Polygon or MultiPolygon feature per range, in request order.
Every calculated result is saved. Retrieval by id is this same path: call GET /isoline?id=<id> with only id (and optionally format) to get the stored result again. Mixing id with calculation parameters returns 400; an unknown id returns 404.
The default format=geojson returns a GeoJSON FeatureCollection; topojson (JSON) and geobuf (binary, application/octet-stream) are also available.
Results carry no datasource field; isolines are computed from OpenStreetMap-derived road data (c) OpenStreetMap contributors.

Deviation (empty): details=population (and any other details value) returns an empty object per dataset.

Deviation (ignored): traffic is validated but not applied; results are always free_flow.

Deviation (approximated): route_type=less_maneuvers is approximated with a Valhalla maneuver penalty; avoid importance is approximated by scaling Valhalla's use_tolls / use_highways / use_ferry preference (1 - importance).

Deviation (unsupported): mode=transit and mode=approximated_transit return 400 (no transit data).

Not supported: mode=transit, mode=approximated_transit. There is no upper bound on a single range value beyond Valhalla's own limits (Geoapify's 3600 s / 100 km cap is not enforced by the gateway). avoid rules green_zones, transfers, country_codes have no effect.

Example: lat=39.7684&lon=-86.1581&type=time&mode=drive&range=300&apiKey=YOUR_API_KEY

Authorization

queryapiKey<token>

Your API key from the dashboard, sent as ?apiKey=<key>.

Query Parameters

lat?number

Origin latitude in decimal degrees. Required when calculating; omit when retrieving by id.

Range-90 <= value <= 90

lon?number

Origin longitude in decimal degrees. Required when calculating; omit when retrieving by id.

Range-180 <= value <= 180

range?array<>

One to 10 comma-separated limits. Required when calculating. Seconds for type=time; meters (metric) or miles (imperial) for type=distance. Each value must be at least 1.

Items1 <= items <= 10

type?string

time for an isochrone, distance for an isodistance. Required when calculating.

Value in"time""distance"

mode?string

Travel mode. Required when calculating.

Deviation (unsupported): transit and approximated_transit are not accepted (400, no transit data).

Value in"walk""hike""scooter""motorcycle""drive""light_truck""bicycle""mountain_bike""road_bike""bus""medium_truck""truck""truck_dangerous_goods""heavy_truck""long_truck"

units?string

Unit system for distance ranges and max_speed. Metric is meters and km/h; imperial is miles and mph. Time ranges are always seconds.

Default"metric"

Value in"metric""imperial"

avoid?array<>

Features or areas to avoid, repeated or | separated: tolls, ferries, highways, green_zones, transfers (optional :importance 0 to 1), location:lat,lon, polygon:lat,lon;lat,lon;... (3+ points), country_codes:us,ca. The _lonlat / _latlon variants of location and polygon set the coordinate order.

Deviation (ignored): green_zones, transfers and country_codes are accepted but have no effect; tolls and highways apply to motorized modes only.

Deviation (approximated): importance scales Valhalla's preference (1 - importance) rather than Geoapify's weighting; no importance means full avoidance.

route_type?string

Route optimization preference.

Deviation (approximated): less_maneuvers is approximated with a Valhalla maneuver penalty and returns 400 for non-motorized modes.

Default"balanced"

Value in"balanced""short""less_maneuvers"

traffic?string

Traffic model. Accepted and validated, but not applied.

Deviation (ignored): results are always computed free-flow and reported as traffic: free_flow.

Default"free_flow"

Value in"free_flow""approximated"

max_speed?number

Maximum travel speed, 10 to 252 km/h (metric) or 6.5 to 155 mph (imperial). Deviation (ignored): has no effect for walk, hike and bicycle modes.

Range6.5 <= value <= 252

details?array<>

Comma-separated detail datasets to add to every feature (5 to 100 characters each), such as population.

Deviation (empty): each requested dataset is returned as an empty object {}; population has no data in v1.

id?string

Id from a previous calculation (properties.id). Use by itself (only format may accompany it); any calculation parameter alongside it returns 400.

Match^[a-f0-9]{32}$

format?string

Response encoding. geojson (default) and topojson are application/json; geobuf is application/octet-stream.

Default"geojson"

Value in"geojson""topojson""geobuf"

Response Body

Calculated or retrieved isoline.

response

Isoline result. One feature per requested range, in request order. properties.id is the retrieval id.

type*unknown

features*array<>

properties*

Example Request

curl -X GET 'https://api.data.graphitelab.ai/v1/isoline?lat=39.7684&lon=-86.1581&range=300&type=time&mode=drive&units=metric&avoid=tolls&route_type=balanced&traffic=free_flow&max_speed=80&details=population&id=768fc88900268ab0ec5aa67fbfa09cc2&format=geojson'

Example Request

curl -X GET 'https://api.data.graphitelab.ai/v1/isoline?lat=39.7684&lon=-86.1581&range=300&type=time&mode=drive&units=metric&avoid=tolls&route_type=balanced&traffic=free_flow&max_speed=80&details=population&id=768fc88900268ab0ec5aa67fbfa09cc2&format=geojson'

Example ResponseSchema

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "fdeada42d77b94d79a2a00316901584c",
        "lat": 39.7684,
        "lon": -86.1581,
        "mode": "drive",
        "type": "time",
        "range": 300,
        "units": "metric",
        "route_type": "balanced",
        "traffic": "free_flow"
      },
      "geometry": {
        "coordinates": [
          [
            [
              -86.166099,
              39.8033
            ],
            [
              -86.16625,
              39.7984
            ],
            [
              -86.16532,
              39.7974
            ],
            [
              -86.167292,
              39.7954
            ],
            [
              -86.165511,
              39.794988
            ],
            [
              -86.165382,
              39.7924
            ],
            [
              -86.166099,
              39.8033
            ]
          ]
        ],
        "type": "Polygon"
      },
      "bbox": [
        -86.190507,
        39.737708,
        -86.119816,
        39.8033
      ]
    }
  ],
  "properties": {
    "id": "fdeada42d77b94d79a2a00316901584c"
  }
}

{  "type": "FeatureCollection",  "features": [    {      "type": "Feature",      "properties": {        "id": "fdeada42d77b94d79a2a00316901584c",        "lat": 39.7684,        "lon": -86.1581,        "mode": "drive",        "type": "time",        "range": 300,        "units": "metric",        "route_type": "balanced",        "traffic": "free_flow"      },      "geometry": {        "coordinates": [          [            [              -86.166099,              39.8033            ],            [              -86.16625,              39.7984            ],            [              -86.16532,              39.7974            ],            [              -86.167292,              39.7954            ],            [              -86.165511,              39.794988            ],            [              -86.165382,              39.7924            ],            [              -86.166099,              39.8033            ]          ]        ],        "type": "Polygon"      },      "bbox": [        -86.190507,        39.737708,        -86.119816,        39.8033      ]    }  ],  "properties": {    "id": "fdeada42d77b94d79a2a00316901584c"  }}

Calculate an isochrone or isodistance

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Query Parameters

Response Body