{"id":4449,"date":"2023-12-12T17:34:00","date_gmt":"2023-12-12T17:34:00","guid":{"rendered":"https:\/\/developers.maplink.global\/?p=4449"},"modified":"2026-11-13T16:55:42","modified_gmt":"2026-11-13T16:55:42","slug":"response-structure-planning","status":"publish","type":"post","link":"https:\/\/developers.maplink.global\/en\/response-structure-planning\/","title":{"rendered":"Response Structure"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">For more details about this example, see <a href=\"https:\/\/developers.maplink.global\/en\/example-1-operations-with-a-single-vehicle\/\" target=\"_blank\" rel=\"noopener\">Example 1 \u2013 Operations with a single vehicle<\/a>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Request<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The request below was used to generate the response in this example. The request fields are described in detail in a dedicated article.<\/p>\n\n\n\n<pre class=\"EnlighterJSRAW\" data-enlighter-language=\"json\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">{\n    \"optimizationProfile\": \"BRAZIL46\",\n    \"startDate\": 1513750219000,\n    \"legislationProfiles\": [\n        {\n            \"name\": \"DEFAULT\"\n        }\n    ],\n    \"logisticConstraints\": [\n        {\n            \"name\": \"DEFAULT\",\n            \"siteLoadingFixedTime\": 900,\n            \"siteUnloadingFixedTime\": 600\n        }\n    ],\n    \"products\": [\n        {\n            \"name\": \"DEFAULT\"\n        }\n    ],\n    \"sites\": [\n        {\n            \"name\": \"Cliente1\",\n            \"coordinates\": {\n                \"latitude\": -23.507608,\n                \"longitude\": -46.587145\n            },\n            \"logisticConstraints\": \"DEFAULT\"\n        },\n        {\n            \"name\": \"Cliente2\",\n            \"coordinates\": {\n                \"latitude\": -23.621059,\n                \"longitude\": -46.756193\n            },\n            \"logisticConstraints\": \"DEFAULT\"\n        }\n    ],\n    \"depots\": [\n        {\n            \"name\": \"CD\",\n            \"coordinates\": {\n                \"latitude\": -23.503939,\n                \"longitude\": -46.498419\n            },\n            \"logisticConstraints\": \"DEFAULT\"\n        }\n    ],\n    \"vehicleTypes\": [\n        {\n            \"name\": \"VUC\",\n            \"maxVolume\": 20,\n            \"maxWeight\": 1200,\n            \"size\": 1\n        }\n    ],\n    \"vehicles\": [\n        {\n            \"name\": \"VUC_1\",\n            \"vehicleType\": \"VUC\",\n            \"legislationProfile\": \"DEFAULT\",\n            \"availablePeriods\": [\n                {\n                    \"departureSite\": \"CD\",\n                    \"arrivalSite\": \"CD\",\n                    \"timeWindow\": {\n                        \"start\": 1513753200000,\n                        \"end\": 1513796400000\n                    }\n                }\n            ]\n        }\n    ],\n    \"operations\": [\n        {\n            \"id\": \"P1\",\n            \"weight\": 100,\n            \"volume\": 2,\n            \"product\": \"DEFAULT\",\n            \"type\": \"DELIVERY\",\n            \"depotSite\": \"CD\",\n            \"customerSite\": \"Cliente1\",\n            \"customerTimeWindows\": [\n                {\n                    \"start\": 1513756800000,\n                    \"end\": 1513771200000\n                }\n            ]\n        },\n        {\n            \"id\": \"P2\",\n            \"weight\": 250,\n            \"volume\": 5,\n            \"product\": \"DEFAULT\",\n            \"type\": \"DELIVERY\",\n            \"depotSite\": \"CD\",\n            \"customerSite\": \"Cliente2\",\n            \"customerTimeWindows\": [\n                {\n                    \"start\": 1513756800000,\n                    \"end\": 1513771200000\n                }\n            ]\n        }\n    ]\n}<\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Response<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The response consists of the fields below. The <code>vehicleRoutes<\/code> and <code>indicators<\/code> 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 &#8220;Fields returned only&#8230;&#8221; sections.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>id<\/code> \u2013 Unique identifier of the generated solution;<\/li>\n\n\n\n<li><code>clientId<\/code> \u2013 Identifier of the client that made the request;<\/li>\n\n\n\n<li><code>vehicleRoutes<\/code> \u2013 List of the routes calculated for each vehicle;<\/li>\n\n\n\n<li><code>indicators<\/code> \u2013 Consolidated indicators for the solution.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">The <code>vehicleRoutes<\/code> field<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Each item in the list represents a vehicle and the routes it performs in its available period.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>vehicle<\/code> \u2013 Vehicle name;<\/li>\n\n\n\n<li><code>period<\/code> \u2013 Availability period of the vehicle used in the solution:\n<ul class=\"wp-block-list\">\n<li><code>timeWindow<\/code> \u2013 Time window of the period, with <code>start<\/code> and <code>end<\/code> (<em>timestamp<\/em> in milliseconds);<\/li>\n\n\n\n<li><code>departureSite<\/code> \u2013 Vehicle departure site;<\/li>\n\n\n\n<li><code>arrivalSite<\/code> \u2013 Vehicle arrival site;<\/li>\n\n\n\n<li><code>maxRoutesNumber<\/code> \u2013 Maximum number of routes for the vehicle in the period. Returned only when informed in the request.<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><code>routes<\/code> \u2013 List of the vehicle&#8217;s routes:\n<ul class=\"wp-block-list\">\n<li><code>id<\/code> \u2013 Route identifier;<\/li>\n\n\n\n<li><code>activities<\/code> \u2013 Ordered list of the route&#8217;s activities:\n<ul class=\"wp-block-list\">\n<li><code>activity<\/code> \u2013 Activity type. The possible values are:\n<ul class=\"wp-block-list\">\n<li><code>ROUTE_START<\/code> \u2013 Start of the route;<\/li>\n\n\n\n<li><code>LOADING<\/code> \u2013 Loading at the depot;<\/li>\n\n\n\n<li><code>DRIVING<\/code> \u2013 Travel between two sites;<\/li>\n\n\n\n<li><code>DELIVERY<\/code> \u2013 Delivery to the customer;<\/li>\n\n\n\n<li><code>COLLECTION<\/code> \u2013 Collection from the customer;<\/li>\n\n\n\n<li><code>UNLOADING<\/code> \u2013 Unloading;<\/li>\n\n\n\n<li><code>WAITING<\/code> \u2013 Waiting;<\/li>\n\n\n\n<li><code>PAUSE<\/code> \u2013 Pause;<\/li>\n\n\n\n<li><code>REST<\/code> \u2013 Rest;<\/li>\n\n\n\n<li><code>ROUTE_END<\/code> \u2013 End of the route.<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><code>type<\/code> \u2013 Activity classification: <code>SITE<\/code> for activities performed at a site and <code>DRIVING<\/code> for travel;<\/li>\n\n\n\n<li><code>timeWindow<\/code> \u2013 Time window in which the activity takes place, with <code>start<\/code> and <code>end<\/code> (<em>timestamp<\/em> in milliseconds);<\/li>\n\n\n\n<li><code>operations<\/code> \u2013 List with the <code>id<\/code> of the operations handled in the activity. It is empty in activities such as <code>ROUTE_START<\/code>, <code>DRIVING<\/code>, and <code>ROUTE_END<\/code>;<\/li>\n\n\n\n<li><code>site<\/code> \u2013 Site where the activity is performed. Returned in <code>SITE<\/code> type activities;<\/li>\n\n\n\n<li><code>fixedTimeSite<\/code> \u2013 Fixed service time at the site, in seconds. Returned in <code>LOADING<\/code>, <code>UNLOADING<\/code>, <code>COLLECTION<\/code>, and <code>DELIVERY<\/code> activities;<\/li>\n\n\n\n<li><code>volume<\/code> \u2013 Volume of the operations handled in the activity. Returned in <code>LOADING<\/code>, <code>UNLOADING<\/code>, <code>COLLECTION<\/code>, and <code>DELIVERY<\/code> activities;<\/li>\n\n\n\n<li><code>weight<\/code> \u2013 Weight of the operations handled in the activity. Returned in <code>LOADING<\/code>, <code>UNLOADING<\/code>, <code>COLLECTION<\/code>, and <code>DELIVERY<\/code> activities;<\/li>\n\n\n\n<li><code>departureSite<\/code> \u2013 Origin site of the trip. Returned in <code>DRIVING<\/code>;<\/li>\n\n\n\n<li><code>arrivalSite<\/code> \u2013 Destination site of the trip. Returned in <code>DRIVING<\/code>;<\/li>\n\n\n\n<li><code>distance<\/code> \u2013 Distance traveled in the trip, in meters. Returned in <code>DRIVING<\/code>;<\/li>\n\n\n\n<li><code>nominalDuration<\/code> \u2013 Nominal duration of the trip, in seconds. Returned in <code>DRIVING<\/code>.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">In the example, the route of vehicle <code>VUC_1<\/code> follows this sequence of activities: <code>ROUTE_START<\/code> at the CD, <code>LOADING<\/code> of operations P2 and P1, <code>DRIVING<\/code> to Cliente1, <code>DELIVERY<\/code> of operation P1, <code>DRIVING<\/code> to Cliente2, <code>DELIVERY<\/code> of operation P2, <code>DRIVING<\/code> back to the CD, and <code>ROUTE_END<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">The <code>indicators<\/code> field<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Consolidated indicators for the entire solution. All times are returned in seconds and distance in meters.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>routesNumber<\/code> \u2013 Number of routes in the solution;<\/li>\n\n\n\n<li><code>rejectOperationsNumber<\/code> \u2013 Number of rejected operations, that is, operations not served by the solution;<\/li>\n\n\n\n<li><code>timeWindowNumber<\/code> \u2013 Number of time windows considered in the solution;<\/li>\n\n\n\n<li><code>totalDistance<\/code> \u2013 Total distance traveled;<\/li>\n\n\n\n<li><code>totalTime<\/code> \u2013 Total time of the routes;<\/li>\n\n\n\n<li><code>totalWorkingTime<\/code> \u2013 Total working time:\n<ul class=\"wp-block-list\">\n<li><code>dayWorkingTotalTime<\/code> \u2013 Working time during the day period;<\/li>\n\n\n\n<li><code>nightWorkingTotalTime<\/code> \u2013 Working time during the night period.<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><code>totalDrivingTime<\/code> \u2013 Total driving time;<\/li>\n\n\n\n<li><code>totalServiceTime<\/code> \u2013 Total service time at the sites:\n<ul class=\"wp-block-list\">\n<li><code>totalLoadingTime<\/code> \u2013 Total loading time;<\/li>\n\n\n\n<li><code>totalDeliveringTime<\/code> \u2013 Total delivery time;<\/li>\n\n\n\n<li><code>totalUnloadingTime<\/code> \u2013 Total unloading time;<\/li>\n\n\n\n<li><code>totalCollectingTime<\/code> \u2013 Total collection time.<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><code>totalWaitingTime<\/code> \u2013 Total waiting time;<\/li>\n\n\n\n<li><code>totalRestTime<\/code> \u2013 Total rest time;<\/li>\n\n\n\n<li><code>averageOccupancyRateVolume<\/code> \u2013 Average vehicle occupancy rate by volume, as a percentage;<\/li>\n\n\n\n<li><code>averageOccupancyRateWeight<\/code> \u2013 Average vehicle occupancy rate by weight, as a percentage.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Fields returned only when there are rejected operations<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">When the solver cannot serve one or more operations, they are listed in the response along with their possible causes.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>rejectOperations<\/code> \u2013 List with the <code>id<\/code> of the rejected operations;<\/li>\n\n\n\n<li><code>possibleCausesOfRejectOperations<\/code> \u2013 Object in which each key is the <code>id<\/code> of a rejected operation and the value is the list of possible causes for the rejection. See the list of possible messages returned in <a href=\"https:\/\/developers.maplink.global\/en\/rejected-operations\/\" data-type=\"link\" data-id=\"https:\/\/developers.maplink.global\/en\/rejected-operations\/\">Rejected Operations<\/a>.\n<ul class=\"wp-block-list\">\n<li><code>code<\/code> \u2013 Cause code;<\/li>\n\n\n\n<li><code>message<\/code> \u2013 Cause description.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Fields returned only with <code>trip<\/code><\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>routes[].tripId<\/code> \u2013 Identifier of the route generated by the Trip API;<\/li>\n\n\n\n<li><code>indicators.tollCosts<\/code> \u2013 Total toll cost of the solution.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Fields returned only with compartments<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>routes[].compartmentConfiguration<\/code> \u2013 Name of the compartment configuration used in the route;<\/li>\n\n\n\n<li><code>routes[].activities[].operationCompartments<\/code> \u2013 Distribution of the operations across the vehicle&#8217;s compartments. Returned only in <code>LOADING<\/code> activities:\n<ul class=\"wp-block-list\">\n<li><code>groupId<\/code> \u2013 <code>id<\/code> of the operation;<\/li>\n\n\n\n<li><code>compartmentSolutions<\/code> \u2013 List of compartments used by the operation:\n<ul class=\"wp-block-list\">\n<li><code>compartment<\/code> \u2013 Compartment name;<\/li>\n\n\n\n<li><code>capacityWeightUsed<\/code> \u2013 Weight allocated to the compartment;<\/li>\n\n\n\n<li><code>capacityVolumeUsed<\/code> \u2013 Volume allocated to the compartment.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Complete response<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The complete response is shown below, generated from the request in this example:<\/p>\n\n\n\n<pre class=\"EnlighterJSRAW\" data-enlighter-language=\"json\" data-enlighter-theme=\"\" data-enlighter-highlight=\"\" data-enlighter-linenumbers=\"\" data-enlighter-lineoffset=\"\" data-enlighter-title=\"\" data-enlighter-group=\"\">{\n    \"id\": \"6af70501533ca0240d44adc5\",\n    \"clientId\": \"maplink\",\n    \"vehicleRoutes\": [\n        {\n            \"routes\": [\n                {\n                    \"id\": \"NewRoute_1_1\",\n                    \"activities\": [\n                        {\n                            \"activity\": \"ROUTE_START\",\n                            \"timeWindow\": {\n                                \"start\": 1513754569000,\n                                \"end\": 1513754569000\n                            },\n                            \"type\": \"SITE\",\n                            \"site\": \"CD\",\n                            \"operations\": []\n                        },\n                        {\n                            \"activity\": \"LOADING\",\n                            \"timeWindow\": {\n                                \"start\": 1513754569000,\n                                \"end\": 1513755469000\n                            },\n                            \"type\": \"SITE\",\n                            \"site\": \"CD\",\n                            \"fixedTimeSite\": 900,\n                            \"volume\": 7.0,\n                            \"weight\": 350.0,\n                            \"operations\": [\n                                \"P2\",\n                                \"P1\"\n                            ]\n                        },\n                        {\n                            \"activity\": \"DRIVING\",\n                            \"timeWindow\": {\n                                \"start\": 1513755469000,\n                                \"end\": 1513756800000\n                            },\n                            \"type\": \"DRIVING\",\n                            \"operations\": [],\n                            \"arrivalSite\": \"Cliente1\",\n                            \"departureSite\": \"CD\",\n                            \"distance\": 13410,\n                            \"nominalDuration\": 1331\n                        },\n                        {\n                            \"activity\": \"DELIVERY\",\n                            \"timeWindow\": {\n                                \"start\": 1513756800000,\n                                \"end\": 1513757400000\n                            },\n                            \"type\": \"SITE\",\n                            \"site\": \"Cliente1\",\n                            \"fixedTimeSite\": 600,\n                            \"volume\": 2.0,\n                            \"weight\": 100.0,\n                            \"operations\": [\n                                \"P1\"\n                            ]\n                        },\n                        {\n                            \"activity\": \"DRIVING\",\n                            \"timeWindow\": {\n                                \"start\": 1513757400000,\n                                \"end\": 1513759737000\n                            },\n                            \"type\": \"DRIVING\",\n                            \"operations\": [],\n                            \"arrivalSite\": \"Cliente2\",\n                            \"departureSite\": \"Cliente1\",\n                            \"distance\": 26603,\n                            \"nominalDuration\": 2337\n                        },\n                        {\n                            \"activity\": \"DELIVERY\",\n                            \"timeWindow\": {\n                                \"start\": 1513759737000,\n                                \"end\": 1513760337000\n                            },\n                            \"type\": \"SITE\",\n                            \"site\": \"Cliente2\",\n                            \"fixedTimeSite\": 600,\n                            \"volume\": 5.0,\n                            \"weight\": 250.0,\n                            \"operations\": [\n                                \"P2\"\n                            ]\n                        },\n                        {\n                            \"activity\": \"DRIVING\",\n                            \"timeWindow\": {\n                                \"start\": 1513760337000,\n                                \"end\": 1513763220000\n                            },\n                            \"type\": \"DRIVING\",\n                            \"operations\": [],\n                            \"arrivalSite\": \"CD\",\n                            \"departureSite\": \"Cliente2\",\n                            \"distance\": 34654,\n                            \"nominalDuration\": 2883\n                        },\n                        {\n                            \"activity\": \"ROUTE_END\",\n                            \"timeWindow\": {\n                                \"start\": 1513763220000,\n                                \"end\": 1513763220000\n                            },\n                            \"type\": \"SITE\",\n                            \"site\": \"CD\",\n                            \"operations\": []\n                        }\n                    ]\n                }\n            ],\n            \"vehicle\": \"VUC_1\",\n            \"period\": {\n                \"timeWindow\": {\n                    \"start\": 1513753200000,\n                    \"end\": 1513796400000\n                },\n                \"departureSite\": \"CD\",\n                \"arrivalSite\": \"CD\"\n            }\n        }\n    ],\n    \"indicators\": {\n        \"totalServiceTime\": 2100,\n        \"totalDeliveringTime\": 1200,\n        \"dayWorkingTotalTime\": 8651,\n        \"nightWorkingTotalTime\": 0,\n        \"totalUnloadingTime\": 0,\n        \"totalWorkingTime\": 8651,\n        \"totalCollectingTime\": 0,\n        \"timeWindowNumber\": 1,\n        \"totalDrivingTime\": 6551,\n        \"totalLoadingTime\": 900,\n        \"totalTime\": 8651,\n        \"totalDistance\": 74667,\n        \"averageOccupancyRateVolume\": 35.0,\n        \"averageOccupancyRateWeight\": 29.17,\n        \"rejectOperationsNumber\": 0,\n        \"totalWaitingTime\": 0,\n        \"totalRestTime\": 0,\n        \"routesNumber\": 1\n    }\n}<\/pre>\n","protected":false},"excerpt":{"rendered":"<p>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 [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"inline_featured_image":false,"footnotes":""},"categories":[160],"tags":[],"class_list":["post-4449","post","type-post","status-publish","format-standard","hentry","category-planning-en"],"acf":[],"_links":{"self":[{"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/posts\/4449","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/comments?post=4449"}],"version-history":[{"count":3,"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/posts\/4449\/revisions"}],"predecessor-version":[{"id":4457,"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/posts\/4449\/revisions\/4457"}],"wp:attachment":[{"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/media?parent=4449"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/categories?post=4449"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/developers.maplink.global\/en\/wp-json\/wp\/v2\/tags?post=4449"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}