Truck Directions API

Truck Directions API is deprected. Use Routing API to build 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.

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

To start using navigation services, get an access key for Routing API:

Sign in to the Platform Manager.
Create a demo key or purchase an access key for using API: see the Access keys instruction.
See the Routing API documentation to start using the service.

To work with access keys, you can use the Platform Manager: see the Platform Manager section.

Request example

Note

Examples below are for the deprecated Truck Directions API. If you have switched to Routing API, refer to the corresponding documentation.

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