Response Structure
In this article, we present the structure of the Planning API response based on an example: the optimization of a delivery route with one distribution center (CD), two customers (Cliente1 and Cliente2), and one vehicle of the VUC type. The vehicle leaves the CD, loads both operations, delivers first to Cliente1, then to Cliente2, and returns to the CD.
For more details about this example, see Example 1 – Operations with a single vehicle.
The response contains the sequence of activities for each route (loading, driving, and deliveries), with time windows, distances, and durations, as well as consolidated indicators for the solution.
Request
The request below was used to generate the response in this example. The request fields are described in detail in a dedicated article.
{
"optimizationProfile": "BRAZIL46",
"startDate": 1513750219000,
"legislationProfiles": [
{
"name": "DEFAULT"
}
],
"logisticConstraints": [
{
"name": "DEFAULT",
"siteLoadingFixedTime": 900,
"siteUnloadingFixedTime": 600
}
],
"products": [
{
"name": "DEFAULT"
}
],
"sites": [
{
"name": "Cliente1",
"coordinates": {
"latitude": -23.507608,
"longitude": -46.587145
},
"logisticConstraints": "DEFAULT"
},
{
"name": "Cliente2",
"coordinates": {
"latitude": -23.621059,
"longitude": -46.756193
},
"logisticConstraints": "DEFAULT"
}
],
"depots": [
{
"name": "CD",
"coordinates": {
"latitude": -23.503939,
"longitude": -46.498419
},
"logisticConstraints": "DEFAULT"
}
],
"vehicleTypes": [
{
"name": "VUC",
"maxVolume": 20,
"maxWeight": 1200,
"size": 1
}
],
"vehicles": [
{
"name": "VUC_1",
"vehicleType": "VUC",
"legislationProfile": "DEFAULT",
"availablePeriods": [
{
"departureSite": "CD",
"arrivalSite": "CD",
"timeWindow": {
"start": 1513753200000,
"end": 1513796400000
}
}
]
}
],
"operations": [
{
"id": "P1",
"weight": 100,
"volume": 2,
"product": "DEFAULT",
"type": "DELIVERY",
"depotSite": "CD",
"customerSite": "Cliente1",
"customerTimeWindows": [
{
"start": 1513756800000,
"end": 1513771200000
}
]
},
{
"id": "P2",
"weight": 250,
"volume": 5,
"product": "DEFAULT",
"type": "DELIVERY",
"depotSite": "CD",
"customerSite": "Cliente2",
"customerTimeWindows": [
{
"start": 1513756800000,
"end": 1513771200000
}
]
}
]
}
Response
The response consists of the fields below. The vehicleRoutes and indicators fields are described in detail in the following sections. Some fields are returned only in specific situations, such as when there are rejected operations or when certain parameters are sent in the request. They are described in the “Fields returned only…” sections.
id– Unique identifier of the generated solution;clientId– Identifier of the client that made the request;vehicleRoutes– List of the routes calculated for each vehicle;indicators– Consolidated indicators for the solution.
The vehicleRoutes field
Each item in the list represents a vehicle and the routes it performs in its available period.
vehicle– Vehicle name;period– Availability period of the vehicle used in the solution:timeWindow– Time window of the period, withstartandend(timestamp in milliseconds);departureSite– Vehicle departure site;arrivalSite– Vehicle arrival site;maxRoutesNumber– Maximum number of routes for the vehicle in the period. Returned only when informed in the request.
routes– List of the vehicle’s routes:id– Route identifier;activities– Ordered list of the route’s activities:activity– Activity type. The possible values are:ROUTE_START– Start of the route;LOADING– Loading at the depot;DRIVING– Travel between two sites;DELIVERY– Delivery to the customer;COLLECTION– Collection from the customer;UNLOADING– Unloading;WAITING– Waiting;PAUSE– Pause;REST– Rest;ROUTE_END– End of the route.
type– Activity classification:SITEfor activities performed at a site andDRIVINGfor travel;timeWindow– Time window in which the activity takes place, withstartandend(timestamp in milliseconds);operations– List with theidof the operations handled in the activity. It is empty in activities such asROUTE_START,DRIVING, andROUTE_END;site– Site where the activity is performed. Returned inSITEtype activities;fixedTimeSite– Fixed service time at the site, in seconds. Returned inLOADING,UNLOADING,COLLECTION, andDELIVERYactivities;volume– Volume of the operations handled in the activity. Returned inLOADING,UNLOADING,COLLECTION, andDELIVERYactivities;weight– Weight of the operations handled in the activity. Returned inLOADING,UNLOADING,COLLECTION, andDELIVERYactivities;departureSite– Origin site of the trip. Returned inDRIVING;arrivalSite– Destination site of the trip. Returned inDRIVING;distance– Distance traveled in the trip, in meters. Returned inDRIVING;nominalDuration– Nominal duration of the trip, in seconds. Returned inDRIVING.
In the example, the route of vehicle VUC_1 follows this sequence of activities: ROUTE_START at the CD, LOADING of operations P2 and P1, DRIVING to Cliente1, DELIVERY of operation P1, DRIVING to Cliente2, DELIVERY of operation P2, DRIVING back to the CD, and ROUTE_END.
The indicators field
Consolidated indicators for the entire solution. All times are returned in seconds and distance in meters.
routesNumber– Number of routes in the solution;rejectOperationsNumber– Number of rejected operations, that is, operations not served by the solution;timeWindowNumber– Number of time windows considered in the solution;totalDistance– Total distance traveled;totalTime– Total time of the routes;totalWorkingTime– Total working time:dayWorkingTotalTime– Working time during the day period;nightWorkingTotalTime– Working time during the night period.
totalDrivingTime– Total driving time;totalServiceTime– Total service time at the sites:totalLoadingTime– Total loading time;totalDeliveringTime– Total delivery time;totalUnloadingTime– Total unloading time;totalCollectingTime– Total collection time.
totalWaitingTime– Total waiting time;totalRestTime– Total rest time;averageOccupancyRateVolume– Average vehicle occupancy rate by volume, as a percentage;averageOccupancyRateWeight– Average vehicle occupancy rate by weight, as a percentage.
Fields returned only when there are rejected operations
When the solver cannot serve one or more operations, they are listed in the response along with their possible causes.
rejectOperations– List with theidof the rejected operations;possibleCausesOfRejectOperations– Object in which each key is theidof a rejected operation and the value is the list of possible causes for the rejection. See the list of possible messages returned in Rejected Operations.code– Cause code;message– Cause description.
Fields returned only with trip
routes[].tripId– Identifier of the route generated by the Trip API;indicators.tollCosts– Total toll cost of the solution.
Fields returned only with compartments
routes[].compartmentConfiguration– Name of the compartment configuration used in the route;routes[].activities[].operationCompartments– Distribution of the operations across the vehicle’s compartments. Returned only inLOADINGactivities:groupId–idof the operation;compartmentSolutions– List of compartments used by the operation:compartment– Compartment name;capacityWeightUsed– Weight allocated to the compartment;capacityVolumeUsed– Volume allocated to the compartment.
Complete response
The complete response is shown below, generated from the request in this example:
{
"id": "6af70501533ca0240d44adc5",
"clientId": "maplink",
"vehicleRoutes": [
{
"routes": [
{
"id": "NewRoute_1_1",
"activities": [
{
"activity": "ROUTE_START",
"timeWindow": {
"start": 1513754569000,
"end": 1513754569000
},
"type": "SITE",
"site": "CD",
"operations": []
},
{
"activity": "LOADING",
"timeWindow": {
"start": 1513754569000,
"end": 1513755469000
},
"type": "SITE",
"site": "CD",
"fixedTimeSite": 900,
"volume": 7.0,
"weight": 350.0,
"operations": [
"P2",
"P1"
]
},
{
"activity": "DRIVING",
"timeWindow": {
"start": 1513755469000,
"end": 1513756800000
},
"type": "DRIVING",
"operations": [],
"arrivalSite": "Cliente1",
"departureSite": "CD",
"distance": 13410,
"nominalDuration": 1331
},
{
"activity": "DELIVERY",
"timeWindow": {
"start": 1513756800000,
"end": 1513757400000
},
"type": "SITE",
"site": "Cliente1",
"fixedTimeSite": 600,
"volume": 2.0,
"weight": 100.0,
"operations": [
"P1"
]
},
{
"activity": "DRIVING",
"timeWindow": {
"start": 1513757400000,
"end": 1513759737000
},
"type": "DRIVING",
"operations": [],
"arrivalSite": "Cliente2",
"departureSite": "Cliente1",
"distance": 26603,
"nominalDuration": 2337
},
{
"activity": "DELIVERY",
"timeWindow": {
"start": 1513759737000,
"end": 1513760337000
},
"type": "SITE",
"site": "Cliente2",
"fixedTimeSite": 600,
"volume": 5.0,
"weight": 250.0,
"operations": [
"P2"
]
},
{
"activity": "DRIVING",
"timeWindow": {
"start": 1513760337000,
"end": 1513763220000
},
"type": "DRIVING",
"operations": [],
"arrivalSite": "CD",
"departureSite": "Cliente2",
"distance": 34654,
"nominalDuration": 2883
},
{
"activity": "ROUTE_END",
"timeWindow": {
"start": 1513763220000,
"end": 1513763220000
},
"type": "SITE",
"site": "CD",
"operations": []
}
]
}
],
"vehicle": "VUC_1",
"period": {
"timeWindow": {
"start": 1513753200000,
"end": 1513796400000
},
"departureSite": "CD",
"arrivalSite": "CD"
}
}
],
"indicators": {
"totalServiceTime": 2100,
"totalDeliveringTime": 1200,
"dayWorkingTotalTime": 8651,
"nightWorkingTotalTime": 0,
"totalUnloadingTime": 0,
"totalWorkingTime": 8651,
"totalCollectingTime": 0,
"timeWindowNumber": 1,
"totalDrivingTime": 6551,
"totalLoadingTime": 900,
"totalTime": 8651,
"totalDistance": 74667,
"averageOccupancyRateVolume": 35.0,
"averageOccupancyRateWeight": 29.17,
"rejectOperationsNumber": 0,
"totalWaitingTime": 0,
"totalRestTime": 0,
"routesNumber": 1
}
}
