HERE Tour Planning API in a Nutshell
Last-mile is often the most complex and expensive part of supply chain. It is crucial to create a route plan that can incorporate real-world constraints like – vehicle capacity, delivery time windows, multiple warehouses, pickups and deliveries, driver shifts, truck attributes, etc. Considering all these input parameters, the HERE Tour Planning API returns a cost-effective sequence to visit all the stops in your daily plan. The Tour Planning API is often integrated into an existing Transport Management System to optimize the trips. In this post, we will explore why you should use the API, understand its input parameters and the solution.
Why use HERE Tour Planning API?
- The first and foremost reason to use HERE Tour Planning API is that it allows for full-fleet optimization. You can create cost-optimized or time-optimized tours for all vehicles in a fleet. It can provide routes for the lowest cost by balancing routes and number of vehicles used.
- Routes can be optimized based on constraints like driver shifts or like certain jobs can only be completed at certain times.
- It provides live traffic-aware, truck-based route optimization.
- Replan new jobs in real-time using the vehicle’s current location.
- Match job constraints to vehicle types, for example, using trucks with refrigerators.
Understanding the parameters in the Problem
Defining the Vehicle Routing Problem is the most extensive aspect of tour planning. The problem can be divided into two main parts: Plan and Fleet.
Plan includes the “jobs” part, where the job location, duration, priority, delivery/pickup time window, demand (i.e. free form value for space needed on the vehicle) and many more specific parameters can be specified. Additionally, plan includes the limit on total number of jobs, sequence between the jobs, if the jobs can be clustered by geographic areas, etc.
Fleet specifies vehicle types and their routing profiles. It can just be one vehicle or combination of different types of vehicles. Each vehicle type needs a unique identifier, predefined costs to use the vehicle, size capacity, time shifts, start and end location, if the vehicle has any specialties (like has refrigeration), max distance it can cover and so forth. Routing profile includes the type (like car, truck, scooter, bicycle, pedestrian), departing time, features to avoid. You can also specify if the plan should include live or historic traffic information. This is super helpful as the ETAs for deliveries would significantly vary depending on the time of the day.
Checkout the API reference that dives deeper into each of these properties.
An example of a Problem:
The API request for Tour Planning is:
POST <a href="https://tourplanning.hereapi.com/v3/problems?apiKey=YOUR_API_KEY">https://tourplanning.hereapi.com/v3/problems?apiKey=YOUR_API_KEY</a>
I will use Postman to create this request. If you would like to get started with Postman, you can follow this post.
In the body of the request, we will have information about the jobs and the fleet. I will create 3 jobs in this example – two deliveries at Los Angeles County Museum and Griffith Observatory, and one pickup from The Getty Center. Let’s say, the pickup needs to happen between 10am and 12pm, and deliveries between 10am to 2pm. Each package has a demand of 1, which we can consider as 1 box size here. I have one car to complete these jobs, and capacity of the car is 10, i.e., 10 boxes in this case. Let’s have the same start and end location for the trip – Echo Park in Los Angeles. The request looks like:
{
"plan": {
"jobs": [
{
"id": "A",
"tasks": {
"deliveries": [
{
"places": [
{
"location": {
"lat": 34.118384,
"lng": -118.299579
},
"times": [
[
"2022-10-15T10:00:00.000Z",
"2022-10-15T14:00:00.000Z"
]
],
"duration": 580
}
],
"demand": [
1
]
}
]
}
},
{
"id": "B",
"tasks": {
"deliveries": [
{
"places": [
{
"location": {
"lat": 34.064221,
"lng": -118.359209
},
"times": [
[
"2022-10-15T10:00:00.000Z",
"2022-10-15T14:00:00.000Z"
]
],
"duration": 1020
}
],
"demand": [
1
]
}
]
}
},
{
"id": "C",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 34.078462,
"lng": -118.474428
},
"times": [
[
"2022-10-15T10:00:00.000Z",
"2022-10-15T12:00:00.000Z"
]
],
"duration": 700
}
],
"demand": [
1
]
}
]
}
}
]
},
"fleet": {
"types": [
{
"id": "car_profile",
"profile": "car_1",
"costs": {
"fixed": 5.0,
"distance": 0.07,
"time": 0
},
"shifts": [
{
"start": {
"time": "2022-10-15T09:00:00Z",
"location": {
"lat": 34.074295,
"lng": -118.259175
}
},
"end": {
"time": "2022-10-15T18:00:00Z",
"location": {
"lat": 34.074295,
"lng": -118.259175
}
}
}
],
"capacity": [
10
],
"amount": 1
}
],
"profiles": [
{
"type": "car",
"name": "car_1"
}
]
}
}
Understanding the Solution
The Solution of Vehicle Routing Problem consists of 3 major parts: statistic, tours, and unassigned jobs.
- Statistics includes the total stats for all tours. It has the total cost, distance driven (meters), duration (seconds) as well as the breakdown of time spend in driving vs time spend serving jobs, or taking breaks.
- Tours section will have the sequence of our stops. For our example, we will do the two deliveries first and still make it in time for pickup from The Getty Center before noon. This solution also takes into account the traffic, loading/unloading time at the location.
- Unassigned Jobs – If, for any of the assigned constraints, the job could not be accommodated in this tour, the unassigned jobs list is where you can find it.
An example of a Solution:
{
"statistic": {
"cost": 5090.290000000001,
"distance": 72647,
"duration": 7669,
"times": {
"driving": 5369,
"serving": 2300,
"waiting": 0,
"break": 0
}
},
"tours": [
{
"vehicleId": "car_profile_1",
"typeId": "car_profile",
"stops": [
{
"location": {
"lat": 34.074295,
"lng": -118.259175
},
"time": {
"arrival": "2022-10-15T09:00:00Z",
"departure": "2022-10-15T09:44:01Z"
},
"load": [
2
],
"activities": [
{
"jobId": "departure",
"type": "departure"
}
]
},
{
"location": {
"lat": 34.118384,
"lng": -118.299579
},
"time": {
"arrival": "2022-10-15T10:00:00Z",
"departure": "2022-10-15T10:09:40Z"
},
"load": [
1
],
"activities": [
{
"jobId": "A",
"type": "delivery"
}
]
},
{
"location": {
"lat": 34.064221,
"lng": -118.359209
},
"time": {
"arrival": "2022-10-15T10:31:40Z",
"departure": "2022-10-15T10:48:40Z"
},
"load": [
0
],
"activities": [
{
"jobId": "B",
"type": "delivery"
}
]
},
{
"location": {
"lat": 34.078462,
"lng": -118.474428
},
"time": {
"arrival": "2022-10-15T11:12:51Z",
"departure": "2022-10-15T11:24:31Z"
},
"load": [
1
],
"activities": [
{
"jobId": "C",
"type": "pickup"
}
]
},
{
"location": {
"lat": 34.074295,
"lng": -118.259175
},
"time": {
"arrival": "2022-10-15T11:51:50Z",
"departure": "2022-10-15T11:51:50Z"
},
"load": [
0
],
"activities": [
{
"jobId": "arrival",
"type": "arrival"
}
]
}
],
"statistic": {
"cost": 5090.290000000001,
"distance": 72647,
"duration": 7669,
"times": {
"driving": 5369,
"serving": 2300,
"waiting": 0,
"break": 0
}
},
"shiftIndex": 0
}
]
}
Conclusion
If you are just starting with Tour Planning API, the problem and solution can feel overwhelming. But start with the building blocks like plan and fleet, and just fill in the specifics from there. You can master this sooner than you think. HERE Tour Planning is included with the platform base plan. You can contact us to request either an evaluation or a usage license. Learn more about HERE's Tour Planning API with the Developer Guide, Tutorials and product details.
Have your say
Sign up for our newsletter
Why sign up:
- Latest offers and discounts
- Tailored content delivered weekly
- Exclusive events
- One click to unsubscribe