Navigation | Truck Directions API | Overview | 2GIS Documentation

Truck Directions API

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

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, fill out the form at dev.2gis.com/order.

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://catalog.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://catalog.api.2gis.com/truck/6.0.0/global?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
   "points": [
       {
           "type": "pedo",
           "x": 82.93057,
           "y": 54.943207
       },
       {
           "type": "pedo",
           "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": "pedo",
                "x": 82.93057,
                "y": 54.943207
            },
            {
                "type": "pedo",
                "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 optimal due to traffic jams, specify the shortest route type.

{
    "points": [...],
    "type": "truck_shortest" // truck route ignoring traffic
}

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.