Isochrone API

Isochrone API allows you to build isochrones (availability zones) on the map:

Areas with boundaries that are reachable from the specified point in a set time. For example, to get a restaurant delivery zone for couriers by car.
Areas from which boundaries you can reach the specified point in a set time. For example, to build an area where you can reach a metro station on foot in 10 minutes.

Main features

You can specify the following parameters when building availability zones:

Travel time.
Coordinates of the point.
Direction of movement: from the specified point to the area boundaries or from the boundaries to the point.
Transportation type:
- On foot.
- By car.
- By bicycle.
- By public transport: metro, bus, and others.
Start travel time (departure time). Specify to use information about statistical traffic jams for calculation instead of information about current traffic jams.
Level of polygon detailing on the map.

For each availability zone, the full geometry in the WKT (well-known text) format is calculated.

For more information about the parameters, see the API Reference.

Example usage

To build availability zones on the map using the Isochrone API, use the interactive example. Select the direction of movement, the transportation type, and the travel time.

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>2GIS Isochrone API</title>
    <meta name="description" content="Building availability zones" />
    <style>
        html,
        body,
        #container {
            margin: 0;
            width: 100%;
            height: 100%;
            overflow: hidden;
        }

        select {
            border: 0;
            padding: 4px 10px;
            font-size: 13px;
            box-shadow: 0 1px 3px 0 rgba(38, 38, 38, 0.5);
            border-radius: 4px;
        }
    </style>
</head>

<body>
    <div id="container"></div>
    <div id="tooltip"></div>
    <script src="https://mapgl.2gis.com/api/js/v1"></script>
    <script>
        const reqUrl = `https://routing.api.2gis.com/isochrone/2.0.0?key=Your directions API access key`;
        const start = {
            lat: 25.19918,
            lon: 55.27280,
        };

        const map = new mapgl.Map('container', {
            center: [start.lon, start.lat],
            zoom: 11,
            key: 'Your API access key',
        });

        const controlsHtml = `<div class="controls">
                    <select name="reverse">
                        <option value="to">Go here</option>
                        <option value="from" selected>Go from here</option>
                    </select>
                    <select name="transport">
                        <option value="walking">On foot</option>
                        <option value="driving" selected>By car</option>
                    </select>
                    <select name="duration">
                        <option value="600" selected>10 min</option>
                        <option value="1200">20 min</option>
                    </select>
                </div>`;

        new mapgl.Control(map, controlsHtml, {
            position: "topLeft"
        });

        const reverseSelectEl = document.querySelector('select[name="reverse"]');
        const transportSelectEl = document.querySelector('select[name="transport"]');
        const durationSelectEl = document.querySelector('select[name="duration"]');

        const startMarker = new mapgl.Marker(map, {
            coordinates: [start.lon, start.lat]
        });

        let polygon;
        function renderGeometries(geometry) {
            if (polygon) {
                polygon.destroy();
            }
            const coordinates = geometry
                .replace("MULTIPOLYGON(((", "")
                .replace(")))", "")
                .split(",")
                .map((point) => point.trim().split(" ").map(Number));
            polygon = new mapgl.Polygon(map, {
                coordinates: [coordinates],
                strokeWidth: 3,
                strokeColor: "#bb0000",
                fillColor: "rgba(187, 0, 0, 0.3)"
            });
        }

        window.addEventListener("change", (evt) => {
            if (
                evt.target.name === "reverse" ||
                evt.target.name === "transport" ||
                evt.target.name === "duration"
            ) {
                updateGeometries();
            }
        });
        updateGeometries();

        function updateGeometries() {
            const reverse = reverseSelectEl.value === "to";
            const transport = transportSelectEl.value;
            const duration = Number(durationSelectEl.value);

            fetch(reqUrl, {
                method: "POST",
                headers: {
                    "Content-Type": "application/json"
                },
                body: JSON.stringify({
                    start,
                    durations: [duration],
                    transport,
                    reverse,
                    format: "wkt",
                    start_time: new Date().toISOString()
                })
            })
                .then((res) => res.json())
                .then((parsed) => {
                    if (parsed.isochrones && parsed.isochrones.length > 0) {
                        renderGeometries(parsed.isochrones[0].geometry);
                    } else {
                        console.error("No isochrones found in response");
                    }
                })
                .catch((err) => console.error("Error fetching isochrone data:", err));
        }
    </script>
