> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mile.app/llms.txt
> Use this file to discover all available pages before exploring further.

# What's New in Routing API

> What the V4 API and the new routing improve, and what changes in each request and response compared with the V3 API

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.

| Routing request | Visits | No clustering | Minimum overlap | No overlap |
| - | - | - | - | - |
| Central Java | 120 | 5 s → 3 s | 10 s → 5 s | 7 s → 4 s |
| Jakarta | 127 | 9 s → 3 s | 16 s → 10 s | 19 s → 6 s |
| Jakarta (200 visits) | 200 | 9 s → 4 s | 14 s → 12 s | 20 s → 8 s |
| Denpasar | 256 | 33 s → 28 s | 29 s → 25 s | 1 m 25 s → 37 s |
| Jabodetabek | 500 | 1 m 26 s → 34 s | 2 m 8 s → 44 s | 2 m 30 s → 1 m 3 s |
| Surabaya | 1,000 | 8 m 30 s → 2 m 12 s | 9 m → 4 m 34 s | 9 m 18 s → 4 m 48 s |

### 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](#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.

| Version | Base URL |
| - | - |
| V3 API | `https://apiweb.mile.app/api/v3` |
| V4 API | `https://apiweb.mile.app/api/v4` |

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](#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](#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](https://docs.mile.app/pages/planning/routing/configuration/introduction.md). The table lists the fields that changed.

| V3 API | V4 API | Changes |
| - | - | - |
| `capacityConstraint` | `capacityConstraints` | Renamed to the plural, because the field is a list. |
| `useAllVehicle` | `useAllVehicles` | Renamed to the plural. |
| `defaultVisitTime` | `defaultVisitDuration` | Renamed: `Time` becomes `Duration`, like the other time-length fields. |
| `mergeVisitTime` | `mergeVisitDuration` | Renamed: `Time` becomes `Duration`. |
| `returnToBase` | `returnToHub` | Renamed: `Base` becomes `Hub`, the term used in the app. `returnToBase` is ignored. |

### 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](https://docs.mile.app/pages/planning/routing/visit.md). The table lists the fields that changed.

| V3 API | V4 API | Changes |
| - | - | - |
| `visitTime` | `visitDuration` | Renamed: `Time` becomes `Duration`. |
| `timeWindow` (one object) | `timeWindows` (a list of `startTime` and `endTime`) | Reshaped and renamed: one object becomes a list. The V3 API also accepted a `timeWindows` list. `timeWindow` is no longer read, and a visit accepts at most 3 time windows. |
| `capacity`, an object such as `{ "weight": 10 }` | `capacities`, a list such as `[{ "name": "weight", "value": 10 }]` | Reshaped: from an object keyed by capacity name to a list with one item per capacity. |
| `visitGroup` | `group` | Renamed to a shorter name. |
| `visitGroupPriority` | `priority` | Renamed to a shorter name. |

### 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](https://docs.mile.app/pages/planning/routing/vehicle.md). Only the capacity field of a vehicle changes.

| V3 API | V4 API | Changes |
| - | - | - |
| `capacity`, an object keyed by capacity name such as `{ "weight": { "min": 0, "max": 100 } }` | `capacities`, a list such as `[{ "name": "weight", "min": 0, "max": 100 }]` | Reshaped: from an object keyed by capacity name to a list with one item per capacity. |

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](#recalculate-route). The [Route optimize](https://docs.mile.app/api-reference/routing/routing/route-optimize.md) 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:

```json V3 API theme={null}
{
  "configuration": {
    "capacityConstraint": ["weight"],
    "useAllVehicle": true,
    "defaultVisitTime": 5,
    "mergeVisitTime": true,
    "returnToBase": true
  },
  "vehicles": [
    {
      "id": "vehicle-1",
      "name": "B 1234 XYZ",
      "capacity": { "weight": { "min": 0, "max": 100 } }
    }
  ],
  "visits": [
    {
      "id": "visit-1",
      "name": "Toko Sinar Jaya",
      "visitTime": 10,
      "timeWindow": { "startTime": "08:00", "endTime": "12:00" },
      "capacity": { "weight": 10 },
      "visitGroup": "area-north",
      "visitGroupPriority": 1
    }
  ]
}
```

```json V4 API theme={null}
{
  "configuration": {
    "capacityConstraints": ["weight"],
    "useAllVehicles": true,
    "defaultVisitDuration": 5,
    "mergeVisitDuration": true,
    "returnToHub": true
  },
  "vehicles": [
    {
      "id": "vehicle-1",
      "name": "B 1234 XYZ",
      "capacities": [{ "name": "weight", "min": 0, "max": 100 }]
    }
  ],
  "visits": [
    {
      "id": "visit-1",
      "name": "Toko Sinar Jaya",
      "visitDuration": 10,
      "timeWindows": [{ "startTime": "08:00", "endTime": "12:00" }],
      "capacities": [{ "name": "weight", "value": 10 }],
      "group": "area-north",
      "priority": 1
    }
  ]
}
```

## 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](https://docs.mile.app/pages/planning/routing/introduction.md).

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](#route-optimize) and [Update Routing Result](#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`.

| V3 API | V4 API | Changes |
| - | - | - |
| `routing[].vehicleId`, `vehicleName`, `vehicleTags` | `routing[].vehicle.id`, `vehicle.name`, `vehicle.tags` | Moved into `vehicle` and renamed: vehicle details are grouped there. |
| `assignee`, `speed`, `fixedCost`, `breakTime`, `subHubId`, `oddEven`, `isOddEven` on the route | The same keys inside `routing[].vehicle` | Moved into `vehicle`. |
| `workingTime` on the route | `routing[].vehicle.workingTime` | Moved into `vehicle`. `endTime` is a clock time such as `06:00`, not `30:00`. `multiday` is added: the number of extra days after the day the shift ends. A shift that ends the next day, such as `20:00`–`06:00`, has `multiday: 0`. |
| `totalTravelTime` on the route | `routing[].summary.totalTravelDuration` | Moved into `summary` and renamed: `Time` becomes `Duration`. |
| `totalDistance`, `totalNodes`, `totalVisits` on the route | The same keys inside `routing[].summary` | Moved into `summary`: totals are grouped there. |
| `totalTrips`, `finishTime`, `totalVisitTime`, `totalWaitingTime` on the route | — (not returned) | Not returned. The number of trips is 1 plus the number of `reload` stops after the first stop. Read the `etd` of the last item of `trips` for the finish time. Add up `trips[].visit.visitDuration` and `trips[].waitingDuration`, without the first hub stop, for the visit time total and the waiting time total. |
| One set of keys per capacity, such as `totalWeight`, `vehicleMaxWeight`, `vehicleMinWeight`, `weightPercentage` | `routing[].summary.capacities[]` with `name`, `min`, `max`, `used`, `percentage` | Reshaped: one list for every capacity instead of a set of keys for each capacity. |
| `weightPercentage` as text such as `"20%"` | `percentage` as a number | Reshaped: a number is easier to sort and calculate with. |

### 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`.

| V3 API | V4 API | Changes |
| - | - | - |
| `trips[].visitId`, `visitName`, `address`, `coordinate`, `tags` | `trips[].visit.id`, `visit.name`, `visit.address`, `visit.coordinate`, `visit.tags` | Moved into `visit` and renamed: visit details are grouped there. |
| `visitTime` | `visit.visitDuration` | Moved into `visit` and renamed: `Time` becomes `Duration`. |
| `timeWindow` | `visit.timeWindows` | Moved into `visit`, renamed and reshaped: now a list. |
| `visitGroup`, `visitGroupPriority` | `visit.group`, `visit.priority` | Moved into `visit` and renamed to shorter names. |
| One key per capacity, such as `weight` | `visit.capacities[]` with `name` and `value` | Reshaped: one list for every capacity. |
| `travelTime`, `waitingTime` | `travelDuration`, `waitingDuration` | Renamed: `Time` becomes `Duration`. |
| `eta`, `etd` | `eta`, `etd` | No change. In the V4 API, a time on a later day is written as `1 day, 01:30:00`. |
| `etaStr`, `etdStr` | — (not returned) | Not returned. Use `eta` and `etd`. |
| `isHub` | `nodeType` (`visit`, `hub`, `subhub` or `reload`), and `isHub`, which is `true` for `hub` and `reload` | Added: `nodeType` tells the kind of stop. `isHub` stays. |
| `isSubHub` | — (not returned) | Not returned. Use `nodeType`, which is `subhub` for a sub hub stop. |

### 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`.

| V3 API | V4 API | Changes |
| - | - | - |
| `dropped[].id`, `name`, `address`, `coordinate`, `tags` | `dropped[].visit.id`, `visit.name`, `visit.address`, `visit.coordinate`, `visit.tags` | Moved into `visit` and renamed, as in trips. |
| `visitTime`, `timeWindow`, `capacity` | `visit.visitDuration`, `visit.timeWindows`, `visit.capacities[]` | Moved into `visit`, with the same renames and reshapes as in the `POST /routing` request. |
| `visitGroup`, `visitGroupPriority` | `visit.group`, `visit.priority` | Moved into `visit` and renamed to shorter names. |
| `dropped[].code` (`RE-DROP-001` to `RE-DROP-008`) and `dropped[].reason` | `dropped[].code` as a drop reason code, and `dropped[].reason` | Changed: `dropped[].code` names the cause; `dropped[].reason` is in the language of the user who sends the routing request. See [Drop Reason Codes](#drop-reason-codes). |

### 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`.

| Code (V4 API) | Code (V3 API) | What it means | What to do |
| - | - | - | - |
| `NO_ROUTE` | `RE-DROP-001` | The location could not be reached. | Check the visit address or map pin. |
| `TAG_MISMATCH` | `RE-DROP-002` | No vehicle has all of the visit's tags. | Fix the tags, or add a vehicle that has them. |
| `CAPACITY_EXCEEDED` | `RE-DROP-003` | The visit does not fit in the space left on any vehicle, or on any trip for multi-trip. | Add a vehicle, adjust the capacity, or turn on `autoSplit`. |
| `TIME_CONSTRAINT` | `RE-DROP-004` | No vehicle has enough working time left. | Extend the working hours or add a vehicle. |
| `VISIT_GROUP_TOO_LARGE` | `RE-DROP-005` | The visit group is larger than the vehicle limits. | Not returned by the new routing; a grouped visit gets its real cause. No action needed. |
| `ASSIGNED_VEHICLE_NOT_FOUND` | `RE-DROP-006` | The assigned vehicle is not in the `POST /routing` request. | Send the vehicle, or clear `assignedVehicleId`. |
| `TIME_WINDOW_OUTSIDE_WORKING_TIME` | `RE-DROP-007` | The visit time window is outside every vehicle's working hours. | Adjust the time window or the working hours. |
| `UNREACHABLE_IN_TIME` | `RE-DROP-008` | The visit cannot be reached within its time window or working hours. | Widen the time window or check the location. |

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.

| V3 API | V4 API | Changes |
| - | - | - |
| `summary.totalTravelTime` | `summary.totalTravelDuration` | Renamed: `Time` becomes `Duration`. |
| `summary.totalVisitTime` | `summary.totalVisitDuration` | Renamed: `Time` becomes `Duration`. |
| `summary.totalWaitingTime` | `summary.totalWaitingDuration` | Renamed: `Time` becomes `Duration`. |
| `summary.totalSpentTime` | `summary.totalDuration` | Renamed to a clearer name for the total. |
| `summary.capacityConstraint[]` with `name`, `optimized`, `available`, `percentage` | `summary.capacities[]` with `name`, `min`, `max`, `used`, `percentage` | Reshaped and renamed: one list for every capacity, with new keys. |
| `configuration`: `capacityConstraint`, `useAllVehicle`, `defaultVisitTime`, `mergeVisitTime` | `configuration`: `capacityConstraints`, `useAllVehicles`, `defaultVisitDuration`, `mergeVisitDuration` | Renamed, the same as in the `POST /routing` request. |
| `configuration.returnToBase` | `configuration.returnToHub` | Renamed: read `returnToHub`. A routing result that uses the hub's configuration profile may also still carry `returnToBase` with the same value. |

For the full V3 structure, see the [Routing object](https://docs.mile.app/api-reference/objects/routing-object.md); for the V4 structure, see the response of [Route Optimize](https://docs.mile.app/api-reference/routing/routing/route-optimize.md).

### 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`:

```json V3 API theme={null}
{
  "routing": [
    {
      "vehicleId": "vehicle-1",
      "vehicleName": "B 1234 XYZ",
      "vehicleTags": [],
      "totalTravelTime": 16,
      "totalDistance": 6312,
      "totalVisits": 1,
      "totalWeight": 10,
      "vehicleMinWeight": 0,
      "vehicleMaxWeight": 100,
      "weightPercentage": "10%",
      "trips": [
        {
          "visitId": "visit-1",
          "visitName": "Toko Sinar Jaya",
          "visitTime": 10,
          "weight": 10,
          "travelTime": 16
        }
      ]
    }
  ],
  "dropped": [
    {
      "id": "visit-2",
      "name": "Apotek Sehat",
      "timeWindow": { "startTime": "05:00", "endTime": "05:30" },
      "capacity": { "weight": 10 },
      "code": "RE-DROP-007",
      "reason": "Visit time window is outside every vehicle's working hours. Adjust the visit time window or vehicle working hours."
    }
  ],
  "summary": {
    "totalTravelTime": 16,
    "totalVisitTime": 10,
    "totalWaitingTime": 0,
    "totalSpentTime": 26
  },
  "configuration": {
    "useAllVehicle": true,
    "mergeVisitTime": true
  }
}
```

```json V4 API theme={null}
{
  "routing": [
    {
      "vehicle": { "id": "vehicle-1", "name": "B 1234 XYZ", "tags": [] },
      "summary": {
        "totalTravelDuration": 16,
        "totalDistance": 6312,
        "totalVisits": 1,
        "capacities": [
          { "name": "weight", "min": 0, "max": 100, "used": 10, "percentage": 10 }
        ]
      },
      "trips": [
        {
          "visit": {
            "id": "visit-1",
            "name": "Toko Sinar Jaya",
            "visitDuration": 10,
            "capacities": [{ "name": "weight", "value": 10 }]
          },
          "travelDuration": 16
        }
      ]
    }
  ],
  "dropped": [
    {
      "visit": {
        "id": "visit-2",
        "name": "Apotek Sehat",
        "timeWindows": [{ "startTime": "05:00", "endTime": "05:30" }],
        "capacities": [{ "name": "weight", "value": 10 }]
      },
      "code": "TIME_WINDOW_OUTSIDE_WORKING_TIME",
      "reason": "Visit time window is outside every vehicle's working hours. Adjust the visit time window or vehicle working hours."
    }
  ],
  "summary": {
    "totalTravelDuration": 16,
    "totalVisitDuration": 10,
    "totalWaitingDuration": 0,
    "totalDuration": 26
  },
  "configuration": {
    "useAllVehicles": true,
    "mergeVisitDuration": true
  }
}
```

## 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](#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.

| V3 API | V4 API | Changes |
| - | - | - |
| `routing[].vehicleId`, `vehicleName` | `routing[].vehicle.id`, `vehicle.name` | Moved into `vehicle` and renamed: a route is identified by `vehicle.id`. |
| `trips[].visitId`, `visitName` | `trips[].visit.id`, `visit.name` | Moved into `visit` and renamed: a stop is identified by `visit.id`. |
| `dropped[].id`, `name` | `dropped[].visit.id`, `visit.name` | Moved into `visit` and renamed: a dropped visit is identified by `visit.id`. |
| No stop type | `trips[].nodeType` | Added: each stop carries its `nodeType`: `visit`, `hub`, `subhub` or `reload`. |

The same `PUT /result/{resultId}` request body in the V3 API and the V4 API, with one route and one stop:

```json V3 API theme={null}
{
  "result": {
    "routing": [
      {
        "vehicleId": "vehicle-1",
        "vehicleName": "B 1234 XYZ",
        "trips": [
          { "visitId": "visit-1", "visitName": "Toko Sinar Jaya" }
        ]
      }
    ]
  }
}
```

```json V4 API theme={null}
{
  "result": {
    "routing": [
      {
        "vehicle": { "id": "vehicle-1", "name": "B 1234 XYZ" },
        "trips": [
          {
            "visit": { "id": "visit-1", "name": "Toko Sinar Jaya" },
            "nodeType": "visit"
          }
        ]
      }
    ]
  }
}
```

## 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.

| V3 API | V4 API | Changes |
| - | - | - |
| `visitTime` | `visitDuration` | Renamed: `Time` becomes `Duration`. |
| `timeWindow` | `timeWindows` | Reshaped and renamed: from one object to a list of objects with `startTime` and `endTime`. |

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:

```json V3 API theme={null}
{
  "currentCoordinate": "-6.2088,106.8456",
  "visits": [
    {
      "id": "visit-1",
      "name": "Toko Sinar Jaya",
      "coordinate": "-6.2300,106.8700",
      "visitTime": 10,
      "timeWindow": { "startTime": "08:00", "endTime": "12:00" }
    }
  ]
}
```

```json V4 API theme={null}
{
  "currentCoordinate": "-6.2088,106.8456",
  "visits": [
    {
      "id": "visit-1",
      "name": "Toko Sinar Jaya",
      "coordinate": "-6.2300,106.8700",
      "visitDuration": 10,
      "timeWindows": [{ "startTime": "08:00", "endTime": "12:00" }]
    }
  ]
}
```

## Recalculate Route

`POST /route-calculate` (the [Calculate route](https://docs.mile.app/api-reference/routing/routing/calculate-route.md) 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.

| V3 API | V4 API | Changes |
| - | - | - |
| `speed` at the top level, required | `vehicle.speed`, optional | Moved into `vehicle`. |
| `workingTime` at the top level | `vehicle.workingTime` | Moved into `vehicle`. |
| No vehicle id | `vehicle.id`, a string | Added: `vehicle.id` is required. |
| `trips[].visitId`, `visitName`, `coordinate` | `trips[].visit.id`, `visit.name`, `visit.coordinate` | Moved into `visit` and renamed: visit details are grouped there. |
| `trips[].visitTime` | `trips[].visit.visitDuration` | Moved into `visit` and renamed: `Time` becomes `Duration`. |
| `trips[].travelTime`, `waitingTime` | `trips[].travelDuration`, `waitingDuration` | Renamed: `Time` becomes `Duration`. |
| `isHub: true` on the hub stop | `nodeType: "hub"` | Reshaped: see the paragraph above the table. |
| `trips[].visit.visitTime`, `visit.timeWindow`, `visit.visitGroup`, `visit.visitGroupPriority` | — (not accepted) | Not accepted. Inside `visit`, these V3 names return an error; at the `trips[]` level they are ignored. Use `visitDuration`, `timeWindows`, `group` and `priority` inside `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:

```json V3 API request theme={null}
{
  "speed": 25,
  "workingTime": { "startTime": "08:00", "endTime": "17:00" },
  "countryCode": "IDN",
  "trips": [
    {
      "visitId": "hub-1",
      "coordinate": "-6.2088,106.8456",
      "isHub": true
    },
    {
      "visitId": "visit-1",
      "visitName": "Toko Sinar Jaya",
      "coordinate": "-6.2300,106.8700",
      "visitTime": 10,
      "travelTime": 13
    }
  ]
}
```

```json V4 API request theme={null}
{
  "vehicle": {
    "id": "vehicle-1",
    "name": "B 1234 XYZ",
    "speed": 25,
    "workingTime": { "startTime": "08:00", "endTime": "17:00" }
  },
  "countryCode": "IDN",
  "trips": [
    {
      "visit": { "id": "hub-1", "coordinate": "-6.2088,106.8456" },
      "nodeType": "hub"
    },
    {
      "visit": {
        "id": "visit-1",
        "name": "Toko Sinar Jaya",
        "coordinate": "-6.2300,106.8700",
        "visitDuration": 10
      },
      "travelDuration": 13
    }
  ]
}
```

The responses to that request in the V3 API and the V4 API, with the main keys:

```json V3 API response theme={null}
{
  "speed": 25,
  "workingTime": { "startTime": "08:00", "endTime": "17:00" },
  "countryCode": "IDN",
  "trips": [
    {
      "visitId": "hub-1",
      "coordinate": "-6.2088,106.8456",
      "isHub": true,
      "travelTime": 0,
      "waitingTime": 0,
      "eta": "08:00:00",
      "etd": "08:00:00"
    },
    {
      "visitId": "visit-1",
      "visitName": "Toko Sinar Jaya",
      "coordinate": "-6.2300,106.8700",
      "visitTime": 10,
      "travelTime": 13,
      "waitingTime": 0,
      "eta": "08:13:00",
      "etd": "08:23:00"
    }
  ],
  "totalTrips": 1,
  "finishTime": "08:23:00",
  "totalNodes": 2,
  "totalVisits": 1
}
```

```json V4 API response theme={null}
{
  "vehicle": {
    "id": "vehicle-1",
    "name": "B 1234 XYZ",
    "speed": 25,
    "workingTime": { "startTime": "08:00", "endTime": "17:00", "multiday": 0 }
  },
  "summary": {
    "totalTravelDuration": 13,
    "totalDistance": 5387,
    "totalNodes": 2,
    "totalVisits": 1,
    "capacities": []
  },
  "trips": [
    {
      "visit": {
        "id": "hub-1",
        "coordinate": "-6.2088,106.8456",
        "visitDuration": 0
      },
      "travelDuration": 0,
      "waitingDuration": 0,
      "eta": "08:00:00",
      "etd": "08:00:00",
      "nodeType": "hub"
    },
    {
      "visit": {
        "id": "visit-1",
        "name": "Toko Sinar Jaya",
        "coordinate": "-6.2300,106.8700",
        "visitDuration": 10
      },
      "travelDuration": 13,
      "waitingDuration": 0,
      "eta": "08:13:00",
      "etd": "08:23:00",
      "nodeType": "visit"
    }
  ]
}
```

## 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](#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](https://docs.mile.app/pages/workflow/automation/events/on-routing-finished.md) and the [Webhook](https://docs.mile.app/pages/workflow/automation/actions/webhook.md) action, using your URL. Each finished routing result is sent as an HTTP POST. See [Routing Events](https://docs.mile.app/api-reference/webhooks/routing-events.md) 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).

## Webhooks and Schedules

The [routing webhook](https://docs.mile.app/api-reference/webhooks/routing-events.md#payload-format) 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](https://docs.mile.app/api-reference/routing/overview.md) - Route optimization overview
* [Routing Schedule](https://docs.mile.app/api-reference/routing/routing-schedule-overview.md) - Run route optimization on a schedule
* [Routing Events](https://docs.mile.app/api-reference/webhooks/routing-events.md) - Webhook payloads for routing events
* [Routing Object](https://docs.mile.app/api-reference/objects/routing-object.md) - Routing result data structure (V3 format)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.