Isochrone

An isochrone, from the Greek root words iso (equal) and chrone (time), is a line that connects points of equal travel time around a given location. The Mapbox Isochrone API computes areas that are reachable within a specified amount of time from a location, and returns the reachable regions as contours of polygons or lines that you can display on a map.

playground
Isochrone API playground

Build an Isochrone API request and see the reachable areas from a location on a map.

Retrieve isochrones around a location

get
/isochrone/v1/{profile}/{coordinates}?{contours_minutes}

Given a location and a routing profile, retrieve up to four isochrone contours. The contours are calculated using rasters and are returned as either polygon or line features, depending on your input setting for the polygons parameter.

Required parametersDescription
profileA Mapbox Directions routing profile ID. Options are mapbox/driving for travel times by car, mapbox/walking for pedestrian and hiking travel times, and mapbox/cycling for travel times by bicycle. For more detailed descriptions of these routing profiles, see the Directions API documentation.
coordinatesA {longitude,latitude} coordinate pair around which to center the isochrone lines.
contours_minutesThe times in minutes to use for each isochrone contour. You can specify up to four contours. Times must be in increasing order. The maximum time that can be specified is 60 minutes.

You can further refine the results from this endpoint with the following optional parameters:

Optional parametersDescription
contours_colorsThe colors to use for each isochrone contour, specified as hex values without a leading # (for example, ff0000 for red). If this parameter is used, there must be the same number of colors as there are entries in contours_minutes. If no colors are specified, the Isochrone API will assign a default rainbow color scheme to the output.
polygonsSpecify whether to return the contours as GeoJSON polygons (true) or linestrings (false, default). When polygons=true, any contour that forms a ring is returned as a polygon.
denoiseA floating point value from 0.0 to 1.0 that can be used to remove smaller contours. The default is 1.0. A value of 1.0 will only return the largest contour for a given time value. A value of 0.5 drops any contours that are less than half the area of the largest contour in the set of contours for that same time value.
generalizeA positive floating point value in meters used as the tolerance for Douglas-Peucker generalization. There is no upper bound. If no value is specified in the request, the Isochrone API will choose the most optimized generalization to use for the request. Note that the generalization of contours can lead to self-intersections, as well as intersections of adjacent contours.

Example request: Retrieve isochrones around a location

$ curl "https://api.mapbox.com/isochrone/v1/mapbox/driving/-118.22258,33.99038?contours_minutes=5,10,15&contours_colors=6706ce,04e813,4286f4&polygons=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Retrieve isochrones around a location

In the response to a request to the Mapbox Isochrone API, the isochrone contours are returned as a GeoJSON Feature Collection. Each feature object in the Feature Collection is an isochrone, and contains the following properties:

PropertyDescription
typeFeature, a GeoJSON type from the GeoJSON specification.
propertiesAn object that describes how the isochrone should be drawn.
properties.contourThe time in minutes used for the isochrone contour.
properties.colorThe color of the isochrone line if the geometry property is Linestring.
properties.opacityThe opacity of the isochrone line if the geometry property is Linestring.
properties.fillThe fill color of the isochrone polygon if the geometry property is Polygon, suitable for use in geojson.io.
properties.fill-opacityThe fill opacity of the isochrone polygon if the geometry property is Polygon, suitable for use in geojson.io.
properties.fillColorThe fill color of the isochrone polygon if the geometry property is Polygon, suitable for use in Leaflet.
properties.fillOpacityThe fill opacity of the isochrone polygon if the geometry property is Polygon, suitable for use in Leaflet.
geometryAn object that describes the geometry of the isochrone.
geometry.coordinatesAn array of arrays that contain the coordinates for the isochrone, formatted as [longitude,latitude].
geometry.typeThe GeoJSON type of the returned geometry. Either Linestring (default) or Polygon (if polygons=true was specified in the query).

Example response: Retrieve isochrones around a location

{
    "features": [
        {
            "properties": {
                "contour": 15,
                "color": "#4286f4",
                "opacity": 0.33,
                "fill": "#4286f4",
                "fill-opacity": 0.33,
                "fillColor": "#4286f4",
                "fillOpacity": 0.33
            },
            "type": "Feature",
            "geometry": {
                "coordinates": [ "arrays of longitude, latitude coordinates" ],
                "type": "Polygon"
            }
        },
        {
            "properties": {
                "contour": 10,
                "color": "#04e813",
                "opacity": 0.33,
                "fill": "#04e813",
                "fill-opacity": 0.33,
                "fillColor": "#04e813",
                "fillOpacity": 0.33
            },
            "type": "Feature",
            "geometry": {
                "coordinates": [ "arrays of longitude, latitude coordinates" ],
                "type": "Polygon"
            }
        },
        {
            "properties": {
                "contour": 5,
                "color": "#6706ce",
                "opacity": 0.33,
                "fill": "#6706ce",
                "fill-opacity": 0.33,
                "fillColor": "#6706ce",
                "fillOpacity": 0.33
            },
            "type": "Feature",
            "geometry": {
                "coordinates": [ "arrays of longitude, latitude coordinates" ],
                "type": "Polygon"
            }
        }
    ],
    "type": "FeatureCollection"
}

Supported libraries: Retrieve isochrones around a location

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Isochrone API errors

Response body messageHTTP status codeDescription
Could not find a matching segment for input coordinates200No road segment could be matched for coordinates. Check for coordinates that are too far away from a road.
No route found200There was no route found for the given coordinates. Check for impossible routes (for example, routes over oceans without ferry connections).
Not Authorized - No Token401No token was used in the query.
Not Authorized - Invalid Token401Check the access token you used in the query.
Not Found404Check the profile you used in the query, which must be one of mapbox/driving, mapbox/walking, or mapbox/cycling.
Latitude must be between -90 and 90422Check the coordinates used in the query.
Should have required property 'contours_minutes'422The query must include the contours_minutes parameter.
Contours_minutes must be an integer between 1 and 60422The contours_minutes specified in the query is larger than 60 or contains non-numeric characters.
Contours_colors should be a hexidecimal422contours_colors must be specified as a hexidecimal color code.

Isochrone API restrictions and limits

  • The Isochrone API is limited to 300 requests per minute.
  • The Isochrone API supports 1 coordinate per request.
  • The Isochrone API can support a maximum of 4 isochrone contours per request.
  • The maximum time that can be specified for an isochrone contour is 60 minutes.
  • Results must be displayed on a Mapbox map using one of the Mapbox libraries or SDKs.
If you require a higher rate limit, contact us.

Isochrone API pricing

  • Billed by requests
  • See rates and discounts per Isochrone API request in the pricing page's Navigation section

Usage of the Isochrone API is measured in API requests. Details about the number of Isochrone API requests included in the free tier and the cost per request beyond what is included in the free tier are available on the pricing page.