Examples
Examples below explain and illustrate how to use parameters from the API Reference when sending requests to TSP API.
Point parameters
Time windows for visiting a point
Time windows are allowed time intervals for visiting a point. Two types of time windows are available:
-
Hard (default): if the courier does not reach the point within the specified time interval, the point is excluded from the route calculation.
-
Soft: the point is included in the route calculation even if the courier is late. The route is calculated to minimize the total delay time at the points.
For soft time windows, you can set the additional time after the closing of the window: the maximum allowed delay time, after which the point is excluded from the route. If the allowed delay time for all points is set (
soft_time_windows_max_delay), the value for a specific point (max_delay) has a higher priority. If the maximum delay time is not specified, any delay time is allowed when calculating the route.
You can set a time window either for a specific point (the time_windows parameter in the waypoints array) or for all route points at once (options). The time is set in seconds.
If the start time of the courier (start_time) is not specified, it is taken from the current UTC at the time of the request.
For example, set a hard time window for a point and visit it from 15:07 to 17:54:
{
"waypoints": [
{
"waypoint_id": 0,
"point": {
"lat": 54.994814,
"lon": 82.87837
},
"time_windows": [
{
"start": 54420,
"end": 64440
}
]
}
]
}
For example, set a soft time window for all route points with a maximum allowed delay time of two hours:
{
"agents": [...],
"waypoints": [...],
"options": {
"is_soft_time_windows": true,
"soft_time_windows_max_delay": 7200
}
}
Work duration at the point
The length of time that the courier will spend at the point in seconds (for example, to register and pick up cargo).
For example, to stay at a point for 10 minutes:
{
"waypoints": [
{
"waypoint_id": 0,
"point": {
"lat": 54.994814,
"lon": 82.87837
},
"service_time": 600
}
]
}
Point priority
Specify the priority parameter to build a route through the points with the highest priority. Points with low priority can also get into the route if they are close to points with high priority.
The priority parameter is specified in the range from 0 (default value, not a priority point) to 100 (maximum priority):
{
"waypoints": [
{
"waypoint_id": 0,
"point": {
"lat": 54.994814,
"lon": 82.87837
},
"priority": 100
}
]
}
Route parameters
Shortest route in time
By default, the server returns the shortest car route in time using current traffic data. To build a specific type of route, specify the type parameter in the request:
{
"waypoints": [...],
"agents": [...],
"routing_options": {
"type": "jam" // car route using current traffic data
}
}
Instead of current traffic data, you can build a route using statistical traffic data. To do this, specify the statistics route type and the required date and time in RFC 3339 format as the start_time parameter:
{
"waypoints": [...],
"agents": [...],
"routing_options": {
"type": "statistics" // car route using statistical traffic data...
},
"start_time": "2020-05-15T15:52:01Z", // ...as of 15 May 2020, 15:52:01 UTC
}
If the start_time parameter is not used, the time of sending the request is considered to be the starting time of moving along the route.
Example of calculating the order of visiting points considering the current traffic data (on the left) and the statistical traffic data (on the right):
Shortest route in distance
To build the shortest route in distance, even if it is not the fastest one due to traffic jams, specify the shortest route type:
{
"waypoints": [...],
"agents": [...],
"routing_options": {
"type": "shortest"
}
}
Cargo route
To build a cargo route:
-
Specify the
transportparameter with the valuetruck:{ "waypoints": [...], "routing_options": { "transport": "truck" // cargo transport } } -
(Additional) Specify the cargo and transport features using the
truck_paramsparameter. If any feature is not specified, its default value is used:{ "waypoints": [...], "routing_options": { "transport": "truck", "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 } } } -
If the route goes through pass zones where the movement of trucks is limited, you need to do the following steps:
- Get a list of all active passes for trucks: send a GET request to /truck_passes/1.0.0/global
curl --location --request GET 'http://routing.api.2gis.com/truck_passes/1.0.0/global?key=API_KEY' \ --header 'Accept: application/json'All current pass zones and pass IDs are listed in the response.
- Specify the required pass IDs using the
pass_zone_pass_idsparameter when sending a request to TSP API:
{ "waypoints": [...], "routing_options": { "transport": "truck", "pass_zone_pass_ids": [4, 3, 2], } }
Pedestrian route
To build a pedestrian route, specify the transport parameter with the value walking:
{
"waypoints": [...],
"agents": [...],
"routing_options": {
"transport": "walking" // pedestrian route
}
}
Bicycle route
To build a bicycle route, specify the transport parameter with the value bicycle:
{
"waypoints": [...],
"agents": [...],
"routing_options": {
"transport": "bicycle" // bicycle route
}
}
Scooter route
To build a scooter route, specify the transport parameter with the value scooter:
{
"waypoints": [...],
"agents": [...],
"routing_options": {
"transport": "scooter" // scooter route
}
}
Route altitude
To get the altitude information for a pedestrian or bicycle route in the response, specify the need_altitudes parameter with the value true in the request:
{
"waypoints": [...],
"agents": [...],
"routing_options": {
"transport": "walking", //or "transport": "bicycle"
"need_altitudes": true
}
}
Solution file contains a JSON object with the information on a route altitude:
{
"routes": [
{
...
"altitudes_info": {
"elevation_gain": 0,
"elevation_loss": 0,
"max_altitude": 0,
"min_altitude": 0,
"max_road_angle": 0
}
},
...
]
}
Where:
elevation_gain- total elevation gain in cm.elevation_loss- total elevation loss in cm.max_altitude- maximum height above mean sea level in cm.min_altitude- minimum height above mean sea level in cm.max_road_angle- maximum tilt angle.
Calculating the route distance
The JSON file with a solution contains information on the route duration:
{
"routes": [
{
"agent_id": 0,
"points": [0, 2, 1, 4, 5],
"duration": 7366, // courier route duration in seconds
"distance": 76781, // courier route distance in meters
"waypoints": [
{
"waypoint_id": 2,
"duration_waypoint": 2128, // route duration to the point
"distance_to_waypoint": 24718 // route distance to the point
},
...
]
},
...
],
"summary_duration": 8930, // total travel time of all couriers in seconds
"summary_distance": 91823 // total travel distance of all couriers in meters
}
Where:
-
durationanddistance: the travel time and route length for each courier. -
summary_durationandsummary_distance: the total travel time and route length for all couriers. -
duration_waypointanddistance_to_waypoint: the travel time and route length to a specific waypoint.By default, these values are calculated using the traffic data relevant at the start of the route (the
start_timeparameter or the request time if this parameter is not used). To refine the travel time calculation, specify thetravel_time_calculationparameter with the valuefrom_each_pointin the request. In this case, the calculation of travel time to a waypoint will take into account the courier service time at the previous point, the departure time from the previous point, and statistical traffic data for that moment.{ "waypoints": [...], "agents": [...], "travel_time_calculation": "from_each_point" }
Courier parameters
Start and finish points
Start and finish points belong to a special type of points. They are not considered during the route optimization and serve as a warehouse:
- Only
waypoint_idandtime_windowsparameters are taken into account for these points. Parametersdelivery_value,pickup_value, andservice_timeare not considered. - The courier route may end up empty if no other
waypoint_id, besides the start (start_waypoint_id) and finish (finish_waypoint_id) points, were assigned to the courier. The route for this courier may be excluded from the solution file.
The start point (start_waypoint_id) must be specified for each courier. The finish point (finish_waypoint_id) can be left unspecified: in this case, the algorithm chooses the optimal finish point for the current task.
Working hours for a courier
Time during which a courier can visit points.
The time is set in seconds. For example, the courier's working hours are from 14:00 to 15:00:
{
"agents": [
{
"agent_id": 0,
"start_waypoint_id": 1,
"work_time_window": {
"start": 50400,
"end": 54000
}
}
]
}
Cargo delivery
If you need to control how much cargo a courier delivers to or picks up from a point on the route, specify the following parameters:
-
Courier capacity: how much cargo can a courier carry.
For example, the courier capacity is 100 units:
{ "agents": [ { "agent_id": 0, "start_waypoint_id": 1, "capacity": 100 } ] } -
Loading of each point (except of the start and finish ones). The loading type for all points must be the same depending on the task type:
delivery_value: how many cargo units a courier must deliver to the point from the warehouse.pickup_value: how many cargo units a courier must pick up from the point to deliver to the warehouse.
For example, to pick up 50 units of cargo from the point:
{ "waypoints": [ { "waypoint_id": 0, "point": { "lat": 54.994814, "lon": 82.87837 }, "pickup_value": 50 } ] }
If the total pickup_value or delivery_value load of points exceeds the total capacity of couriers, then the request is considered invalid.
Avoiding areas and road types
When building a route, you can avoid certain types of roads, such as toll roads or dirt roads, and avoid specific areas. Avoiding specific areas may impact the order and the possibility of visiting points as well as the total route distance and duration.
To avoid roads of certain types, use the filters parameter, for example:
{
"routing_options": {
"filters": ["toll_roads"] // avoid toll roads
}
}
To avoid a specific area, pass its coordinates and other features using the following parameters in the exclude field:
-
points— coordinates of the excluded area (an array of points):x— degrees of east longitude.y— degrees of north latitude.
-
type— shape of the excluded area:point— a circle with a radius equal toextent(pointsrepresent the center of the circle).polyline— a polyline with a width equal toextent(pointsrepresent the vertices of the line).polygon— a polygon (pointsrepresent the vertices of the polygon).
-
extent— size of the excluded area in meters. -
severity— how strictly to avoid the specified area:soft— avoid if possible.hard— always avoid.
Maximum 25 areas can be excluded.
For example, add a strictly avoidable area of a circle shape to the task example:
{
"routing_options": {
"exclude": [
{
"type": "point",
"severity": "hard",
"extent": 2000, // 2 km
"points": [
{
"y": 25.2073565127789,
"x": 55.27350060436054
}
]
}
]
}
}
Even if the number of points on route does not change after adding the area to avoid, the route distance and duration may change. Pay attention to the summary_duration and summary_distance parameters in the solution file.
For example, a route distance and duration from the task example with no area to avoid:
{
"summary_duration": 8964, // 2.5 hours
"summary_distance": 87718 // 87.7 km
}
And with the area to avoid specified above:
{
"summary_duration": 9552, // 2.5 hours
"summary_distance": 104836 // 104.8 km
}
Excluded points and couriers
If a task cannot be solved with all conditions met, TSP API suggests a route with some points or couriers excluded. To see information about excluded components, send a status check request. The response contains a link to a file with the required information in the url_excluded field.
The file contains a JSON object with excluded points (excluded_waypoints) and couriers (excluded_agents) grouped by reasons. For example:
{
"excluded_waypoints": {
"count_waypoints": 9,
"reasons": [
{
"reason": "route_does_not_exist",
"count": 2,
"waypoints": [16, 18]
},
{
"reason": "failed_time",
"count": 1,
"waypoints": [7]
},
{
"reason": "failed_time_window_for_worktime",
"count": 3,
"waypoints": [5, 10, 12]
},
{
"reason": "failed_pickup_value",
"count": 1,
"waypoints": [8]
},
{
"reason": "failed_delivery_value",
"count": 2,
"waypoints": [2, 13]
}
]
},
"excluded_agents": {
"count_agents": 2,
"reasons": [
{
"reason": "empty_agent",
"count": 2,
"agents": [1, 4]
}
]
}
}
Reasons for excluding a component:
route_does_not_exist— points no routes were built to.failed_time— points that do not fit to couriers work time.failed_time_window_for_worktime— points with time windows no courier can fit.failed_pickup_value— points which pickup value is more than capacity of any courier.failed_delivery_value— points which delivery value is more than capacity of any courier.empty_agent— souriers without points.