# Optimize

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 13 minutes read

<br />

# Optimize REST API

The **Optimize REST API** provides endpoints for performing route optimization within the Fleet Management system.

All operations are **stateless** - no data is stored in the database - making them ideal for **real-time route planning** and **what-if scenarios**.

***

### Key Functionalities[​](#key-functionalities "Direct link to Key Functionalities")

**1. Full Route Optimization**

* A comprehensive optimization that generates complete routing solutions.

* Considers multiple constraints such as:

  <!-- -->

  * Vehicle capabilities
  * Time windows
  * Capacity limits
  * Vehicle constraints
  * Configuration parameters

**2. Landmark Optimization**

* A lightweight optimization that takes a list of coordinates and reorders them into an optimal sequence.
* Best suited for **simple route planning** needs.

**3. Solution Retrieval**

* Dedicated `/optimize/{id}/solution` endpoint for retrieving optimization results
* **Request tracking** with status monitoring
* Support for polling mechanism to check completion status

***

### Benefits[​](#benefits "Direct link to Benefits")

* **Minimize travel time and distance** with advanced optimization algorithms

* **Respect all operational constraints** including vehicle capabilities and time windows

* **Flexible execution models**:

  <!-- -->

  * Asynchronous processing for complex multi-vehicle scenarios
  * Synchronous processing for simple coordinate optimization

* **Enhanced customization**:

  <!-- -->

  * Custom distance matrices for specialized routing needs
  * Order sequencing for pickup/delivery operations

* **Improved reliability** with better error handling and validation

* **Stateless operations** ideal for real-time planning and what-if scenarios

***

## Endpoints[​](#endpoints "Direct link to Endpoints")

### 1. Optimize Synchronously[​](#1-optimize-synchronously "Direct link to 1. Optimize Synchronously")

**Description:** Receives a set of locations, vehicles, vehicle constraints, and configuration parameters, solves the Vehicle Routing Problem (VRP) synchronously and returns the complete solution immediately. Unlike the asynchronous `/optimize` endpoint, this endpoint processes the request in real-time and returns the routing solution directly without requiring a separate solution retrieval step.

:::info Synchronous Processing This endpoint processes optimization requests synchronously, returning the complete solution immediately. Best suited for smaller optimization problems where immediate results are needed. :::

:::warning Performance Considerations Synchronous optimization may take longer to respond for complex problems with many vehicles and orders. For large-scale optimizations, consider using the asynchronous `/optimize` endpoint instead. :::

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `POST /fleetmanagement/optimize/sync`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **Returned error codes:**

| Error Code                  | Description                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `200 Successful`            | Successful operation, solution returned directly.                                                                 |
| `400 Bad Request`           | Invalid input or missing required fields.                                                                         |
| `401 Unauthorized`          | API key is missing or invalid.                                                                                    |
| `404 Not Found`             | No solution found, please try changing the constraints, or adding more vehicles, there may be more possibilities. |
| `405 Method Not Allowed`    | Incorrect method type.                                                                                            |
| `408 Request Timeout`       | Request processing took too long. Consider using the asynchronous `/optimize` endpoint for complex problems.      |
| `500 Internal Server Error` | Database error occurred.                                                                                          |

warning

**Input Requirements for Synchronous Optimization**

The same input requirements apply as for the asynchronous `/optimize` endpoint:

**Orders**

