Isochrone API

Isochrone API allows you to get an area on the map that is reachable from a given point on foot, by car or by bicycle in a given amount of time.

Isochrone API can be used to display a courier delivery area based on delivery time and type of transport.

<!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://routing.api.2gis.com/get_hull?key=Your directions API access key`;
            const start = {
                lat: 55.76259,
                lon: 37.668598,
            };

            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="mode">
                        <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 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 === 'reverse' || evt.target.name === 'mode' || evt.target.name === 'duration') {
                    updateGeometries();
                }
            });
            updateGeometries();

            function updateGeometries() {
                const reverse = reverseSelectEl.value === 'to';
                const mode = modeSelectEl.value;
                const duration = Number(durationSelectEl.value);

                fetch(reqUrl, {
                    method: 'POST',
                    body: JSON.stringify({
                        start,
                        durations: [duration],
                        mode,
                        reverse,
                        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>

Getting an access key

Usage of this API requires an API key. To obtain the key, fill out the form at dev.2gis.com/order.

Request example

To get the coordinates of the reachable area, send a POST request to the /get_hull endpoint. Specify your API key as the key parameter in the query string.

https://routing.api.2gis.com/get_hull?key=API_KEY

Coordinates of the starting point, travel time, movement type and other parameters must be sent as a JSON string in the request body.

For example, to get areas that are reachable on foot within 10 and 20 minutes, you can send a request similar to the following:

curl --request POST \
 --url 'https://routing.api.2gis.com/get_hull?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
    "start": {
        "lat": 55.028268092578884,
        "lon": 82.91853904724123
    },
    "durations": [600, 1200],
    "mode": "walking"
}'

In the example above:

start is the coordinates of the starting point (latitude and longitude),
durations is an array of travel times (600 and 1200 seconds),
mode is the type of movement.

Additionally, you can set the exact time to start the movement, reverse the direction of movement (to move to the starting point instead of moving from the starting point) and specify other parameters. For the full list of supported parameters, see API Reference.

Response example

The response will return the coordinates of areas that are reachable in a given amount of time (geometries). You can find more information about each field in API Reference.

{
    "generation_time": 0.117,
    "geometries": [
        {
            "attract_points": [...],
            "duration": 600,
            "points": [...],
            "start_point": {
                "lat": 55.028268092578884,
                "lon": 82.91853904724123
            },
            "wkt": "LINESTRING(...)"
        },
        {
            "attract_point": [...],
            "duration": 1200,
            "points": [...],
            "start_point": {
                "lat": 55.028268092578884,
                "lon": 82.91853904724123
            },
            "wkt": "LINESTRING(...)"
        }
    ],
    "mode": "walking",
    "status": "OK"
}