Overview
Truck Directions API is only available in particular deployment options.
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.
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.
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"
}
]
}
Deployment options
- Cloud-based: Truck Directions API methods are not available. To build routes and get truck pass zones, use Routing API.
- On-Premise: Truck Directions API is used as a utility service required for the operation of other navigation APIs in a private network and not intended for standalone use. For more information, see the API Platform for server.
Methods labeled as deprecated are not supported in any deployment options.