Navigation | Truck Directions API | Overview | 2GIS Documentation
Truck Directions API

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:

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.

Usage of this API requires an API key. To obtain the key:

  1. Sign in to the Platform Manager.
  2. 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.

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.

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

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.

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
}

To build the shortest route in distance, even if it is not the fastest one, specify the shortest route type.

{
    "points": [...],
    "type": "truck_shortest"
}

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.

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

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