TMS Optimizer Contract
Overview
The Delivery Route Optimizer API is designed to compute optimal delivery routes based on various constraints such as time, cost, vehicle capacity, and priority. This document provides details on the payload structure required for route optimization.
Payload Structure
Root Object
{
"config": {
"costMetric": "time",
"routingProfile": "<string>",
"timeLimitInSeconds": "<integer>",
"planner": "<string>",
"exclusiveZones": { "in_288": -35535206.977762625 },
"timePenalty": { "base": "<number>", "factor": "<number>" },
"sizeDimPenalties": [
{ "base": "<number>", "factor": "<number>" },
{ "base": "<number>", "factor": "<number>" }
],
"solutionTraits": {
"clustered": false,
"clusterBias": 0.5,
"pitstops": { "threshold": 0, "maxSize": 0 },
"ignoreLastLeg": false,
"oneway": false,
"allowMultiTrip": false,
"softExclusiveZones": false,
"allPicksAfterDrops": false
}
},
"locations": [ ... ],
"vehicleTypes": [ ... ],
"tasks": [ ... ],
"tags": [ "<string>", "<string>" ],
"providedTaskPlans": [ ... ]
}
Fields
config
- Type:
object - Description: Configuration settings for route optimization.
costMetric(string): Defines the cost metric for optimization (e.g.,time,distance).routingProfile(string): Specifies the routing profile used for optimization.timeLimitInSeconds(integer): The time limit for optimization.planner(string): Specifies the optimization planner to use.exclusiveZones(object): Defines geographical zones that should be avoided.timePenalty(object): Specifies penalties based on time.sizeDimPenalties(array): Specifies penalties based on size dimensions.solutionTraits(object): Additional configuration options for solution tuning.
locations
- Type:
array - Description: A list of locations with unique identifiers and coordinates.
vehicleTypes
- Type:
array - Description: A list of vehicle types with constraints.
id(string): Unique identifier for the vehicle type.startLocationId(string): The starting location ID for the vehicle.endLocationId(string): The ending location ID for the vehicle.fixedCost(number): Fixed cost of operating this vehicle.activeWindows(array): Available operation time windows.speedFactor(number): Speed multiplier for the vehicle.waitingCostPerUnitTime(number): Cost per unit of time while waiting.baseTaskServiceTime(number): Base time required to service a task.capacity(array): The capacity limits of the vehicle.maxDistance(number): Maximum distance the vehicle can travel.count(integer): Number of vehicles of this type available.refillTime(integer): Time required for refilling/restocking.
Sample Vehicle Type:
{
"id": "82725",
"startLocationId": "0",
"endLocationId": "0",
"fixedCost": 120000,
"activeWindows": [[0, 23400]],
"speedFactor": 6.777777777777777,
"waitingCostPerUnitTime": 0.15,
"baseTaskServiceTime": 0,
"capacity": [9600000, 4150, 35, 350],
"maxDistance": 4294967296,
"count": 1,
"refillTime": 0
}
tasks
- Type:
array - Description: A list of delivery tasks with pickup and drop-off constraints.
id(string): Unique identifier for the task.group(string, optional): Task group for categorization.pickupLocationId(string): Location ID for pickup.dropLocationId(string): Location ID for drop-off.pickupWindows(array): Allowed pickup time windows.dropWindows(array): Allowed drop-off time windows.demand(array): Resource demand for the task.serviceCost(number): Cost associated with servicing the task.serviceTime(number): Time required to complete the task.priority(integer): Priority level of the task.noPlanPenalty(number): Penalty applied if the task is not planned.compatibleVehicleTypeIds(array): List of vehicle types compatible with this task.fixed(boolean): Whether the task assignment is fixed.
Sample Task:
{
"id": "123712135",
"pickupLocationId": "0",
"dropLocationId": "1",
"pickupWindows": [],
"dropWindows": [],
"demand": [1730577.6992361129, 595.702005654761, 1, 1],
"serviceCost": 4584,
"serviceTime": 4584,
"priority": 2,
"noPlanPenalty": 1000000000,
"compatibleVehicleTypeIds": null
}
tags
- Type:
array - Description: Tags for categorization.
providedTaskPlans
- Type:
array - Description: Pre-defined plans for specific tasks.
Usage Example
{
"config": {
"costMetric": "time",
"routingProfile": "fastest",
"timeLimitInSeconds": 3600,
"planner": "default"
},
"locations": [{ "id": "loc1", "lat": 37.7749, "lng": -122.4194 }],
"vehicleTypes": [
{
"id": "truck1",
"startLocationId": "loc1",
"endLocationId": "loc1",
"capacity": [1000, 2000]
}
],
"tasks": [
{
"id": "task1",
"pickupLocationId": "loc1",
"dropLocationId": "loc1",
"demand": [500, 1000]
}
]
}
Sample input and its response(more comprehensive)
input
{
"costMetric": "time",
"routingProfile": "distance",
"timeLimitInSeconds": 3600,
"planner": "jvrp",
"solutionTraits": {
"clustered": true,
"clusterBias": 100,
"ignoreLastLeg": true,
"oneway": false,
"allowMultiTrip": false,
"softExclusiveZones": false,
"allPicksAfterDrops": false
},
"locations": [
{
"id": "l1",
"lat": 12.1716,
"lng": 77.1946
},
{
"id": "l2",
"lat": 12.5716,
"lng": 77.5946
},
{
"id": "l3",
"lat": 12.9716,
"lng": 77.9946
}
],
"vehicleTypes": [
{
"id": "v1",
"startLocationId": "l1",
"endLocationId": "l1",
"capacity": [1200, 1100, 5000],
"maxDistance": 300000
},
{
"id": "v2",
"startLocationId": "l1",
"endLocationId": "l1",
"capacity": [800, 700, 3000],
"maxDistance": 250000
},
{
"id": "v3",
"startLocationId": "l1",
"endLocationId": "l1",
"capacity": [1500, 2000, 6000],
"maxDistance": 200000
}
],
"tasks": [
{
"id": "t1",
"pickupLocationId": "l1",
"dropLocationId": "l2",
"demand": [600, 0.3, 20]
},
{
"id": "t2",
"pickupLocationId": "l1",
"dropLocationId": "l3",
"demand": [700, 0.2, 15]
},
{
"id": "t3",
"pickupLocationId": "l1",
"dropLocationId": "l2",
"demand": [500, 0.25, 10]
},
{
"id": "t4",
"pickupLocationId": "l1",
"dropLocationId": "l3",
"demand": [550, 0.22, 12]
}
]
}
response
{
...rest of the input fields,
"id": "KTBSYQQWZ38Q8EW40BQUCMO0KY88O9JBDGMXJYZU",
"state": "SOLVED",
"tasks": [
{
"id": "t1",
"pickupLocationId": "l1",
"dropLocationId": "l2",
"demand": [600, 0.3, 20],
"priority": 1
},
{
"id": "t2",
"pickupLocationId": "l1",
"dropLocationId": "l3",
"demand": [700, 0.2, 15],
"priority": 1
},
{
"id": "t3",
"pickupLocationId": "l1",
"dropLocationId": "l2",
"demand": [500, 0.25, 10],
"priority": 1
},
{
"id": "t4",
"pickupLocationId": "l1",
"dropLocationId": "l3",
"demand": [550, 0.22, 12],
"priority": 1
}
],
"vehicleTypes": [
{
"id": "v1",
"startLocationId": "l1",
"endLocationId": "l1",
"capacity": [1200, 1100, 5000],
"maxDistance": 300000,
"fixedCost": 0,
"speedFactor": 1,
"waitingCostPerUnitTime": 0,
"baseTaskServiceTime": 0,
"count": 0,
"refillTime": 2400
},
{
"id": "v2",
"startLocationId": "l1",
"endLocationId": "l1",
"capacity": [800, 700, 3000],
"maxDistance": 250000,
"fixedCost": 0,
"speedFactor": 1,
"waitingCostPerUnitTime": 0,
"baseTaskServiceTime": 0,
"count": 0,
"refillTime": 2400
},
{
"id": "v3",
"startLocationId": "l1",
"endLocationId": "l1",
"capacity": [1500, 2000, 6000],
"maxDistance": 200000,
"fixedCost": 0,
"speedFactor": 1,
"waitingCostPerUnitTime": 0,
"baseTaskServiceTime": 0,
"count": 0,
"refillTime": 2400
}
],
"executionId": "projects/589746226377/locations/asia-southeast1/workflows/darwin-runner/executions/82960ce3-9f61-42a3-918f-81bfd5092f38",
"createdAt": "2025-03-21T07:01:21.497Z",
"completedAt": "2025-03-21T07:01:57.355Z",
"progress": 1,
"taskPlans": [
{
"taskId": "t3",
"vehicleIndex": 0,
"vehicleTypeId": "v1",
"pickupSequence": 0,
"dropSequence": 1,
"tripIndex": 0
},
{
"taskId": "t1",
"vehicleIndex": 1,
"vehicleTypeId": "v1",
"pickupSequence": 0,
"dropSequence": 1,
"tripIndex": 0
}
]
}
Conclusion
This documentation provides a structured approach for using the Delivery Route Optimizer API. For any additional queries, refer to the API reference or contact support.