Directions API
Try Routing API to plot car, truck, bicycle, or pedestrian routes through one service.
Directions API allows you to build a route from point A to point B.
Directions API supports the following types of routes:
- a fastest car route considering current or statistical traffic data
- a shortest car route in distance
- a car route avoiding certain types of roads, like toll roads or dirt roads
- a car route that includes public transport lanes (a taxi route)
- a pedestrian route including crosswalks and avoiding obstacles
- a pedestrian route inside buildings with floor plans
- a bicycle route including pedestrian crossings and optionally avoiding stairways, overpasses, underpasses, and highways
- a route with intermediate points (up to 10, including start and end point)
For each route, Directions API can additionally return the following information:
- altitude information (height above sea level and elevation changes)
- information about special points on the route (for example, start of a toll road)
To build a route for a truck, use Truck Directions API.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>2GIS Navi API</title>
<meta name="description" content="Navi API directions example" />
<style>
html,
body,
#container {
margin: 0;
width: 100%;
height: 100%;
overflow: hidden;
}
#reset {
padding: 4px 10px;
background: #00a81f;
border-radius: 4px;
box-shadow: 0 1px 3px 0 rgba(38, 38, 38, 0.5);
border: none;
color: #fff;
font-size: 13px;
cursor: pointer;
}
#reset:disabled {
background: #f2f2f2;
color: #6e6d6d;
cursor: default;
}
</style>
</head>
<body>
<div id="container"></div>
<script src="https://mapgl.2gis.com/api/js/v1"></script>
<script src="https://unpkg.com/@2gis/mapgl-directions@^2/dist/directions.js"></script>
<script>
const map = new mapgl.Map('container', {
center: [37.668598, 55.76259],
zoom: 13,
key: 'Your API access key',
});
const directions = new mapgl.Directions(map, {
// This key can be used for demo purpose only!
// You can get your own key on http://partner.api.2gis.ru/
directionsApiKey: 'Your directions API access key',
});
const markers = [];
let firstPoint;
let secondPoint;
// A current selecting point
let selecting = 'a';
const buttonText = ['Choose two points on the map', 'Reset points'];
const controlsHtml = `<button id="reset" disabled>${buttonText[0]}</button> `;
new mapgl.Control(map, controlsHtml, {
position: 'topLeft',
});
const resetButton = document.getElementById('reset');
resetButton.addEventListener('click', function() {
selecting = 'a';
firstPoint = undefined;
secondPoint = undefined;
directions.clear();
this.disabled = true;
this.textContent = buttonText[0];
});
map.on('click', (e) => {
const coords = e.lngLat;
if (selecting != 'end') {
// Just to visualize selected points, before the route is done
markers.push(
new mapgl.Marker(map, {
coordinates: coords,
icon: 'https://docs.2gis.com/img/dotMarker.svg',
}),
);
}
if (selecting === 'a') {
firstPoint = coords;
selecting = 'b';
} else if (selecting === 'b') {
secondPoint = coords;
selecting = 'end';
}
// If all points are selected — we can draw the route
if (firstPoint && secondPoint) {
directions.carRoute({
points: [firstPoint, secondPoint],
});
markers.forEach((m) => {
m.destroy();
});
resetButton.disabled = false;
resetButton.textContent = buttonText[1];
}
});
</script>
</body>
</html>
You can also work with Directions API in the playground.
Getting 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: see the Platform Manager section.
Request example
To calculate a route, send a POST request to the /carrouting/6.0.0/global
endpoint. Specify your API key as the key
parameter in the query string.
https://routing.api.2gis.com/carrouting/6.0.0/global?key=API_KEY
Coordinates for the route and other parameters must be sent as a JSON string in the request body.
For example, to build a car route from point A to point B considering the current traffic condition, you can send a request similar to the following:
curl --request POST \
--url 'https://routing.api.2gis.com/carrouting/6.0.0/global?key=API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"locale": "en",
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
]
}'
The points
parameter is an array of route points (x
is the longitude of a point; y
is the latitude of a point). The first element of the array is the starting point.
Response example
The response will return an object containing the information about the calculated route: route length in meters (total_distance
), travel time in seconds (total_duration
), a list of maneuvers (maneuvers
), and other fields. You can find information about each field in API Reference.
{
"query": {
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
]
},
"result": [
{
"algorithm": "with traffic jams",
"begin_pedestrian_path": {...},
"end_pedestrian_path": {...},
"filter_road_types": [...],
"id": "1805336109018823561",
"maneuvers": [...],
"route_id": "...",
"total_distance": 15153,
"total_duration": 2204,
"type": "carrouting",
"ui_total_distance": {},
"ui_total_duration": "36 min",
"waypoints": [...]
}
],
"type": "result"
}