</body>

</html>

To edit the example code, click Source code and then Edit on Codepen.

Getting started

1. Get an access key

To work with the API of the service, you need to get an access key:

Sign in to the Platform Manager.
Create a demo key or purchase an access key for using API: see the Access keys instruction.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

2. Send a request

To get availability zone data, send a POST request to the /isochrone/2.0.0 endpoint. Follow these steps:

In the request URL, specify the API key value for the key parameter:
```
https://routing.api.2gis.com/isochrone/2.0.0?key=API_KEY
```
In the request body, pass the JSON with the necessary parameters. For example, to get map areas with boundaries that can be reached from the specified point on foot in 10 and 20 minutes, send the following request:
```
{
    "start": {
        "lat": 25.19918,
        "lon": 55.27280
    },
    "durations": [600, 1200],
    "reverse": false,
    "transport": "walking"
}
```

For more information about the parameters, see the API Reference.

Request example:

curl --request POST \
 --url 'https://routing.api.2gis.com/isochrone/2.0.0?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
    "start": {
        "lat": 25.19918,
        "lon": 55.27280
    },
    "durations": [600, 1200],
    "reverse": false,
    "transport": "walking"
}'

Where:

start - coordinates of the point (latitude and longitude) from which availability zones are built.
durations - array of travel times in seconds: 600 seconds (10 minutes) and 1200 seconds (20 minutes). For each time value, a separate availability zone is built.
"reverse": "false" - direction of movement: from the specified point.
transport - transportation type: on foot.

Additionally, you can reverse the direction of movement (moving to the specified point instead of moving from the point), specify the start time and other parameters. For more information, see the examples.

Response example:

The response returns the isochrones array. The array describes two map areas that are reachable in the specified time intervals.

{
    "isochrones": [
        {
            "duration": 1200,
            "geometry": "MULTIPOLYGON(((55.277763 25.18656, 55.278477 25.189979, 55.282996 25.190651, 55.28279 25.192579, 55.287613 25.193904, 55.285362 25.200521, 55.287803 25.202432, 55.28255 25.206211, 55.282098 25.211726, 55.276529 25.210436, 55.272676 25.208233, 55.272785 25.207024, 55.269616 25.206125, 55.264131 25.209113, 55.263638 25.206211, 55.259597 25.202147, 55.261574 25.193331, 55.259327 25.19158, 55.260696 25.190767, 55.260393 25.186572, 55.262335 25.187828, 55.277763 25.18656)))",
            "start_point": {
                "lon": 55.272799993546045,
                "lat": 25.199180003614458
            },
            "attract_points": [
                {
                    "lon": 55.27276451009232,
                    "lat": 25.199191383170145
                }
            ]
        },
        {
            "duration": 600,
            "geometry": "MULTIPOLYGON(((55.272317 25.192301, 55.274676 25.192606, 55.274977 25.194831, 55.277133 25.196457, 55.275809 25.198198, 55.280301 25.198028, 55.278504 25.204305, 55.276614 25.20296, 55.272216 25.203608, 55.269521 25.202421, 55.269521 25.204675, 55.266739 25.20296, 55.267901 25.200521, 55.266394 25.198896, 55.26574 25.193036, 55.272317 25.192301)))",
            "start_point": {
                "lon": 55.272799993546045,
                "lat": 25.199180003614458
            },
            "attract_points": [
                {
                    "lon": 55.27276451009232,
                    "lat": 25.199191383170145
                }
            ]
        }
    ],
    "format": "wkt",
    "transport": "walking",
    "status": "OK",
    "generation_time": 0
}

Where:

isochrones - array with availability zone data:
- duration - travel time in seconds for which the availability zone is calculated.
- geometry - availability zone geometry (Multipolygon) in WKT format.
- start_point - coordinates of the point (latitude and longitude) specified in the request.
- attract_points - coordinates of the attraction point used to build the zone. May differ slightly from the coordinates of the specified point (start_point).
format - geometry format in the response: WKT (Well-known text).
transport - transportation type to build availability zones.
status - request processing status.
generation_time - response generation time in seconds.

For more information about each parameter, see the API Reference.