What’s Better in the New Routing
Faster Routing
The new routing is about 1.2 to 4 times faster than the previous routing, most often 2 to 3 times. With the new routing, aPOST /routing request of up to 256 visits finishes within 40 seconds, and a request of 1,000 visits takes 2 to 5 minutes, compared with 8 to 10 minutes with the previous routing.
The table shows how long one POST /routing request takes on the server, from the previous routing to the new routing. The last three columns are the Clustering options of the routing configuration.
Other Improvements
Besides being faster, the new routing brings the improvements below. Some of them also change the field names and the structure of requests and responses in the V4 API:- Less overlap between vehicles. With clustering turned on, each vehicle’s route is kept closer to its own area, so routes overlap much less than before. Routes are easier to follow and to manage.
- Overnight and multi-day shifts. Working hours, breaks and visit time windows can now run past midnight, for example a
20:00–04:00shift. Multi-day plans repeat the shift every day, with a rest between shifts. - Multi-trip fixes. Vehicles can now reload correctly more than once. Before, only the first reload worked, so visits were dropped even when more reloads were allowed.
- Clearer drop reasons. Each dropped visit gets its own drop reason code and a readable message in the language of the user who sends the routing request. A dropped visit in a visit group now gets its real cause, not a general group error. See Drop Reason Codes.
- Lists instead of objects named by capacity. In the V3 format, a capacity is an object with one key per capacity name, such as
{ "weight": 10 }. In the V4 format, it is a list, such as[{ "name": "weight", "value": 10 }]. Every capacity has the same shape, so your code reads weight, volume or any other capacity the same way, and a value is easier to check. - Consistent field names. Fields that hold a length of time end in
duration, such asvisitDurationandtravelDuration. In the V3 format, the names mixtimeandduration. - Grouped data. In a routing result, a route (an item of
routing[]) keeps the vehicle details invehicle, the route totals insummaryand the stops intrips. A stop (an item oftrips) keeps the visit details invisit. Data that belongs together is now in one place, so the result is easier to read and to map to your own system.
Routing API Versioning
The Routing API has two versions. The V3 API is on/api/v3 and runs the previous routing. The V4 API is on /api/v4 and runs the new routing.
Both APIs take the same
Authorization: Bearer token and need the same permissions and an active Route Optimization license. Each API can read every routing result, whichever API created it. Only their request and response formats differ.
The API reference endpoint pages in the Routing and Routing Schedule groups document the V4 API. Their request examples and API playground use the base URL https://apiweb.mile.app/api/v4.
Route Optimize
POST /routing plans the routes. You send the visits to serve, the vehicles to use and the routing configuration to follow, and the API saves a routing result. Both the request and the response change. This section covers the request; for the response, see Routing Result. Send the V4 field names in the request body.
The configuration and visits renames below apply to POST /routing. The visits renames also apply to POST /reorder-visits; see Reorder Visits.
Configuration
configuration holds the routing settings for one POST /routing request: which capacities to respect, multi-trip, return to hub, clustering, cross-docking, the default visit duration and so on. Without it, the default configuration profile of the hub is used. See Configuration. The table lists the fields that changed.
Visits
visits are the places a vehicle must go, such as a delivery or a pickup. Each visit has a location, a visit duration, time windows, a load (capacities), tags and an optional group and priority. See Visit. The table lists the fields that changed.
Vehicles
vehicles is the fleet available for one POST /routing request. Each vehicle has its working time, break, speed, capacity limits, tags and cost. See Vehicle. Only the capacity field of a vehicle changes.
A vehicle whose
workingTime.endTime is not later than its workingTime.startTime works one shift that ends the next day, such as an overnight or 24-hour shift. In POST /routing and routing schedules, the new routing plans that vehicle as one shift, not two.
In a POST /routing request, vehicles[].workingTime.multiday accepts 0 to 10. A request with a larger value returns 400.
The request fields not listed in the tables keep their names. On POST /routing and POST /reorder-visits, the V4 API ignores V3 fields that it does not read, such as returnToBase, instead of returning an error. POST /route-calculate is different; see Recalculate Route. The Route optimize endpoint page shows the Basic, Cross-Docking and Multi-Trip request examples.
Request Example
The samePOST /routing request in the V3 API and the V4 API, with only the fields that differ:
Routing Result
A routing result is what one routing run saves and returns: one route for each vehicle used, the dropped visits, the totals and the routing configuration that was used. See Routing. These endpoints return the routing result indata:
POST /routing,GET /result/{resultId}andPATCH /result/{resultId}.GET /results: each item of the list indata.datachanges the same way.
property:
PUT /result/{resultId},POST /result/switch-visit,PUT /result/{resultId}/restore/{version}andPUT /result/{resultId}/reset.
POST /routing and PUT /result/{resultId}, whose requests change too; see Route Optimize and Update Routing Result.
The V4 API moves the flat route keys and trip keys of a routing result into nested objects. The tables below compare the two APIs.
Routes
A route, an item ofrouting[], is the plan for one vehicle: the vehicle, its totals and its trips. The vehicle details are now in vehicle and the route totals in summary.
Trips
Thetrips of a route are the ordered stops of its vehicle: the hub, the visits and the reloads, each with its travel and waiting durations, ETA and ETD. The visit details of each stop are now in visit, and the time-length fields end in duration.
Dropped Visits
dropped lists the visits that could not be planned, each with a drop reason code. A dropped visit now keeps its visit details in visit, like a stop in trips.
Drop Reason Codes
A drop reason code says why a visit could not be planned. The two codes in each row mean the same thing. Indropped[].code, the V3 API and the V3 webhook format use the V3 codes (RE-DROP-001 to RE-DROP-008); the V4 API and the V4 webhook format use the V4 codes. A routing result created with the V3 API only has RE-DROP-001 to RE-DROP-004.
In the V4 API,
dropped[].reason is in the language of the user who sends the routing request. If that user has no language set, the reason uses the organization language, and otherwise English. All app languages are supported, and the language is chosen when the routing runs. Routing results created earlier may show the reason as it was stored at that time.
With crossDockingType set to all, a POST /routing request succeeds even when no sub hub vehicle matches any visit tag, and every visit is dropped as TAG_MISMATCH. Such a request no longer returns 400.
Summary and Configuration
The top-levelsummary of a routing result holds the totals for the whole result, and the top-level configuration holds the routing settings that were used. The other summary keys (totalDistance, totalVisits, routedVisits, droppedVisits, totalVehicles, usedVehicles, unusedVehicles, minFinishTime, maxFinishTime, avgFinishTime, avgSpeed) keep their names. In configuration, capacityConstraint, useAllVehicle, defaultVisitTime, mergeVisitTime and returnToBase are renamed in the same way as in the POST /routing request.
For the full V3 structure, see the Routing object; for the V4 structure, see the response of Route Optimize.
Response Example
The same routing result in the V3 API and the V4 API, showing only the keys that differ and one stop intrips:
Update Routing Result
PUT /result/{resultId} saves a routing result after manual edits, such as moving visits between vehicles. The request changes, and the response returns the routing result in property; see Routing Result.
In the request body, result holds the routing result in the nested V4 format. Send the whole routing result from GET /result/{resultId} with your edits; it replaces the stored one.
The same
PUT /result/{resultId} request body in the V3 API and the V4 API, with one route and one stop:
Reorder Visits
POST /reorder-visits finds the best order of a driver’s ongoing visits from the driver’s current location and saves the new order on the tasks. The request changes; the response does not.
Any V3 field that the V4 API does not read is ignored, without an error.
The same
POST /reorder-visits request in the V3 API and the V4 API:
Recalculate Route
POST /route-calculate (the Calculate route endpoint) recalculates the times and the distance of a route whose stop order you set yourself. Nothing is saved. POST /route-calculate/bulk does the same for several routes. Both endpoints change in the request and in the response. In the bulk request, the body is an array and the same changes apply to each item. An item may carry vehicleIndex, and the V4 API returns it in the response for that item.
The first item of trips is the hub stop where the route starts. In the V4 API, every item of trips carries a nodeType (hub, visit, reload or subhub), and the V4 API times the stops by nodeType, not by isHub. Send "nodeType": "hub" on the hub stop; without it, the stop is timed as a visit.
In the V3 API, the response is your request with the recalculated
trips, plus totalTrips, finishTime, totalNodes and totalVisits. In the V4 API, the response has vehicle, summary and trips.
The V4 API copies the visit object of each item of trips from the request into the response. To get visit.name back, send trips[].visit.name in the request (trips[].visitName in the V3 API). With no trips, or only hub and reload stops, the response is your request with an empty trips list.
The same POST /route-calculate request in the V3 API and the V4 API:
Start Using the V4 API
- Change the base URL from
https://apiweb.mile.app/api/v3tohttps://apiweb.mile.app/api/v4. Your access token stays the same. - Send
POST /routingwith the new request body from Route Optimize. The response has the routing result indata. Savedata._id, which is theresultIdof the routing result. - Read the result again with
GET /result/{resultId}. - To have routing results sent to your system, set up a routing webhook. On Workflow › Automation, click New and create an automation with the event On Routing Finished and the Webhook action, using your URL. Each finished routing result is sent as an HTTP POST. See Routing Events for the payload.
- To change a routing result, send
PUT /result/{resultId}orPATCH /result/{resultId}. To dispatch it, sendPOST /dispatchwith theresultIdin the body. - Routing schedules and the routing webhook follow the format set for your organization, V3 or V4. See Webhooks and Schedules.
Webhooks and Schedules
The routing webhook comes in two formats: the V3 format and the V4 format. Your organization receives one of them, and the V4 format is the default. The same format also decides whether your routing schedules run on the V3 or the V4 routing. It does not change the/api/v3 and /api/v4 endpoints: each one keeps its own request and response format.
If your organization still uses the V3 format and you want to switch to the V4 format, contact the support team. The change applies to your routing webhooks and routing schedules at once.
Related Resources
- Routing - Route optimization overview
- Routing Schedule - Run route optimization on a schedule
- Routing Events - Webhook payloads for routing events
- Routing Object - Routing result data structure (V3 format)