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"
}
]
}