Route types
Shortest route in time
By default, the server returns the shortest car route in time using current traffic data. To build a specific type of route, set the type
parameter in the request. Сar route using current traffic data.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "jam"
}
Build a route for a specific time
Instead of current traffic data, you can build a route using statistical traffic data. To do this, specify the statistic
route type and the required timestamp as Unix time in the utc
parameter. Car route using statistical traffic data on December 1, 2020, 12 hours UTC.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "statistic",
"utc": 1606826131
}
Shortest route in distance
To build the shortest route in distance, even if it is not optimal due to traffic jams, specify the shortest
route type. Car route ignoring traffic.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "shortest"
}
Public transport lanes
You can also include public transport lanes when building a car route, which can be useful for taxi and bus routes. To do this, add the "taxi_" prefix to the required route type: taxi_jam
, taxi_statistic
, taxi_shortest
.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "taxi_jam"
}
Pedestrian route
To build a pedestrian route, specify the pedestrian
route type.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "pedestrian"
}
Routes inside buildings
To build a pedestrian route inside buildings, specify the parameters "use_indoor": true
and "options": ["pedestrian_instructions"]
. At least one of the starting or ending points must be inside a building or be bound to a building using the object_id
parameter.
You can specify the floor ID for a point using the floor_id
parameter.
{
"points": [
{
"type": "walking",
"x": 82.891385,
"y": 54.983477,
"object_id": "70000001057266023",
"floor_id": "141832716803532"
},
{
"type": "walking",
"x": 82.897328,
"y": 54.980198,
"floor_id": "70030076256452036"
}
],
"type": "pedestrian",
"use_indoor": true,
"options": ["pedestrian_instructions"]
}
The response will include an indoors route based on the floor plans of the buildings, as well as pedestrian navigation instructions: entrances and exits of buildings, movements between floors by elevators, escalators, or stairs.
Bicycle route
To build a bicycle route, specify the bicycle
route type.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "bicycle"
}
By default, bicycle routes include stairways, overground crossings, underground crossings, and car roads. You can exclude them from the route by using the filters
parameter (see Avoiding road types).
Route points
Start and end points
If the starting or ending point of a car route is not located on a road, a path will be added to the route connecting it with the nearest road. You can adjust this by using one of two point types for the start or end point:
walking
- add a pedestrian path avoiding all obstacles such as buildingsstop
- add a simple straight path that ignores all obstacles
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
]
For any type of route, you can set several start and end points, which can be useful, for example, if a building has multiple entrances or exits. When multiple points are specified, only one of them (the most convenient) will be used to build an optimal route.
To separate start and end points in the points
array, you can use the start
parameter or add intermediate points to the route (see the next section).
"points": [
{
"type": "stop",
"x": 82.93057,
"y": 54.943207,
"start": true
},
{
"type": "stop",
"x": 82.93856,
"y": 54.943112,
"start": true
},
{
"type": "stop",
"x": 82.945039,
"y": 55.033879
}
]
Intermediate points
You can add intermediate points to any route by using the pref
point type. The total number of route points must not exceed 10.
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "pref",
"x": 82.941984,
"y": 54.974563
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
]
Avoiding road types
When building a route, you can exclude certain types of roads, such as dirt roads and toll roads (for a car route) or stairways and overground/underground crossings (for a bicycle route). To do this, use the filters
parameter.
For example, to exclude dirt roads from a car route, specify the value "dirt_road":
{
"points": [...],
"filters": ["dirt_road"]
}
To exclude stairways, overground crossings, underground crossings, and car roads from a bicycle route, specify the following array of values:
{
"points": [...],
"type": "bicycle",
"filters": [
"ban_stairway",
"ban_over",
"ban_car_road"
]
}
If the route without the specified road types is too long or impossible to build, parts of the resulting route may still include the excluded road types.
You can also exclude certain types of roads from a pedestrian route. For a complete list of possible values, see API Reference.
Excluding areas
To exclude specific areas from the route, use the exclude
parameter.
Areas can be specified as circles, polygons, or thick lines. To specify an area, use the following parameters:
type
- shape of the area (circle, polygon, or line)points
- coordinates of the areaextent
- area size in meters (radius of a circle, width of a line)
{
"points": [...],
"exclude": [
{
"type": "point",
"points": [
{
"x": 82.03057,
"y": 54.043207
}
],
"extent": 100
},
{
"type": "polyline",
"points": [
{
"x": 82.13057,
"y": 54.143207
},
{
"x": 82.23057,
"y": 54.243207
}
],
"extent": 1000
}
]
}
For each area, you can additionally specify the severity
parameter, which determines how strictly the area should be avoided: if possible (soft
) or always (hard
).
{
"points": [...],
"exclude": [
{
"type": "polygon",
"points": [
{"x": 55.28770929, "y": 25.22069944},
{"x": 55.28976922, "y": 25.25656786},
{"x": 55.33302789, "y": 25.25687836},
{"x": 55.33096795, "y": 25.22007825},
{"x": 55.28770929, "y": 25.22069944}
],
"severity": "hard"
}
]
}