Truck Directions API
Try Routing API to plot car, truck, bicycle, or pedestrian routes through one service.
Truck Directions API allows you to build a truck route, excluding roads with current restrictions for trucks.
Truck Directions API takes into account:
- size and mass of the vehicle
- maximum permitted mass on the route
- restrictions on traffic with dangerous and explosive cargo
- restrictions by signs "No goods vehicles" and "No vehicles" in combination with plates "Vehicle type", "Restriction of maximum gross weight" (2.5 tonnes) and "Direction of action"
- current traffic jams or traffic jam statistics
- dirt and toll roads, offering an option to avoid such roads
For each route, Truck 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)
The list of regions where it is possible to build routes for trucks is gradually being expanded with new cities.
The video below shows an example of a truck route that takes into account the restrictions on the size of a vehicle.
The video below shows an example of a truck route that avoids roads where trucks are prohibited.
Getting an access key
Usage of this API requires an API key. To obtain the key:
- Sign in to the Platform Manager.
- Create a demo key (if you have not used Urbi products before) or request a production key: follow the link to contact a manager on the API Keys tab.
In the Platform Manager, you can also:
- See information on your current keys: which services are enabled, which limit is set for each, when a key will be deactivated, and more.
- Set restrictions for a key by HTTP headers or by IP and subnet.
- Check the statistics of request distribution for each key.
Request example
To calculate a route, send a POST request to the /truck/6.0.0/global
endpoint. Specify your API key as the key
parameter in the query string.
https://routing.api.2gis.com/truck/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 truck 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/truck/6.0.0/global?key=API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "truck_jam",
"locale": "en"
}'
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
}
],
"type": "truck_jam"
},
"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": "truckrouting",
"ui_total_distance": {},
"ui_total_duration": "36 min",
"waypoints": [...]
}
],
"type": "result"
}
Cargo parameters
To build a truck route taking into account road restrictions, you need to specify the characteristics of the cargo as the truck_params
parameter. If any characteristic is not specified, the default value will be used.
{
"points": [...],
"truck_params": {
"max_perm_mass": 10,
"mass": 9,
"axle_load": 4,
"height": 3.2,
"width": 2.5,
"length": 7,
"dangerous_cargo": true,
"explosive_cargo": true
}
}
For a full list of characteristics and their default values, see API Reference.
Route types
Shortest route in time
By default, the server returns the shortest truck route in time using current traffic data. To build a specific type of route, set the type
parameter in the request.
{
"points": [...],
"type": "truck_jam" // truck route using current traffic data
}
Instead of current traffic data, you can build a route using statistical traffic data. To do this, specify the truck_statistic
route type and the required timestamp as Unix time in the utc
parameter.
{
"points": [...],
"type": "truck_statistic", // truck route using statistical traffic data...
"utc": 1606826131 // ...as of 1 December 2020, 12:00 UTC
}
Shortest route in distance
To build the shortest route in distance, even if it is not the fastest one, specify the shortest
route type.
{
"points": [...],
"type": "truck_shortest"
}
Avoiding road types
When building a route, you can exclude certain types of roads, such as toll roads or dirt roads. To do this, use the filters
parameter.
{
"points": [...],
"filters": ["dirt_road"] // exclude dirt roads from the route
}
The list of possible values for the filters
parameter can be found in API Reference.
Altitude information
To get altitude information, specify the need_altitudes
parameter.
{
"points": [...],
"need_altitudes": true
}
If this parameter is specified, the response will contain the following information:
- Total elevation gain and loss (in centimeters).
- Maximum and minimum altitude on the route (height above sea level in centimeters).
- Maximum elevation angle on the route.
- Elevation angle and altitude for each segment of the route.
{
"altitudes_info": {
"elevation_gain": 12440,
"elevation_loss": 11020,
"max_altitude": 10700,
"min_altitude": 6600,
"max_road_angle": 8
},
"geometry": [
{
// Elevation angle.
"angles": "LINESTRING(1, -1)",
"color": "ignore",
"length": 22,
// Third value is the altitude.
"selection": "LINESTRING(82.930722 54.943655 9200, 82.930815 54.943650 9220, 82.930926 54.943640 9190)",
"style": "normal"
}
]
}
Special points
In some cases, the route may contain special types of points, which will be listed in the route_points
field. For example, if the route includes a toll road segment, route_points
will contain information about the starting and ending points of that segment.
{
"route_points": [
{
// Point coordinates.
"coordinates": {
"lat": 55.73942822546596,
"lon": 37.37259908712576
},
// Distance from the start of the route (in meters).
"distance": 746,
// Special point type.
"type": "TollRoadBegin"
},
{
"coordinates": {
"lat": 55.71525675255834,
"lon": 37.31850882892307
},
"distance": 5784,
"type": "TollRoadEnd"
}
]
}