* Each order must include a **valid set of coordinates**.
* For each order's `timeWindows`, the **end time must be greater than the start time**.
* **RoundRoute**: requires **at least 1 order** and **1 departure**.
* **CustomEnd**: requires **at least 1 order**, **1 departure**, and **1 destination**.
* **EndAnywhere**: requires **at least 2 orders** and **1 departure**. More details on `route type`: [**Configuration Parameters**](/docs/cloud-rest-api/guides/fleet-management/core-concepts/configuration-parameters.md#configuration-parameters-structure)

**Vehicles**

* At least **1 vehicle** must be defined.

* **Vehicle type is mandatory** and cannot be empty.

* Each vehicle's `startTime` must always be **less than its `endTime`**.

* Vehicle constraints must be provided either:

  <!-- -->

  * **One globally** (applies to all vehicles), or
  * **Individually for each vehicle** (same number of constraints as vehicles). More details: [**Vehicle Constraints**](/docs/cloud-rest-api/guides/fleet-management/core-concepts/vehicle-constraints.md#vehicle-constraints-structure)

⚠️ If any of these requirements are not met, the solver will return an **input error**:<br />`400 - Bad Request` (Invalid input or missing required fields).

#### Example:[​](#example "Direct link to Example:")

* **Request Body:**

- Schema View
- JSON Example
- JSON View

* ▶`configurationParameters`(

  <!-- -->

  object

  <!-- -->

  )

  Configuration parameters for the optimization.

* ▶`departures`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of departure locations for the optimization.

* ▶`destinations`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of destination locations for the optimization (optional).

* ▶`orders`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of orders to optimize.

* ▶`vehicles`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of vehicles assigned to the optimization.

* ▶`vehiclesConstraints`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of vehicle constraints applied in the optimization.

* `matrixBuildType`(

  <!-- -->

  integer

  <!-- -->

  )

  Defines how the distance matrix is built. **Possible values:**

  * `0` - Set by user using 'matrices' field`matrices` field
  * `1` - Real road map distances and times (default) distances and times

* `matrices`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  Contains distance and time matrices, required when matrixBuildType is set to 0 (optional).

```json
{
  "configurationParameters": {
    "name": "Paris - test optimization",
    "ignoreTimeWindow": false,
    "allowDroppingOrders": false,
    "groupingOrders": false,
    "balancedRoutes": 0,
    "optimizationCriterion": 0,
    "arrangeCriterion": 0,
    "optimizationQuality": 2,
    "maxTimeToOptimize": 300,
    "maxWaitTime": 18000,
    "routeType": 0,
    "restrictions": 0,
    "distanceUnit": 0,
    "orderSequenceOptions": []
  },
  "orders": [
    {
      "alias": "Customer 1",
      "location": [
        48.870852,
        2.356148
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 2",
      "location": [
        48.827327,
        2.342267
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 3",
      "location": [
        48.88025,
        2.299601
      ],
      "type": 0,
      "numberOfPackages": 3,
      "weight": 5.1,
      "cube": 2.5,
      "timeWindow": [
        770,
        1020
      ],
      "serviceTime": 0,
      "revenue": 12,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 4",
      "location": [
        48.845198,
        2.402896
      ],
      "type": 1,
      "numberOfPackages": 8,
      "weight": 15.4,
      "cube": 5.8,
      "timeWindow": [
        753,
        1036
      ],
      "serviceTime": 0,
      "revenue": 2.7,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 5",
      "location": [
        48.897163,
        2.292865
      ],
      "type": 0,
      "numberOfPackages": 9,
      "weight": 16.2,
      "cube": 8.4,
      "timeWindow": [
        736,
        1086
      ],
      "serviceTime": 0,
      "revenue": 7.5,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 6",
      "location": [
        48.90092,
        2.400039
      ],
      "type": 1,
      "numberOfPackages": 9,
      "weight": 16.5,
      "cube": 9.7,
      "timeWindow": [
        786,
        1053
      ],
      "serviceTime": 0,
      "revenue": 10,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 7",
      "location": [
        48.860914,
        2.310625
      ],
      "type": 0,
      "numberOfPackages": 5,
      "weight": 7.5,
      "cube": 2.6,
      "timeWindow": [
        820,
        1020
      ],
      "serviceTime": 0,
      "revenue": 13.4,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 8",
      "location": [
        48.827865,
        2.379216
      ],
      "type": 1,
      "numberOfPackages": 11,
      "weight": 12.1,
      "cube": 4.6,
      "timeWindow": [
        753,
        1086
      ],
      "serviceTime": 0,
      "revenue": 14.7,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 9",
      "location": [
        48.887096,
        2.283513
      ],
      "type": 1,
      "numberOfPackages": 6,
      "weight": 5.2,
      "cube": 1.5,
      "timeWindow": [
        770,
        1070
      ],
      "serviceTime": 0,
      "revenue": 2.9,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 10",
      "location": [
        48.896894,
        2.321586
      ],
      "type": 0,
      "numberOfPackages": 13,
      "weight": 6.3,
      "cube": 7.5,
      "timeWindow": [
        836,
        1053
      ],
      "serviceTime": 0,
      "revenue": 8.1,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 11",
      "location": [
        48.870449,
        2.342204
      ],
      "type": 0,
      "numberOfPackages": 10,
      "weight": 8,
      "cube": 4.1,
      "timeWindow": [
        903,
        1020
      ],
      "serviceTime": 0,
      "revenue": 6.2,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 12",
      "location": [
        48.895658,
        2.344043
      ],
      "type": 0,
      "numberOfPackages": 6,
      "weight": 4.8,
      "cube": 11.5,
      "timeWindow": [
        870,
        1020
      ],
      "serviceTime": 0,
      "revenue": 2.3,
      "priority": 0,
      "customData": ""
    }
  ],
  "departures": [
    {
      "alias": "Depot 1",
      "location": [
        48.870569,
        2.356448
      ]
    },
    {
      "alias": "Depot 2",
      "location": [
        48.82674,
        2.342116
      ]
    }
  ],
  "destinations": [],
  "vehicles": [
    {
      "name": "Car vehicle 1",
      "type": 0,
      "maxLoadWeight": 60,
      "maxLoadCube": 50,
      "startTime": 420,
      "endTime": 1439,
      "availableBreaks": "AA-123-AA",
      "licensePlate": 6.5,
      "consumption": [
        {
          "duration": 1800,
          "timeWindows": [
            [
              720,
              780
            ],
            [
              900,
              960
            ]
          ]
        }
      ]
    },
    {
      "name": "Car vehicle 2",
      "type": 0,
      "maxLoadWeight": 60,
      "maxLoadCube": 50,
      "startTime": 420,
      "endTime": 1439,
      "availableBreaks": "AA-124-AA",
      "licensePlate": 6.5,
      "consumption": [
        {
          "duration": 1800,
          "timeWindows": [
            [
              720,
              780
            ],
            [
              900,
              960
            ]
          ]
        }
      ]
    }
  ],
  "vehiclesConstraints": [
    {
      "startDate": 1596758400000,
      "maxNumberOfPackages": 53,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 99999999,
      "minDistance": 0,
      "maxDistance": 99999999,
      "maxRevenue": 85
    }
  ],
  "matrixBuildType": 1
}

```

```json
{
  "configurationParameters": {
    "name": "string",
    "ignoreTimeWindow": false,
    "allowDroppingOrders": false,
    "groupingOrders": false,
    "balancedRoutes": 0,
    "optimizationCriterion": 0,
    "arrangeCriterion": 0,
    "optimizationQuality": 0,
    "maxTimeToOptimize": 0,
    "maxWaitTime": 0,
    "routeType": 0,
    "restrictions": 0,
    "distanceUnit": 0,
    "orderSequenceOptions": []
  },
  "orders": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "departures": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ]
    }
  ],
  "destinations": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ]
    }
  ],
  "vehicles": [
    {
      "name": "string",
      "type": 0,
      "maxLoadWeight": 0,
      "maxLoadCube": 0,
      "startTime": 0,
      "endTime": 1439,
      "availableBreaks": "string",
      "licensePlate": 0
    }
  ],
  "vehiclesConstraints": [
    {
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ],
  "matrixBuildType": 1
}

```

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* ▶`drpppedOrders`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of orders excluded from the optimization because no feasible solution was found.

* ▶`routes`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of optimized routes

```json
{
  "droppedOrders": [],
  "routes": [
    {
      "breaks": [
        {
          "duration": 1800,
          "startTime": 720
        }
      ],
      "orders": [
        {
          "alias": "Customer 11",
          "location": [
            48.870852,
            2.356148
          ],
          "matchedLocation": [
            48.8701825,
            2.3423565625
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 10,
          "weight": 8,
          "cube": 4.1,
          "revenue": 6.2,
          "serviceTime": 0,
          "timeWindow": [
            903,
            1020
          ],
          "indexInRoute": 0,
          "indexInOptimization": 10,
          "arrivalTime": 1596812580000,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 34,
          "weightAtArrival": 49.2,
          "cubeAtArrival": 21.6,
          "traveledDistance": 1.4171849,
          "revenueAtArrival": 0,
          "deliveredNumberOfPackages": 10,
          "deliveredWeight": 8,
          "deliveredCube": 4.1,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 6",
          "location": [
            48.827327,
            2.342267
          ],
          "matchedLocation": [
            48.9005959375,
            2.4000475
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 9,
          "weight": 16.5,
          "cube": 9.7,
          "revenue": 10,
          "serviceTime": 0,
          "timeWindow": [
            786,
            1053
          ],
          "indexInRoute": 1,
          "indexInOptimization": 5,
          "arrivalTime": 1596813655241,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 44,
          "weightAtArrival": 57.2,
          "cubeAtArrival": 25.7,
          "traveledDistance": 7.2696328,
          "revenueAtArrival": 6.2,
          "collectedNumberOfPackages": 9,
          "collectedWeight": 16.5,
          "collectedCube": 9.7,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 4",
          "location": [
            48.88025,
            2.299601
          ],
          "matchedLocation": [
            48.8452625,
            2.4027009375
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 8,
          "weight": 15.4,
          "cube": 5.8,
          "revenue": 2.7,
          "serviceTime": 0,
          "timeWindow": [
            753,
            1036
          ],
          "indexInRoute": 2,
          "indexInOptimization": 3,
          "arrivalTime": 1596814512563,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 35,
          "weightAtArrival": 40.7,
          "cubeAtArrival": 16,
          "traveledDistance": 13.1220808,
          "revenueAtArrival": 16.2,
          "collectedNumberOfPackages": 8,
          "collectedWeight": 15.4,
          "collectedCube": 5.8,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 8",
          "location": [
            48.845198,
            2.402896
          ],
          "matchedLocation": [
            48.82792,
            2.3791415625
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 11,
          "weight": 12.1,
          "cube": 4.6,
          "revenue": 14.7,
          "serviceTime": 0,
          "timeWindow": [
            753,
            1086
          ],
          "indexInRoute": 3,
          "indexInOptimization": 7,
          "arrivalTime": 1596815042263,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 27,
          "weightAtArrival": 25.3,
          "cubeAtArrival": 10.2,
          "traveledDistance": 18.9745293,
          "revenueAtArrival": 18.9,
          "collectedNumberOfPackages": 11,
          "collectedWeight": 12.1,
          "collectedCube": 4.6,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 7",
          "location": [
            48.897163,
            2.292865
          ],
          "matchedLocation": [
            48.86112,
            2.310630625
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 5,
          "weight": 7.5,
          "cube": 2.6,
          "revenue": 13.4,
          "serviceTime": 0,
          "timeWindow": [
            820,
            1020
          ],
          "indexInRoute": 4,
          "indexInOptimization": 6,
          "arrivalTime": 1596816069637,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 16,
          "weightAtArrival": 13.2,
          "cubeAtArrival": 5.6,
          "traveledDistance": 24.8269768,
          "revenueAtArrival": 33.6,
          "deliveredNumberOfPackages": 5,
          "deliveredWeight": 7.5,
          "deliveredCube": 2.6,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 3",
          "location": [
            48.90092,
            2.400039
          ],
          "matchedLocation": [
            48.8802215625,
            2.2997153125
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 3,
          "weight": 5.1,
          "cube": 2.5,
          "revenue": 12,
          "serviceTime": 0,
          "timeWindow": [
            770,
            1020
          ],
          "indexInRoute": 5,
          "indexInOptimization": 2,
          "arrivalTime": 1596816563007,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 21,
          "weightAtArrival": 20.7,
          "cubeAtArrival": 8.2,
          "traveledDistance": 30.6794243,
          "revenueAtArrival": 47,
          "deliveredNumberOfPackages": 3,
          "deliveredWeight": 5.1,
          "deliveredCube": 2.5,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 9",
          "location": [
            48.860914,
            2.310625
          ],
          "matchedLocation": [
            48.886894375,
            2.2838003125
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 6,
          "weight": 5.2,
          "cube": 1.5,
          "revenue": 2.9,
          "serviceTime": 0,
          "timeWindow": [
            770,
            1070
          ],
          "indexInRoute": 6,
          "indexInOptimization": 8,
          "arrivalTime": 1596816932267,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 24,
          "weightAtArrival": 25.8,
          "cubeAtArrival": 10.7,
          "traveledDistance": 36.5318718,
          "revenueAtArrival": 59,
          "collectedNumberOfPackages": 6,
          "collectedWeight": 5.2,
          "collectedCube": 1.5,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 5",
          "location": [
            48.827865,
            2.379216
          ],
          "matchedLocation": [
            48.89706375,
            2.29247
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 9,
          "weight": 16.2,
          "cube": 8.39,
          "revenue": 7.5,
          "serviceTime": 0,
          "timeWindow": [
            736,
            1086
          ],
          "indexInRoute": 7,
          "indexInOptimization": 4,
          "arrivalTime": 1596817262381,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 18,
          "weightAtArrival": 20.6,
          "cubeAtArrival": 9.2,
          "traveledDistance": 42.3843193,
          "revenueAtArrival": 61.9,
          "deliveredNumberOfPackages": 9,
          "deliveredWeight": 16.2,
          "deliveredCube": 8.39,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 10",
          "location": [
            48.887096,
            2.283513
          ],
          "matchedLocation": [
            48.8971759375,
            2.321263125
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 13,
          "weight": 6.3,
          "cube": 7.5,
          "revenue": 8.1,
          "serviceTime": 0,
          "timeWindow": [
            836,
            1053
          ],
          "indexInRoute": 8,
          "indexInOptimization": 9,
          "arrivalTime": 1596817690016,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 27,
          "weightAtArrival": 36.8,
          "cubeAtArrival": 17.59,
          "traveledDistance": 48.2367668,
          "revenueAtArrival": 69.4,
          "deliveredNumberOfPackages": 13,
          "deliveredWeight": 6.3,
          "deliveredCube": 7.5,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 12",
          "location": [
            48.896894,
            2.321586
          ],
          "matchedLocation": [
            48.8958034375,
            2.3440403125
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 6,
          "weight": 4.8,
          "cube": 11.5,
          "revenue": 2.3,
          "serviceTime": 0,
          "timeWindow": [
            870,
            1020
          ],
          "indexInRoute": 9,
          "indexInOptimization": 11,
          "arrivalTime": 1596817984460,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 40,
          "weightAtArrival": 43.1,
          "cubeAtArrival": 25.09,
          "traveledDistance": 54.0892143,
          "revenueAtArrival": 77.5,
          "deliveredNumberOfPackages": 6,
          "deliveredWeight": 4.8,
          "deliveredCube": 11.5,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 1",
          "location": [
            48.870449,
            2.342204
          ],
          "matchedLocation": [
            48.8707784375,
            2.3565665625
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 0,
          "weight": 0,
          "cube": 0,
          "revenue": 0,
          "serviceTime": 0,
          "timeWindow": [
            420,
            1086
          ],
          "indexInRoute": 10,
          "indexInOptimization": 0,
          "arrivalTime": 1596818617911,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 46,
          "weightAtArrival": 47.9,
          "cubeAtArrival": 36.59,
          "traveledDistance": 59.9416618,
          "revenueAtArrival": 79.8,
          "collectedNumberOfPackages": 0,
          "collectedWeight": 0,
          "collectedCube": 0,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        }
      ],
      "departure": {
        "alias": "Depot 2",
        "location": [
          48.82679375,
          2.3420853125
        ],
        "matchedLocation": [
          48.82679375,
          2.3420853125
        ],
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "departureTime": 1596783600000,
        "timeToNext": 12122,
        "distanceToNext": 1.1342
      },
      "destination": {
        "alias": "Depot 2",
        "location": [
          48.82679375,
          2.3420853125
        ],
        "matchedLocation": [
          48.82679375,
          2.3420853125
        ],
        "arrivalTime": 1596818617911
      },
      "vehicle": {
        "name": "Car vehicle 1",
        "type": 0,
        "maxLoadWeight": 60,
        "maxLoadCube": 50,
        "startTime": 420,
        "endTime": 1439,
        "availableBreaks": "AA-123-AA",
        "licensePlate": 6.5,
        "consumption": [
          {
            "duration": 1800,
            "timeWindows": [
              [
                720,
                780
              ],
              [
                900,
                960
              ]
            ]
          }
        ]
      },
      "vehicleConstraints": {
        "startDate": 1596758400000,
        "maxNumberOfPackages": 53,
        "minNumberOfOrders": 0,
        "maxNumberOfOrders": 99999999,
        "minDistance": 0,
        "maxDistance": 99999999,
        "maxRevenue": 85
      },
      "totalDistance": 65.7941,
      "totalTime": 1597135480,
      "totalServiceTime": 0,
      "totalWaitTime": 0,
      "creationTimestamp": 1756296705030,
      "neededFuel": 4.2766175,
      "matrixBuildType": 1
    }
  ]
}

```

```json
{
  "droppedOrders": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "routes": [
    {
      "breaks": [],
      "orders": [
        {
          "alias": "string",
          "location": [
            0,
            0
          ],
          "matchedLocation": [
            0,
            0
          ],
          "type": 0,
          "priority": 0,
          "customData": "string",
          "numberOfPackages": 0,
          "weight": 0,
          "cube": 0,
          "revenue": 0,
          "serviceTime": 0,
          "timeWindow": [
            0,
            0
          ],
          "indexInRoute": 0,
          "indexInOptimization": 0,
          "arrivalTime": 0,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 0,
          "weightAtArrival": 0,
          "cubeAtArrival": 0,
          "traveledDistance": 0,
          "revenueAtArrival": 0,
          "deliveredNumberOfPackages": 0,
          "deliveredWeight": 0,
          "deliveredCube": 0,
          "distanceToNextOrder": 0,
          "timeToNextOrder": 0
        }
      ],
      "departure": {
        "alias": "string",
        "location": [
          0,
          0
        ],
        "matchedLocation": [
          0,
          0
        ],
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "departureTime": 0,
        "timeToNext": 0,
        "distanceToNext": 0
      },
      "destination": {
        "alias": "string",
        "location": [
          0,
          0
        ],
        "matchedLocation": [
          0,
          0
        ],
        "arrivalTime": 0
      },
      "vehicle": {
        "name": "string",
        "type": 0,
        "maxLoadWeight": 0,
        "maxLoadCube": 0,
        "startTime": 0,
        "endTime": 1439,
        "availableBreaks": "string",
        "licensePlate": 0
      },
      "vehicleConstraints": {
        "startDate": 0,
        "maxNumberOfPackages": 0,
        "minNumberOfOrders": 0,
        "maxNumberOfOrders": 0,
        "minDistance": 0,
        "maxDistance": 0,
        "maxRevenue": 0
      },
      "totalDistance": 0,
      "totalTime": 0,
      "totalServiceTime": 0,
      "totalWaitTime": 0,
      "creationTimestamp": 0,
      "neededFuel": 0,
      "matrixBuildType": 1
    }
  ]
}

```

***

### 2. Optimize Asynchronously[​](#2-optimize-asynchronously "Direct link to 2. Optimize Asynchronously")

**Description:** Receives a set of locations, vehicles, vehicle constraints, and configuration parameters, solves the Vehicle Routing Problem (VRP) in a stateless manner using asynchronous background execution. Returns a request tracking object that allows you to monitor the optimization process status. Once processing is complete, retrieve the solution using the [`/optimize/{id}/solution`](/docs/cloud-rest-api/guides/fleet-management/core-concepts/landmark.md#3-get-solution) endpoint. The solution consists of one or more routes, where each route represents the trip that a vehicle travels to visit the assigned orders. The maximum number of routes returned equals the number of vehicles provided in the optimization request.

:::info Workflow After submitting an optimization request, you'll receive a request tracking object. Use the returned ID to monitor status and retrieve the final solution once processing is complete. :::

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `POST /fleetmanagement/optimize`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **Returned error codes:**

| Error Code                  | Description                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `200 Successful`            | Successful operation.                                                                                             |
| `400 Bad Request`           | Invalid input or missing required fields.                                                                         |
| `401 Unauthorized`          | API key is missing or invalid.                                                                                    |
| `404 Not Found`             | No solution found, please try changing the constraints, or adding more vehicles, there may be more possibilities. |
| `405 Method Not Allowed`    | Incorrect method type.                                                                                            |
| `500 Internal Server Error` | Database error occurred.                                                                                          |

warning

**Input Requirements for Optimization**

When sending a request for route optimization, the following constraints must be respected:

**Orders**

* Each order must include a **valid set of coordinates**.
* For each order’s `timeWindows`, the **end time must be greater than the start time**.
* **RoundRoute**: requires **at least 1 order** and **1 departure**.
* **CustomEnd**: requires **at least 1 order**, **1 departure**, and **1 destination**.
* **EndAnywhere**: requires **at least 2 orders** and **1 departure**. More details on `route type`: [**Configuration Parameters**](/docs/cloud-rest-api/guides/fleet-management/core-concepts/configuration-parameters.md#configuration-parameters-structure)

**Vehicles**

* At least **1 vehicle** must be defined.

* **Vehicle type is mandatory** and cannot be empty.

* Each vehicle’s `startTime` must always be **less than its `endTime`**.

* Vehicle constraints must be provided either:

  <!-- -->

  * **One globally** (applies to all vehicles), or
  * **Individually for each vehicle** (same number of constraints as vehicles). More details: [**Vehicle Constraints**](/docs/cloud-rest-api/guides/fleet-management/core-concepts/vehicle-constraints.md#vehicle-constraints-structure)

⚠️ If any of these requirements are not met, the solver will return an **input error**:<br />`400 - Bad Request` (Invalid input or missing required fields).

#### Example:[​](#example-1 "Direct link to Example:")

* **Request Body:**

- Schema View
- JSON Example
- JSON View

* ▶`configurationParameters`(

  <!-- -->

  object

  <!-- -->

  )

  Configuration parameters for the optimization.

* ▶`departures`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of departure locations for the optimization.

* ▶`destinations`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of destination locations for the optimization (optional).

* ▶`orders`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of orders to optimize.

* ▶`vehicles`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of vehicles assigned to the optimization.

* ▶`vehiclesConstraints`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of vehicle constraints applied in the optimization.

* `matrixBuildType`(

  <!-- -->

  integer

  <!-- -->

  )

  Defines how the distance matrix is built. **Possible values:**

  * `0` - Set by user using 'matrices' field`matrices` field
  * `1` - Real road map distances and times (default) distances and times

* `matrices`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  Contains distance and time matrices, required when matrixBuildType is set to 0 (optional).

```json
{
  "configurationParameters": {
    "name": "Paris - test optimization",
    "ignoreTimeWindow": false,
    "allowDroppingOrders": false,
    "groupingOrders": false,
    "balancedRoutes": 0,
    "optimizationCriterion": 0,
    "arrangeCriterion": 0,
    "optimizationQuality": 2,
    "maxTimeToOptimize": 300,
    "maxWaitTime": 18000,
    "routeType": 0,
    "restrictions": 0,
    "distanceUnit": 0,
    "orderSequenceOptions": []
  },
  "orders": [
    {
      "alias": "Customer 1",
      "location": [
        48.870852,
        2.356148
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 2",
      "location": [
        48.827327,
        2.342267
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 3",
      "location": [
        48.88025,
        2.299601
      ],
      "type": 0,
      "numberOfPackages": 3,
      "weight": 5.1,
      "cube": 2.5,
      "timeWindow": [
        770,
        1020
      ],
      "serviceTime": 0,
      "revenue": 12,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 4",
      "location": [
        48.845198,
        2.402896
      ],
      "type": 1,
      "numberOfPackages": 8,
      "weight": 15.4,
      "cube": 5.8,
      "timeWindow": [
        753,
        1036
      ],
      "serviceTime": 0,
      "revenue": 2.7,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 5",
      "location": [
        48.897163,
        2.292865
      ],
      "type": 0,
      "numberOfPackages": 9,
      "weight": 16.2,
      "cube": 8.4,
      "timeWindow": [
        736,
        1086
      ],
      "serviceTime": 0,
      "revenue": 7.5,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 6",
      "location": [
        48.90092,
        2.400039
      ],
      "type": 1,
      "numberOfPackages": 9,
      "weight": 16.5,
      "cube": 9.7,
      "timeWindow": [
        786,
        1053
      ],
      "serviceTime": 0,
      "revenue": 10,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 7",
      "location": [
        48.860914,
        2.310625
      ],
      "type": 0,
      "numberOfPackages": 5,
      "weight": 7.5,
      "cube": 2.6,
      "timeWindow": [
        820,
        1020
      ],
      "serviceTime": 0,
      "revenue": 13.4,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 8",
      "location": [
        48.827865,
        2.379216
      ],
      "type": 1,
      "numberOfPackages": 11,
      "weight": 12.1,
      "cube": 4.6,
      "timeWindow": [
        753,
        1086
      ],
      "serviceTime": 0,
      "revenue": 14.7,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 9",
      "location": [
        48.887096,
        2.283513
      ],
      "type": 1,
      "numberOfPackages": 6,
      "weight": 5.2,
      "cube": 1.5,
      "timeWindow": [
        770,
        1070
      ],
      "serviceTime": 0,
      "revenue": 2.9,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 10",
      "location": [
        48.896894,
        2.321586
      ],
      "type": 0,
      "numberOfPackages": 13,
      "weight": 6.3,
      "cube": 7.5,
      "timeWindow": [
        836,
        1053
      ],
      "serviceTime": 0,
      "revenue": 8.1,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 11",
      "location": [
        48.870449,
        2.342204
      ],
      "type": 0,
      "numberOfPackages": 10,
      "weight": 8,
      "cube": 4.1,
      "timeWindow": [
        903,
        1020
      ],
      "serviceTime": 0,
      "revenue": 6.2,
      "priority": 0,
      "customData": ""
    },
    {
      "alias": "Customer 12",
      "location": [
        48.895658,
        2.344043
      ],
      "type": 0,
      "numberOfPackages": 6,
      "weight": 4.8,
      "cube": 11.5,
      "timeWindow": [
        870,
        1020
      ],
      "serviceTime": 0,
      "revenue": 2.3,
      "priority": 0,
      "customData": ""
    }
  ],
  "departures": [
    {
      "alias": "Depot 1",
      "location": [
        48.870569,
        2.356448
      ]
    },
    {
      "alias": "Depot 2",
      "location": [
        48.82674,
        2.342116
      ]
    }
  ],
  "destinations": [],
  "vehicles": [
    {
      "name": "Car vehicle 1",
      "type": 0,
      "maxLoadWeight": 60,
      "maxLoadCube": 50,
      "startTime": 420,
      "endTime": 1439,
      "availableBreaks": "AA-123-AA",
      "licensePlate": 6.5,
      "consumption": [
        {
          "duration": 1800,
          "timeWindows": [
            [
              720,
              780
            ],
            [
              900,
              960
            ]
          ]
        }
      ]
    },
    {
      "name": "Car vehicle 2",
      "type": 0,
      "maxLoadWeight": 60,
      "maxLoadCube": 50,
      "startTime": 420,
      "endTime": 1439,
      "availableBreaks": "AA-124-AA",
      "licensePlate": 6.5,
      "consumption": [
        {
          "duration": 1800,
          "timeWindows": [
            [
              720,
              780
            ],
            [
              900,
              960
            ]
          ]
        }
      ]
    }
  ],
  "vehiclesConstraints": [
    {
      "startDate": 1596758400000,
      "maxNumberOfPackages": 53,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 99999999,
      "minDistance": 0,
      "maxDistance": 99999999,
      "maxRevenue": 85
    }
  ],
  "matrixBuildType": 1
}

```

```json
{
  "configurationParameters": {
    "name": "string",
    "ignoreTimeWindow": false,
    "allowDroppingOrders": false,
    "groupingOrders": false,
    "balancedRoutes": 0,
    "optimizationCriterion": 0,
    "arrangeCriterion": 0,
    "optimizationQuality": 0,
    "maxTimeToOptimize": 0,
    "maxWaitTime": 0,
    "routeType": 0,
    "restrictions": 0,
    "distanceUnit": 0,
    "orderSequenceOptions": []
  },
  "orders": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "departures": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ]
    }
  ],
  "destinations": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ]
    }
  ],
  "vehicles": [
    {
      "name": "string",
      "type": 0,
      "maxLoadWeight": 0,
      "maxLoadCube": 0,
      "startTime": 0,
      "endTime": 1439,
      "availableBreaks": "string",
      "licensePlate": 0
    }
  ],
  "vehiclesConstraints": [
    {
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ],
  "matrixBuildType": 1
}

```

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* `id`(

  <!-- -->

  integer

  <!-- -->

  )

  Unique identifier for the request.

* `optimizationId`(

  <!-- -->

  integer

  <!-- -->

  )

  The ID of the associated optimization. Only present for optimization requests.

* `routeId`(

  <!-- -->

  integer

  <!-- -->

  )

  The ID of the associated route. Only present for route requests.

* `status`(

  <!-- -->

  integer

  <!-- -->

  )

  Current status of the request:

  <br />

  `0` - Created

  <br />

  `1` - Pending

  <br />

  `2` - Finished

  <br />

  `3` - Canceled

* `message`(

  <!-- -->

  string

  <!-- -->

  )

  Status message for the request.

* `creationTimestamp`(

  <!-- -->

  integer

  <!-- -->

  )

  Timestamp when the request was created.

```json
{
  "id": 23567,
  "solutionId": 46587,
  "status": 0,
  "message": "Operation running...please wait!",
  "creationTimestamp": 1747786578
}

```

```json
{
  "id": 0,
  "solutionId": 0,
  "status": 0,
  "message": "string",
  "creationTimestamp": 0
}

```

***

### 3. Get Solution[​](#3-get-solution "Direct link to 3. Get Solution")

**Description:** Retrieves the solution for a previously submitted `/optimize` request using the request ID. This endpoint is used after submitting an optimization request to get the final routing solution once processing is complete.

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `GET /fleetmanagement/optimize/{id}/solution`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **Path Parameter:**

  * `id` (integer, \**required*) - The ID returned from the initial `/optimize` req

* **Returned error codes:**

| Error Code                  | Description                                         |
| --------------------------- | --------------------------------------------------- |
| `200 Successful`            | Successful operation, solution retrieved.           |
| `400 Bad Request`           | Invalid requestId or missing required parameters.   |
| `401 Unauthorized`          | API key is missing or invalid.                      |
| `404 Not Found`             | Request ID not found or optimization not completed. |
| `405 Method Not Allowed`    | Incorrect method type.                              |
| `425 Too Early`             | Request not finished.                               |
| `500 Internal Server Error` | Database error occurred.                            |

:::info Note This endpoint is used in conjunction with the `/optimize` endpoint. After submitting an optimization request, use the returned `requestId` to retrieve the solution once processing is complete. :::

#### Example:[​](#example-2 "Direct link to Example:")

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* ▶`drpppedOrders`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of orders excluded from the optimization because no feasible solution was found.

* ▶`routes`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of optimized routes

```json
{
  "droppedOrders": [],
  "routes": [
    {
      "breaks": [
        {
          "duration": 1800,
          "startTime": 720
        }
      ],
      "orders": [
        {
          "alias": "Customer 11",
          "location": [
            48.870852,
            2.356148
          ],
          "matchedLocation": [
            48.8701825,
            2.3423565625
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 10,
          "weight": 8,
          "cube": 4.1,
          "revenue": 6.2,
          "serviceTime": 0,
          "timeWindow": [
            903,
            1020
          ],
          "indexInRoute": 0,
          "indexInOptimization": 10,
          "arrivalTime": 1596812580000,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 34,
          "weightAtArrival": 49.2,
          "cubeAtArrival": 21.6,
          "traveledDistance": 1.4171849,
          "revenueAtArrival": 0,
          "deliveredNumberOfPackages": 10,
          "deliveredWeight": 8,
          "deliveredCube": 4.1,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 6",
          "location": [
            48.827327,
            2.342267
          ],
          "matchedLocation": [
            48.9005959375,
            2.4000475
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 9,
          "weight": 16.5,
          "cube": 9.7,
          "revenue": 10,
          "serviceTime": 0,
          "timeWindow": [
            786,
            1053
          ],
          "indexInRoute": 1,
          "indexInOptimization": 5,
          "arrivalTime": 1596813655241,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 44,
          "weightAtArrival": 57.2,
          "cubeAtArrival": 25.7,
          "traveledDistance": 7.2696328,
          "revenueAtArrival": 6.2,
          "collectedNumberOfPackages": 9,
          "collectedWeight": 16.5,
          "collectedCube": 9.7,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 4",
          "location": [
            48.88025,
            2.299601
          ],
          "matchedLocation": [
            48.8452625,
            2.4027009375
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 8,
          "weight": 15.4,
          "cube": 5.8,
          "revenue": 2.7,
          "serviceTime": 0,
          "timeWindow": [
            753,
            1036
          ],
          "indexInRoute": 2,
          "indexInOptimization": 3,
          "arrivalTime": 1596814512563,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 35,
          "weightAtArrival": 40.7,
          "cubeAtArrival": 16,
          "traveledDistance": 13.1220808,
          "revenueAtArrival": 16.2,
          "collectedNumberOfPackages": 8,
          "collectedWeight": 15.4,
          "collectedCube": 5.8,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 8",
          "location": [
            48.845198,
            2.402896
          ],
          "matchedLocation": [
            48.82792,
            2.3791415625
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 11,
          "weight": 12.1,
          "cube": 4.6,
          "revenue": 14.7,
          "serviceTime": 0,
          "timeWindow": [
            753,
            1086
          ],
          "indexInRoute": 3,
          "indexInOptimization": 7,
          "arrivalTime": 1596815042263,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 27,
          "weightAtArrival": 25.3,
          "cubeAtArrival": 10.2,
          "traveledDistance": 18.9745293,
          "revenueAtArrival": 18.9,
          "collectedNumberOfPackages": 11,
          "collectedWeight": 12.1,
          "collectedCube": 4.6,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 7",
          "location": [
            48.897163,
            2.292865
          ],
          "matchedLocation": [
            48.86112,
            2.310630625
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 5,
          "weight": 7.5,
          "cube": 2.6,
          "revenue": 13.4,
          "serviceTime": 0,
          "timeWindow": [
            820,
            1020
          ],
          "indexInRoute": 4,
          "indexInOptimization": 6,
          "arrivalTime": 1596816069637,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 16,
          "weightAtArrival": 13.2,
          "cubeAtArrival": 5.6,
          "traveledDistance": 24.8269768,
          "revenueAtArrival": 33.6,
          "deliveredNumberOfPackages": 5,
          "deliveredWeight": 7.5,
          "deliveredCube": 2.6,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 3",
          "location": [
            48.90092,
            2.400039
          ],
          "matchedLocation": [
            48.8802215625,
            2.2997153125
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 3,
          "weight": 5.1,
          "cube": 2.5,
          "revenue": 12,
          "serviceTime": 0,
          "timeWindow": [
            770,
            1020
          ],
          "indexInRoute": 5,
          "indexInOptimization": 2,
          "arrivalTime": 1596816563007,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 21,
          "weightAtArrival": 20.7,
          "cubeAtArrival": 8.2,
          "traveledDistance": 30.6794243,
          "revenueAtArrival": 47,
          "deliveredNumberOfPackages": 3,
          "deliveredWeight": 5.1,
          "deliveredCube": 2.5,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 9",
          "location": [
            48.860914,
            2.310625
          ],
          "matchedLocation": [
            48.886894375,
            2.2838003125
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 6,
          "weight": 5.2,
          "cube": 1.5,
          "revenue": 2.9,
          "serviceTime": 0,
          "timeWindow": [
            770,
            1070
          ],
          "indexInRoute": 6,
          "indexInOptimization": 8,
          "arrivalTime": 1596816932267,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 24,
          "weightAtArrival": 25.8,
          "cubeAtArrival": 10.7,
          "traveledDistance": 36.5318718,
          "revenueAtArrival": 59,
          "collectedNumberOfPackages": 6,
          "collectedWeight": 5.2,
          "collectedCube": 1.5,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 5",
          "location": [
            48.827865,
            2.379216
          ],
          "matchedLocation": [
            48.89706375,
            2.29247
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 9,
          "weight": 16.2,
          "cube": 8.39,
          "revenue": 7.5,
          "serviceTime": 0,
          "timeWindow": [
            736,
            1086
          ],
          "indexInRoute": 7,
          "indexInOptimization": 4,
          "arrivalTime": 1596817262381,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 18,
          "weightAtArrival": 20.6,
          "cubeAtArrival": 9.2,
          "traveledDistance": 42.3843193,
          "revenueAtArrival": 61.9,
          "deliveredNumberOfPackages": 9,
          "deliveredWeight": 16.2,
          "deliveredCube": 8.39,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 10",
          "location": [
            48.887096,
            2.283513
          ],
          "matchedLocation": [
            48.8971759375,
            2.321263125
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 13,
          "weight": 6.3,
          "cube": 7.5,
          "revenue": 8.1,
          "serviceTime": 0,
          "timeWindow": [
            836,
            1053
          ],
          "indexInRoute": 8,
          "indexInOptimization": 9,
          "arrivalTime": 1596817690016,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 27,
          "weightAtArrival": 36.8,
          "cubeAtArrival": 17.59,
          "traveledDistance": 48.2367668,
          "revenueAtArrival": 69.4,
          "deliveredNumberOfPackages": 13,
          "deliveredWeight": 6.3,
          "deliveredCube": 7.5,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 12",
          "location": [
            48.896894,
            2.321586
          ],
          "matchedLocation": [
            48.8958034375,
            2.3440403125
          ],
          "type": 0,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 6,
          "weight": 4.8,
          "cube": 11.5,
          "revenue": 2.3,
          "serviceTime": 0,
          "timeWindow": [
            870,
            1020
          ],
          "indexInRoute": 9,
          "indexInOptimization": 11,
          "arrivalTime": 1596817984460,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 40,
          "weightAtArrival": 43.1,
          "cubeAtArrival": 25.09,
          "traveledDistance": 54.0892143,
          "revenueAtArrival": 77.5,
          "deliveredNumberOfPackages": 6,
          "deliveredWeight": 4.8,
          "deliveredCube": 11.5,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        },
        {
          "alias": "Customer 1",
          "location": [
            48.870449,
            2.342204
          ],
          "matchedLocation": [
            48.8707784375,
            2.3565665625
          ],
          "type": 1,
          "priority": 0,
          "customData": "",
          "numberOfPackages": 0,
          "weight": 0,
          "cube": 0,
          "revenue": 0,
          "serviceTime": 0,
          "timeWindow": [
            420,
            1086
          ],
          "indexInRoute": 10,
          "indexInOptimization": 0,
          "arrivalTime": 1596818617911,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 46,
          "weightAtArrival": 47.9,
          "cubeAtArrival": 36.59,
          "traveledDistance": 59.9416618,
          "revenueAtArrival": 79.8,
          "collectedNumberOfPackages": 0,
          "collectedWeight": 0,
          "collectedCube": 0,
          "distanceToNextOrder": 5.8524479866,
          "timeToNextOrder": 972
        }
      ],
      "departure": {
        "alias": "Depot 2",
        "location": [
          48.82679375,
          2.3420853125
        ],
        "matchedLocation": [
          48.82679375,
          2.3420853125
        ],
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "departureTime": 1596783600000,
        "timeToNext": 12122,
        "distanceToNext": 1.1342
      },
      "destination": {
        "alias": "Depot 2",
        "location": [
          48.82679375,
          2.3420853125
        ],
        "matchedLocation": [
          48.82679375,
          2.3420853125
        ],
        "arrivalTime": 1596818617911
      },
      "vehicle": {
        "name": "Car vehicle 1",
        "type": 0,
        "maxLoadWeight": 60,
        "maxLoadCube": 50,
        "startTime": 420,
        "endTime": 1439,
        "availableBreaks": "AA-123-AA",
        "licensePlate": 6.5,
        "consumption": [
          {
            "duration": 1800,
            "timeWindows": [
              [
                720,
                780
              ],
              [
                900,
                960
              ]
            ]
          }
        ]
      },
      "vehicleConstraints": {
        "startDate": 1596758400000,
        "maxNumberOfPackages": 53,
        "minNumberOfOrders": 0,
        "maxNumberOfOrders": 99999999,
        "minDistance": 0,
        "maxDistance": 99999999,
        "maxRevenue": 85
      },
      "totalDistance": 65.7941,
      "totalTime": 1597135480,
      "totalServiceTime": 0,
      "totalWaitTime": 0,
      "creationTimestamp": 1756296705030,
      "neededFuel": 4.2766175,
      "matrixBuildType": 1
    }
  ]
}

```

```json
{
  "droppedOrders": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "routes": [
    {
      "breaks": [],
      "orders": [
        {
          "alias": "string",
          "location": [
            0,
            0
          ],
          "matchedLocation": [
            0,
            0
          ],
          "type": 0,
          "priority": 0,
          "customData": "string",
          "numberOfPackages": 0,
          "weight": 0,
          "cube": 0,
          "revenue": 0,
          "serviceTime": 0,
          "timeWindow": [
            0,
            0
          ],
          "indexInRoute": 0,
          "indexInOptimization": 0,
          "arrivalTime": 0,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 0,
          "weightAtArrival": 0,
          "cubeAtArrival": 0,
          "traveledDistance": 0,
          "revenueAtArrival": 0,
          "deliveredNumberOfPackages": 0,
          "deliveredWeight": 0,
          "deliveredCube": 0,
          "distanceToNextOrder": 0,
          "timeToNextOrder": 0
        }
      ],
      "departure": {
        "alias": "string",
        "location": [
          0,
          0
        ],
        "matchedLocation": [
          0,
          0
        ],
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "departureTime": 0,
        "timeToNext": 0,
        "distanceToNext": 0
      },
      "destination": {
        "alias": "string",
        "location": [
          0,
          0
        ],
        "matchedLocation": [
          0,
          0
        ],
        "arrivalTime": 0
      },
      "vehicle": {
        "name": "string",
        "type": 0,
        "maxLoadWeight": 0,
        "maxLoadCube": 0,
        "startTime": 0,
        "endTime": 1439,
        "availableBreaks": "string",
        "licensePlate": 0
      },
      "vehicleConstraints": {
        "startDate": 0,
        "maxNumberOfPackages": 0,
        "minNumberOfOrders": 0,
        "maxNumberOfOrders": 0,
        "minDistance": 0,
        "maxDistance": 0,
        "maxRevenue": 0
      },
      "totalDistance": 0,
      "totalTime": 0,
      "totalServiceTime": 0,
      "totalWaitTime": 0,
      "creationTimestamp": 0,
      "neededFuel": 0,
      "matrixBuildType": 1
    }
  ]
}

```

***

### 4. Optimize landmarks[​](#4-optimize-landmarks "Direct link to 4. Optimize landmarks")

**Description:** Receives a list of coordinates and a vehicle type, then optimizes them by creating a route for the given coordinates.

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `POST /fleetmanagement/optimize/landmarks`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **Returned error codes:**

| Error Code                  | Description                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `200 Successful`            | Successful operation.                                                                                             |
| `400 Bad Request`           | Invalid input or missing required fields.                                                                         |
| `401 Unauthorized`          | API key is missing or invalid.                                                                                    |
| `404 Not Found`             | No solution found, please try changing the constraints, or adding more vehicles, there may be more possibilities. |
| `405 Method Not Allowed`    | Incorrect method type.                                                                                            |
| `500 Internal Server Error` | Database error occurred.                                                                                          |

warning

**Input Requirements for Landmark Optimization**

When sending a request for a landmark optimization, the following constraints must be respected:

* A minimum of **3 points** is required.
* The **first point** is always treated as the **starting point (departure)**.
* The route type is `EndAnywhere`, the last point in the optimized route is treated as **destination**.
* **Vehicle type is mandatory** for route calculation and must not be empty.

More details on `route type`: [**Configuration Parameters**](/docs/cloud-rest-api/guides/fleet-management/core-concepts/configuration-parameters.md#configuration-parameters-structure)

⚠️ If any of these requirements are not met, the solver will return an **input error**:<br />`400 - Bad Request` (Invalid input or missing required fields).

#### Example:[​](#example-3 "Direct link to Example:")

* **Request Body:**

- Schema View
- JSON Example
- JSON View

* `vehicleType`(

  <!-- -->

  integer

  <!-- -->

  )

  Vehicle type - Specifies the vehicle's type.

  <br />

  <br />

  `0` - Car

  <br />

  `1` - Pedestrian

  <br />

  `2` - E-Bike

  <br />

  `3` - Truck

  <br />

  `4` - Bike

* ▶`locations`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of coordinates that will be optimized to determine the best route.

```json
{
  "vehicleType": 1,
  "locations": [
    [48.869900, 2.344389],
    [48.870214, 2.358400],
    [48.868321, 2.341789],
    [48.873201, 2.350999],
    [48.867842, 2.351328],
    [48.866749, 2.354210],
    [48.869123, 2.357890],
    [48.865234, 2.346721],
    [48.872830, 2.360402],
    [48.871567, 2.349012]
  ]
}

```

```json
{
  "vehicleType": 0,
  "locations": [
    [0.0, 0.0],
    [0.0, 0.0],
    [0.0, 0.0],
    [0.0, 0.0],
    [0.0, 0.0],
    [0.0, 0.0],
    [0.0, 0.0]
  ]
}

```

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* `locationIndexes`(

  <!-- -->

  array\[integer]

  <!-- -->

  )

  Array of reordered indexes representing the optimized sequence.

  <br />

  **Values:**

  <br />

  • Non-negative integers (0 to n-1): Position in optimized sequence

  <br />

  • `-1`: Unassigned/dropped location

* `droppedIndexes`(

  <!-- -->

  array\[integer]

  <!-- -->

  )

  List of indexes of the orders excluded from the optimization because no feasible solution was found.

  <br />

```json
{
  "locationIndexes": [9, 3, 0, 2, 7, 4, 5, 6, 1, 8]
  "droppedIndexes": []
}

```

```json
{
  "locationIndexes": [-1, -1, -1, -1, -1, -1, -1, -1],
  "droppedIndexes": [-1, -1]
}

```

***
