Skip to main content
The V4 API runs the new routing, which plans routes faster and gives clearer reasons when a visit is dropped. The V4 API also uses a cleaner request and response format than the V3 API. This page explains what is better, what changed in the requests you send and the responses you receive, and how to start.

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, a POST /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:00 shift. 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 as visitDuration and travelDuration. In the V3 format, the names mix time and duration.
  • Grouped data. In a routing result, a route (an item of routing[]) keeps the vehicle details in vehicle, the route totals in summary and the stops in trips. A stop (an item of trips) keeps the visit details in visit. 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 same POST /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 in data:
  • POST /routing, GET /result/{resultId} and PATCH /result/{resultId}.
  • GET /results: each item of the list in data.data changes the same way.
These endpoints return the routing result in property:
  • PUT /result/{resultId}, POST /result/switch-visit, PUT /result/{resultId}/restore/{version} and PUT /result/{resultId}/reset.
For these endpoints only the response changes. The exceptions are 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 of routing[], 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

The trips 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. In dropped[].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-level summary 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 in trips:

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:
The responses to that request in the V3 API and the V4 API, with the main keys:

Start Using the V4 API

  1. Change the base URL from https://apiweb.mile.app/api/v3 to https://apiweb.mile.app/api/v4. Your access token stays the same.
  2. Send POST /routing with the new request body from Route Optimize. The response has the routing result in data. Save data._id, which is the resultId of the routing result.
  3. Read the result again with GET /result/{resultId}.
  4. 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.
  5. To change a routing result, send PUT /result/{resultId} or PATCH /result/{resultId}. To dispatch it, send POST /dispatch with the resultId in the body.
  6. 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.