Delivery route optimization is one of the most common yet complex logistical challenges. Beyond finding the shortest path, it requires balancing numerous factors, such as time windows, driver breaks, and special handling for goods. Effective route optimization can significantly reduce costs, improve customer satisfaction, lower environmental impact, and scale operations seamlessly.
To tackle these challenges effectively, consider strategies such as leveraging real-time traffic data, grouping nearby deliveries, planning around time constraints, and using dynamic routing to adapt to changes. Additionally, analyzing past delivery data can uncover inefficiencies and improve future planning.
To address these complexities, we designed our Route Planner API to be flexible and powerful, capable of handling even the most demanding delivery optimization scenarios. In this article, we’ll explore practical scenarios and solutions to help you optimize your delivery services effectively.
Playground: Delivery and Pickup Route Planning
We've created a courier route planner playground that generates a delivery optimization task for the visible on the map area. We emulate the following scenario:
Three couriers need to serve 50 locations within 3 hours. At every location, a courier needs to deliver shipments and pick up returns. Each location can have up to 3 items to deliver and up to 2 items to pick up. Items have different pickup and delivery duration times.
The shipments are stored in the Warehouse, the pickup items should be returned to the Warehouse too.
Locations, numbers of items to deliver/pickup, and duration are chosen randomly.
So the generated delivery and pickup route planning task has the following input:
- 1 warehouse
- 3 vehicles with different starting positions
- 50 locations to serve
- a random number of shipments
The solution shows optimized courier routes. You can show/hide separate routes and get hints for each stop by hovering it. Try to generate the task for different visible areas.
How to Use The Route Planner API for Delivery Route Optimization
Optimizing delivery routes effectively with the Route Planner API requires understanding how to map real-world delivery scenarios to API terms. Below, we outline the key concepts and how to set up your tasks using the Route Planner API:
Task Description in Terms of Route Planner API
To effectively use the Route Planner API for optimizing delivery routes, it’s essential to understand how to map your scenario to the API's parameters:
- Agents: Represent the couriers or vehicles whose routes need optimization.
- Mode: Specifies the transportation mode for the agents and can be set to "drive," "truck," "walk," "bicycle," and more.
- Shipments: Define items that need to be picked up from one location and delivered to another.
Representing a Warehouse or Storage Location
There’s no need to explicitly describe a warehouse location within the API. Shipment items already include information on their initial and pickup locations. However, the Delivery Route Planner API includes a locations parameter to create reusable references for frequently used locations, such as a warehouse, allowing you to reference it instead of repeating latitude and longitude coordinates in the shipments input.
Setting Time Windows
The Route Planner API offers several ways to incorporate time windows:
- Agent Time Windows: Define the availability or working hours of an agent, and optionally, add break times.
- Shipment Time Windows: Specify delivery and pickup time frames for each shipment, ensuring time-sensitive deliveries are met.
Transporting Special Goods
The API allows shipment objects to include requirements and agent objects to have capabilities, facilitating the transport of special items:
- Add specific tags, such as "xxx-large," "bulky," or "dangerous," as requirements to a shipment and match them with capabilities in agent objects.
- The system ensures that shipments are only assigned to agents with the corresponding capabilities.
The requirements and capabilities can include any string values, allowing for detailed customization (e.g., "bulky," "hazardous," "custom_code").
Assigning Shipments to Specific Agents
Use the requirements and capabilities parameters to assign a shipment to a specific agent. For instance, you can label an agent with the capability "agentA" and apply the same label as a requirement to a shipment. This feature is particularly helpful when you need to partially recalculate results, such as when adding new shipments or after manual adjustments.
Solve the Delivery Route Optimization Task and Visualize Results
The Delivery Route Planner API works via HTTP POST. So it's cross-platform and can be used with any programming language. Learn more about Route Planner API specification on the API documentation page >>
We've prepared JavaScript code samples for you to help you implement a solution.
Here is a JSFiddle containing the code samples.
Build a Request Object
The Delivery Optimization task input is a JSON object, that contain agents and shipments objects, mode, and optionally locations:
const deliveryOptimizationInput = {
mode: "drive",
agents: [
{
start_location: [9.172755637709471, 48.77966025],
time_windows: [[0, 10800]],
},
{
start_location: [9.175432904901374, 48.7814951],
time_windows: [[0, 10800]],
},
{ start_location: [9.1801828, 48.7821022], time_windows: [[0, 10800]] },
],
shipments: [
{
id: "order_1",
pickup: { location_index: 0, duration: 120 },
delivery: {
location: [9.166594392161663, 48.7714641],
duration: 120,
},
},
...{
id: "order_76",
pickup: { location_index: 0, duration: 120 },
delivery: {
location: [9.18948154795877, 48.7754963],
duration: 300,
},
},
],
locations: [{ id: "warehouse-0", location: [9.1780335, 48.779639] }],
};Call Route Planner API
Make a POST call with "Content-Type=application/json" header:
fetch(`https://api.geoapify.com/v1/routeplanner?apiKey=${myAPIKey}`, {
method: "post",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(deliveryOptimizationInput),
})
.then((res) => res.json())
.then((res) => console.log(res));Analyze Results
The Route Planner API result contains an extended by properties GeoJSON.FeatureCollection object where every feature represents an agent.
The feature properties contain information that describes the agent waypoints and way legs, route time and distance, as well as delivery/pickups actions:
- action - single operations. For example, "pickup item 0", "deliver item 22":
{
"index": 1,
"type": "pickup",
"start_time": 108,
"duration": 120,
"shipment_index": 51,
"shipment_id": "order_52",
"location_index": 0,
"location_id": "warehouse-0",
"waypoint_index": 1
}- waypoints - route stops, required to perform one or multiple actions:
{
"original_location": [
9.165804110078732,
48.78057285
],
"location": [
9.165804,
48.780573
],
"start_time": 2675,
"duration": 120,
"actions": [
{
"index": 21,
"type": "pickup",
"start_time": 2675,
"duration": 120,
"shipment_index": 5,
"shipment_id": "order_6",
"waypoint_index": 2
}
],
"prev_leg_index": 1,
"next_leg_index": 2
}- legs - routes between waypoints:
{
"time": 167,
"distance": 1509,
"from_waypoint_index": 1,
"to_waypoint_index": 2,
"steps": [
{
"from_index": 0,
"to_index": 1,
"time": 167,
"distance": 1509
}
]
}Besides, the FeatureCollection object is enriched by the "properties" object, that contains the input parameters and may contain issues that appeared by solving the task - unassigned agents and unassigned shipments.
Visualize The Results With MapLibre GL (an open-source fork of Mapbox GL)
Here is a JSFiddle that shows how to visualize the results with MapLibre GL map library:
What's next
- Learn more about Route Planner API >>
- Learn about optimizing bus routes with Route Planner API *Learn how to optimize routes and schedules for workers
- Try more optimization scenarios on the Playground page >>
- Check the Route Planner API specification >>
