Navigation | Isochrone API | Overview | 2GIS Documentation

Isochrone API

The Isochrone API allows you to get the area on a map that is reachable on foot or by car within a specified time.

It can be used, for example, to display points where a courier can walk or drive from a specified point in 20 minutes.


Requests are made using the POST method, all required parameters should be passed in the JSON format. The responses are also generated in the JSON format.

The request takes the coordinates of the departure point, the travel time from the departure point, and the way of travelling. You will receive the coordinates of the area in the response. All request and response parameters are listed in the API Reference.

Building the area on the map that is reachable from the point of departure

<!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="Several destination points example" />
        <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://catalog.api.2gis.com/get_hull?key=Your directions API access key`;
            const start = {
                lat: 54.97564330524832,
                lon: 82.88566589362209,
            };

            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="mode">
                        <option value="walking">пешком</option>
                        <option value="driving" selected>на авто</option>
                    </select>
                    <select name="duration">
                        <option value="600">5 минут</option>
                        <option value="1200" selected>10 минут</option>
                    </select>
                </div>`;
            new mapgl.Control(map, controlsHtml, {
                position: 'topLeft',
            });

            const modeSelectEl = document.querySelector('select[name="mode"]');
            const durationSelectEl = document.querySelector('select[name="duration"]');

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

            let polyline;
            function renderGeometries(geometries) {
                if (polyline) {
                    polyline.destroy();
                }
                polyline = new mapgl.Polyline(map, {
                    coordinates: geometries.map((item) => [item.lon, item.lat]),
                    width: 2,
                    color: '#00b7ff',
                });
            }
            window.addEventListener('change', (evt) => {
                if (evt.target.name === 'mode' || evt.target.name === 'duration') {
                    updateGeometries();
                }
            });
            updateGeometries();

            function updateGeometries() {
                const mode = modeSelectEl.value;
                const duration = Number(durationSelectEl.value);

                fetch(reqUrl, {
                    method: 'POST',
                    body: JSON.stringify({
                        start,
                        durations: [duration],
                        mode,
                        start_time: new Date().toISOString(),
                    }),
                })
                    .then((res) => res.json())
                    .then((parsed) => renderGeometries(parsed.geometries[0].points))
                    .catch((err) => console.error('error', err));
            }
        </script>
    </body>
</html>

To retrieve the data, make a POST request to https://catalog.api.2gis.com/get_hull?key=YOUR_KEY with Content-Type: application/json.

The request takes the following parameters:

  • key=YOUR_KEY — your API key
{
    "start": {
        "lat": 55.028268092578884,
        "lon": 82.91853904724123
    },
    "durations": [600, 1200],
    "start_time": "2020-04-10T14:07:00Z",
    "mode": "walking"
}
{
    "generation_time": 0.04900002479553223,
    "geometries": [
        {
            "attract_points": [],
            "duration": 600,
            "points": [],
            "start_point": {},
            "wkt": "LINESTRING(...)"
        },
        {
            "attract_point": {},
            "duration": 1200,
            "points": [],
            "start_point": {},
            "wkt": "LINESTRING(...)"
        }
    ],
    "status": "OK"
}
  1. To get your API access key, fill in the application form.
  2. Learn about the request and response formats.