Route

The Route Rest API allows you to manage route data, including retrieving, updating, and deleting routes. This Rest API supports multiple request types to interact with route solutions and optimization processes.

Route Object Fields

Field	Type	Description
`id`	Integer	Unique identifier for the route.
`optimizationId`	Integer	ID of the associated optimization.
`idVehicle`	Integer	ID of the vehicle assigned to this route.
`matrixBuiltType`	Integer	Distance calculation method: `0` - Set by user using "matrices" field `1` - Real road distances and times
`matrices`	Array	Contains distance and time matrices (set only if `matrixBuiltType = 0`).
`configurationParameters`	Object	Configuration parameters for the route.
`orders`	Array	List of orders included in the route.
`breaks`	Array	List of breaks taken during route execution. Each break contains: `startTime` (Integer) - Start time of the break in minutes from midnight `duration` (Integer) - Duration of the break in seconds
`departure`	Object	Details of the departure location.
`destination`	Object	Details of the destination location.
`vehicleConstraints`	Array	List of vehicle constraints applied to the route.
`rideStatus`	Integer	Current status of the ride. Possible values: • `0` - Finished: The ride is completed • `1` - New: The ride is ready to start • `2` - Started: The ride has begun • `3` - Canceled by Driver: The ride was canceled by the driver • `4` - Canceled by Fleet: The ride was canceled by fleet management
`totalDistance`	Float	Total route distance (in kilometers or miles based on settings).
`totalTime`	Integer	Total duration of the route (in seconds).
`totalServiceTime`	Integer	Total service time for all orders in the route (in seconds).
`totalWaitTime`	Integer	Total wait time for the route (in seconds).
`neededFuel`	Float	Total fuel consumption for the route (liters or kWh based on fuel type).
`price`	Float	Total cost of the route, calculated based on fuel consumption and distance.
`shape`	String	Encoded polyline or list of locations representing the route.
`creationTimestamp`	Integer	Timestamp of when the route was created.

Endpoints

1. Get All Routes

Description: Fetches all available routes.

Method: GET
Endpoint: /routes
Headers:
- Authorization: YOUR_API_KEY
URL: https://fleetmanagement.magiclaneapis.com/v1/routes
Query Parameters:
- search (string, optional) - General search term.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	The values sent for page and per_page parameters are incorrect; should be greater than 0.
`401 Unauthorized`	API key is missing or invalid.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Example:

Response Body: (error code 200)

Schema View
JSON Example
JSON View

id(integer)
Unique identifier for the route.
optimizationId(integer)
ID of the associated optimization.
▶configurationParameters(object)
Configuration parameters for the route.
▶vehicleConstraints(array[object])
List of vehicle constraints applied to the route.
rideStatus(integer)
Current status of the ride.
Possible values:
• 0 - Finished: The ride is completed
• 1 - New: The ride is ready to start
• 2 - Started: The ride has begun
• 3 - Canceled by Driver: The ride was canceled by the driver
• 4 - Canceled by Fleet: The ride was canceled by fleet management
▶vehicle(object)
Vehicle assigned to this route.
▶departure(object)
Details of the departure location.
▶destination(object)
Details of the destination location.
shape(string)
Encoded polyline or list of locations representing the route.
creationTimestamp(integer)
Timestamp of when the route was created.
neededFuel(float)
Total fuel consumption for the route (liters or kWh based on fuel type).
matrixBuildType(integer)
Defines how the distance matrix is built. Possible values:
- 0 - Set by user using 'matrices' fieldmatrices field
- 1 - Real road map distances and times (default) distances and times
price(float)
Total cost of the route, calculated based on fuel consumption and distance.
totalWaitTime(integer)
Total wait time for the route (in seconds).
totalServiceTime(integer)
Total service time for all orders in the route (in seconds).
▶orders(array[object])
List of orders included in the route.
▶breaks(array[object])
List of breaks taken during the route execution.
totalTime(integer)
Total duration of the route (in seconds).
totalDistance(float)
Total route distance (in kilometers or miles based on settings).
matrices(array[object])
Contains distance and time matrices (set only if matrixBuildType = 0).

{
  "routes": [
    {
      "id": 255145,
      "optimizationId": 139950,
      "configurationParameters": {
        "name": "Paris - test optimization - Part 1",
        "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": []
      },
      "vehicleConstraints": {
        "fuelPrice": 1.0700000524520874,
        "startDate": 1596758400000,
        "maxNumberOfPackages": 53,
        "minNumberOfOrders": 0,
        "maxNumberOfOrders": 99999999,
        "minDistance": 0,
        "maxDistance": 100000000,
        "maxRevenue": 85
      },
      "rideStatus": 1,
      "vehicle": {
        "id": 139813,
        "type": 0,
        "status": 0,
        "name": "Car vehicle",
        "manufacturer": "",
        "model": "",
        "fuelType": 2,
        "lastPosition": [
          48.868507,
          2.359727
        ],
        "consumption": 6.5,
        "plate": "",
        "maxLoadWeight": 60,
        "maxLoadCube": 50,
        "height": 0,
        "width": 0,
        "weight": 0,
        "length": 0,
        "axleLoad": 0,
        "fixedCost": 0,
        "costPerHour": 10,
        "startTime": 420,
        "endTime": 1439,
        "availableBreaks": [
          {
            "duration": 1800,
            "timeWindows": [
              [
                720,
                780
              ],
              [
                900,
                960
              ]
            ]
          }
        ]
      },
      "departure": {
        "depotId": 0,
        "alias": "Departure2",
        "location": [
          48.82674,
          2.342116
        ],
        "address": {
          "country": "France",
          "state": "",
          "county": "Nouvelle-Aquitaine",
          "city": "Poitiers",
          "postalCode": "86000",
          "streetName": "Boulevard Chasseigne",
          "streetNumber": "34"
        },
        "matchedLocation": [
          48.82679375,
          2.3420853125
        ],
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "timeToNext": 12,
        "distanceToNext": 0.07019499689340591,
        "departureTime": 1596783600000
      },
      "destination": {
        "alias": "Departure2",
        "location": [
          48.82674,
          2.342116
        ],
        "address": {
          "country": "France",
          "state": "",
          "county": "Nouvelle-Aquitaine",
          "city": "Poitiers",
          "postalCode": "86000",
          "streetName": "Boulevard Chasseigne",
          "streetNumber": "34"
        },
        "matchedLocation": [
          48.82679375,
          2.3420853125
        ],
        "traveledDistance": 0.6638350486755371,
        "arrivalTime": 1596783691000
      },
      "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
      "creationTimestamp": 1744096606089,
      "neededFuel": 0.04314928129315376,
      "matrixBuildType": 1,
      "price": 0.04616973176598549,
      "totalWaitTime": 0,
      "totalServiceTime": 0,
      "orders": [
        {
          "orderInfo": {
            "id": 933799,
            "creationTimestamp": 1744096603223,
            "customerInfo": {
              "id": 1839506,
              "alias": "",
              "firstName": "",
              "lastName": "",
              "address": {
                "country": "",
                "state": "",
                "county": "",
                "city": "",
                "postalCode": "",
                "streetName": "",
                "streetNumber": ""
              },
              "email": "c1@yahoo.com",
              "phoneNumber": "+12025550181",
              "location": [
                48.827327,
                2.342267
              ],
              "customData": ""
            },
            "location": [
              48.827327,
              2.342267
            ],
            "alias": "",
            "firstName": "",
            "lastName": "",
            "address": {
              "country": "",
              "state": "",
              "county": "",
              "city": "",
              "postalCode": "",
              "streetName": "",
              "streetNumber": ""
            },
            "phoneNumber": "+12025550181",
            "customData": "",
            "type": 0,
            "status": 1,
            "state": 1,
            "priority": 0,
            "numberOfPackages": 0,
            "weight": 0,
            "cube": 0,
            "revenue": 0,
            "timeWindow": [
              420,
              1086
            ],
            "serviceTime": 0,
            "depotId": 0
          },
          "matchedLocation": [
            48.82734625,
            2.3421875
          ],
          "actualLocation": [
            0,
            0
          ],
          "indexInRoute": 0,
          "indexInOptimization": 1,
          "arrivalTime": 1596783612000,
          "timeToNextOrder": 79,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 0,
          "collectedNumberOfPackages": 0,
          "deliveredNumberOfPackages": 0,
          "weightAtArrival": 0,
          "collectedWeight": 0,
          "deliveredWeight": 0,
          "cubeAtArrival": 0,
          "collectedCube": 0,
          "deliveredCube": 0.07019499689340591,
          "traveledDistance": 0.5936400294303894,
          "distanceToNextOrder": 0,
          "revenueAtArrival": 0
        }
      ],
      "breaks": [
        {
          "duration": 1800,
          "startTime": 720
        }
      ],
      "totalTime": 91,
      "totalDistance": 0.6638350486755371
    }
  ]
}

{
  "routes": [
    {
      "id": 0,
      "optimizationId": 0,
      "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": []
      },
      "vehicleConstraints": [
        {
          "fuelPrice": 0,
          "startDate": 0,
          "maxNumberOfPackages": 0,
          "minNumberOfOrders": 0,
          "maxNumberOfOrders": 0,
          "minDistance": 0,
          "maxDistance": 0,
          "maxRevenue": 0
        }
      ],
      "rideStatus": 0,
      "vehicle": {
        "id": 0,
        "type": 0,
        "status": 0,
        "name": "string",
        "manufacturer": "string",
        "model": "string",
        "fuelType": 0,
        "lastPosition": [
          0,
          0
        ],
        "consumption": 0,
        "plate": "string",
        "maxLoadWeight": 0,
        "maxLoadCube": 0,
        "height": 0,
        "width": 0,
        "weight": 0,
        "length": 0,
        "axleLoad": 0,
        "fixedCost": 0,
        "costPerHour": 0,
        "startTime": 0,
        "endTime": 0,
        "availableBreaks": []
      },
      "departure": {
        "depotId": 0,
        "alias": "string",
        "location": [
          0,
          0
        ],
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "matchedLocation": [
          0,
          0
        ],
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "timeToNext": 0,
        "distanceToNext": 0,
        "departureTime": 0
      },
      "destination": {
        "alias": "string",
        "location": [
          0,
          0
        ],
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "matchedLocation": [
          0,
          0
        ],
        "traveledDistance": 0,
        "arrivalTime": 0
      },
      "shape": "string",
      "creationTimestamp": 0,
      "neededFuel": 0,
      "matrixBuildType": 1,
      "price": 0,
      "totalWaitTime": 0,
      "totalServiceTime": 0,
      "orders": {
        "orders": [
          {
            "id": 0,
            "creationTimestamp": 0,
            "customerInfo": {
              "id": 0,
              "alias": "string",
              "firstName": "string",
              "lastName": "string",
              "address": {
                "country": "string",
                "state": "string",
                "county": "string",
                "city": "string",
                "postalCode": "string",
                "streetName": "string",
                "streetNumber": "string",
                "extra": "string"
              },
              "email": "string",
              "phoneNumber": "string",
              "location": [
                0,
                0
              ],
              "customData": "string"
            },
            "location": [
              0,
              0
            ],
            "alias": "string",
            "firstName": "string",
            "lastName": "string",
            "address": {
              "country": "string",
              "state": "string",
              "county": "string",
              "city": "string",
              "postalCode": "string",
              "streetName": "string",
              "streetNumber": "string",
              "extra": "string"
            },
            "phoneNumber": "string",
            "customData": "string",
            "type": 0,
            "status": 0,
            "state": 1,
            "priority": 0,
            "numberOfPackages": 0,
            "weight": 0,
            "cube": 0,
            "revenue": 0,
            "timeWindow": [
              0,
              0
            ],
            "serviceTime": 0,
            "depotId": 0
          }
        ]
      },
      "breaks": [],
      "totalTime": 0,
      "totalDistance": 0
    }
  ]
}

2. Get a Route by ID

Description: Retrieves a specific route by its ID.

Method: GET
Endpoint: /routes/{id}
Headers:
- Authorization: YOUR_API_KEY
URL: https://fleetmanagement.magiclaneapis.com/v1/routes/{id}
Path Parameter:
- id (integer, *required) - The unique route ID.
Query Parameter:
- encodeShape (integer, optional)
  - 0 : The route's shape will not be encoded.
  - 1 (default) : The route's shape will be encoded.
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`	Route not found.
`405 Method Not Allowed`	Incorrect method type.
`425 Too Early`	Request not finished.
`500 Internal Server Error`	Database error occurred.

Example:

Response Body: (error code 200)

Schema View
JSON Example
JSON View

id(integer)
Unique identifier for the route.
optimizationId(integer)
ID of the associated optimization.
▶configurationParameters(object)
Configuration parameters for the route.
▶vehicleConstraints(array[object])
List of vehicle constraints applied to the route.
rideStatus(integer)
Current status of the ride.
Possible values:
• 0 - Finished: The ride is completed
• 1 - New: The ride is ready to start
• 2 - Started: The ride has begun
• 3 - Canceled by Driver: The ride was canceled by the driver
• 4 - Canceled by Fleet: The ride was canceled by fleet management
▶vehicle(object)
Vehicle assigned to this route.
▶departure(object)
Details of the departure location.
▶destination(object)
Details of the destination location.
shape(string)
Encoded polyline or list of locations representing the route.
creationTimestamp(integer)
Timestamp of when the route was created.
neededFuel(float)
Total fuel consumption for the route (liters or kWh based on fuel type).
matrixBuildType(integer)
Defines how the distance matrix is built. Possible values:
- 0 - Set by user using 'matrices' fieldmatrices field
- 1 - Real road map distances and times (default) distances and times
price(float)
Total cost of the route, calculated based on fuel consumption and distance.
totalWaitTime(integer)
Total wait time for the route (in seconds).
totalServiceTime(integer)
Total service time for all orders in the route (in seconds).
▶orders(array[object])
List of orders included in the route.
▶breaks(array[object])
List of breaks taken during the route execution.
totalTime(integer)
Total duration of the route (in seconds).
totalDistance(float)
Total route distance (in kilometers or miles based on settings).
matrices(array[object])
Contains distance and time matrices (set only if matrixBuildType = 0).

{
  "id": 255145,
  "optimizationId": 139950,
  "configurationParameters": {
    "name": "Paris - test optimization - Part 1",
    "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": []
  },
  "vehicleConstraints": {
    "fuelPrice": 1.0700000524520874,
    "startDate": 1596758400000,
    "maxNumberOfPackages": 53,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 100000000,
    "maxRevenue": 85
  },
  "rideStatus": 1,
  "vehicle": {
    "id": 139813,
    "type": 0,
    "status": 0,
    "name": "Car vehicle",
    "manufacturer": "",
    "model": "",
    "fuelType": 2,
    "lastPosition": [
      48.868507,
      2.359727
    ],
    "consumption": 6.5,
    "plate": "",
    "maxLoadWeight": 60,
    "maxLoadCube": 50,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 10,
    "startTime": 420,
    "endTime": 1439,
    "availableBreaks": [
      {
        "duration": 1800,
        "timeWindows": [
          [
            720,
            780
          ],
          [
            900,
            960
          ]
        ]
      }
    ]
  },
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591,
    "departureTime": 1596783600000
  },
  "destination": {
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "traveledDistance": 0.6638350486755371,
    "arrivalTime": 1596783691000
  },
  "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
  "creationTimestamp": 1744096606089,
  "neededFuel": 0.04314928129315376,
  "matrixBuildType": 1,
  "price": 0.04616973176598549,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": [
    {
      "orderInfo": {
        "id": 933799,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.82734625,
        2.3421875
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    }
  ],
  "breaks": [
    {
      "duration": 1800,
      "startTime": 720
    }
  ],
  "totalTime": 91,
  "totalDistance": 0.6638350486755371
}

{
  "id": 0,
  "optimizationId": 0,
  "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": []
  },
  "vehicleConstraints": [
    {
      "fuelPrice": 0,
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ],
  "rideStatus": 0,
  "vehicle": {
    "id": 0,
    "type": 0,
    "status": 0,
    "name": "string",
    "manufacturer": "string",
    "model": "string",
    "fuelType": 0,
    "lastPosition": [
      0,
      0
    ],
    "consumption": 0,
    "plate": "string",
    "maxLoadWeight": 0,
    "maxLoadCube": 0,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 0,
    "startTime": 0,
    "endTime": 0,
    "availableBreaks": []
  },
  "departure": {
    "depotId": 0,
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 0,
    "distanceToNext": 0,
    "departureTime": 0
  },
  "destination": {
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "traveledDistance": 0,
    "arrivalTime": 0
  },
  "shape": "string",
  "creationTimestamp": 0,
  "neededFuel": 0,
  "matrixBuildType": 1,
  "price": 0,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": {
    "orders": [
      {
        "id": 0,
        "creationTimestamp": 0,
        "customerInfo": {
          "id": 0,
          "alias": "string",
          "firstName": "string",
          "lastName": "string",
          "address": {
            "country": "string",
            "state": "string",
            "county": "string",
            "city": "string",
            "postalCode": "string",
            "streetName": "string",
            "streetNumber": "string",
            "extra": "string"
          },
          "email": "string",
          "phoneNumber": "string",
          "location": [
            0,
            0
          ],
          "customData": "string"
        },
        "location": [
          0,
          0
        ],
        "alias": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "phoneNumber": "string",
        "customData": "string",
        "type": 0,
        "status": 0,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          0,
          0
        ],
        "serviceTime": 0,
        "depotId": 0
      }
    ]
  },
  "breaks": [],
  "totalTime": 0,
  "totalDistance": 0
}

3. Update a Route

Description: Routes can be updated with new parameters, such as vehicle or constraints. Make changes on Route and return the new solution after reptimizing the changed route.

Method: PUT
Endpoint: /routes/{id}
Headers:
- Authorization: YOUR_API_KEY
- Content-Type: application/json
URL: https://fleetmanagement.magiclaneapis.com/v1/routes/{id}
Path Parameter:
- id (integer) - The unique route ID.
Query Parameter:
- encodeShape (integer) - 0: The route's shape will not be encoded. 1:(default) - The route's shape will be encoded.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	Route’s vehicle is unavailable. Route’s vehicle limitations are exceeded by the order’s total number of packages/weight/cubic volume. Route’s start-end time are not valid. No destination set for the Route, and the route type is Custom end.
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	Route was not found. Route’s optimization was not found.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Note

Orders within a route cannot be updated directly using Update Route request. However, all other fields in the route can be modified using this method.

To modify orders, refer to the following examples:

Example:

Request Body:

Schema View
JSON Example
JSON View

id(integer)
Unique identifier for the input route.
▶configurationParameters(object)
Configuration parameters for the route.
▶vehicleConstraints(object)
Vehicle constraints for the route.
vehicle(integer)
ID of the vehicle assigned to the route.
▶departure(object)
Departure location for the route.
▶destination(object)
Destination location for the route.
matrixBuildType(integer)
Defines how the distance matrix is built. Possible values:
- 0 - Set by user using 'matrices' fieldmatrices 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).

{
  "id": 255145,
  "configurationParameters": {
    "name": "Paris - test optimization - Part 1",
    "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": []
  },
  "vehicleConstraints": {
    "fuelPrice": 1.0700000524520874,
    "startDate": 1596758400000,
    "maxNumberOfPackages": 53,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 100000000,
    "maxRevenue": 85
  },
  "vehicle": 139813,
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591,
    "departureTime": 1596783600000
  },
  "destination": {
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "traveledDistance": 0.6638350486755371,
    "arrivalTime": 1596783691000
  },
  "matrixBuildType": 1
}

{
  "id": 0,
  "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": []
  },
  "vehicleConstraints": {
    "fuelPrice": 0,
    "startDate": 0,
    "maxNumberOfPackages": 0,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 0,
    "minDistance": 0,
    "maxDistance": 0,
    "maxRevenue": 0
  },
  "vehicle": 0,
  "departure": {
    "depotId": 0,
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 0,
    "distanceToNext": 0,
    "departureTime": 0
  },
  "destination": {
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "traveledDistance": 0,
    "arrivalTime": 0
  },
  "matrixBuildType": 0
}

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:
0 - Created
1 - Pending
2 - Finished
3 - Canceled
message(string)
Status message for the request.
creationTimestamp(integer)
Timestamp when the request was created.

{
  "id": 767456,
  "routeId": 255145,
  "status": 0,
  "message": "Operation done successfully!",
  "creationTimestamp": 1743324342543
}

{
  "id": 0,
  "routeId": 0,
  "status": 0,
  "message": "string",
  "creationTimestamp": 0
}

4. Delete Routes

Description: Delete the routes from the list. Routes can be deleted individually or in bulk.

Method: DELETE
Endpoint: /routes
Headers:
- Authorization: YOUR_API_KEY
- Content-Type: application/json
URL: https://fleetmanagement.magiclaneapis.com/v1/routes
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`	Can't delete the routes because at least one of them does not exist.
`405 Method Not Allowed`	Incorrect method type.
`425 Too Early`	Request not finished.
`500 Internal Server Error`	Database error occurred.

Note

The orders of a deleted route will also be deleted from the optimization to which the route belongs. If the route is the only route of an optimization, then it cannot be deleted, instead delete the optimization (see Delete Optimization).

Example:

Request Body:

{
  "ids": [123, 456]
}

Response Body: (error code 200)

{
  "message": "Operation done successfully",
}

5. Reoptimize a Route

Description: Reoptimization allows you to find a better solution for an existing route.

Method: PUT
Endpoint: /routes/{id}/reoptimize
Headers:
- Authorization: YOUR_API_KEY
URL: https://fleetmanagement.magiclaneapis.com/v1/routes/{id}/reoptimize
Path Parameter:
- id (integer, *required) - The unique route ID.
Query Parameter:
- encodeShape (integer, optional)
  - 0: The route's shape will not be encoded.
  - 1 (default): The route's shape will be encoded.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	Route’s vehicle is unavailable. Route’s vehicle limitations are exceeded by the order’s total number of packages/weight/cubic volume. Route’s start-end time are not valid. No destination set for the Route, and the route type is Custom end.
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	Route was not found. Route’s optimization was not found.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Note

Rearranges the orders in a better order of visit, if exists. The latest fuel prices are used to calculate the route's cost (see Get Fuel Prices example).

Example:

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:
0 - Created
1 - Pending
2 - Finished
3 - Canceled
message(string)
Status message for the request.
creationTimestamp(integer)
Timestamp when the request was created.

{
  "id": 767456,
  "routeId": 255145,
  "status": 0,
  "message": "Operation done successfully!",
  "creationTimestamp": 1743324342543
}

{
  "id": 0,
  "routeId": 0,
  "status": 0,
  "message": "string",
  "creationTimestamp": 0
}

6. Add Route Orders

Description: Add a list of orders into an existing route's orders list. The orders will also be added in the optimization's orders list.

Method: POST
Endpoint: /routes/{id}/orders
Headers:
- Authorization: YOUR_API_KEY
- Content-Type: application/json
URL: https://fleetmanagement.magiclaneapis.com/v1/routes/{id}/orders
Path Parameter:
- id (integer, *required) - The unique route ID.
Query Parameters:
- reoptimize (integer, optional)
  - 0: (default) - If the route will not be re-optimized, the orders will be added to the end of the route.
  - 1: The route will be re-optimized.
- encodeShape (integer, optional)
  - 0: The route's shape will not be encoded.
  - 1(default) : - The route's shape will be encoded.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	One of the orders is used in another operation. One of the orders time window is outside the route’s start-end time interval. (For matrix build type=Set by user) The distances and times to all the orders of the route’s optimization were not set.
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	The route’s optimization was not found. The solution of the route’s optimization was not found.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Note

There are three options to add orders to a route:

at the end of the route's orders list.
at the optimal positions, which are determined by the algorithm.The orders are inserted at the best positions between the route's orders, without rearranging the route's orders.
at specified positions between the route's orders.

The route can be reoptimized, which means that after the addition, the route orders will be rearranged in the best order of visit, so it doesn’t matter which option was chosen to add the orders. The orders will be also added in the list of orders of the route's optimization.

Example:

Request Body:

Schema View
JSON Example
JSON View

▶orders(array[object])
List of orders to add to the route.
optimalPosition(boolean)
If true, the algorithm will insert the orders at the optimal positions.

{
  "orders": [
    {
      "id": 899037,
      "position": 0
    },
    {
      "id": 899038,
      "position": 0
    }
  ],
  "optimalPosition": true,
}

{
  "orders": [
    {
      "id": 0,
      "position": 0
    },
    {
      "id": 0,
      "position": 0
    }
  ],
  "optimalPosition": false,
}

Response Body: (error code 200)

note

There are two possible responses:

If the route is reoptimized, the response will be a request object with the status of the request.
If the route is not reoptimized, the response will be the updated route.

Schema View
JSON Example
JSON View

id(integer)
Unique identifier for the route.
optimizationId(integer)
ID of the associated optimization.
▶configurationParameters(object)
Configuration parameters for the route.
▶vehicleConstraints(array[object])
List of vehicle constraints applied to the route.
rideStatus(integer)
Current status of the ride.
Possible values:
• 0 - Finished: The ride is completed
• 1 - New: The ride is ready to start
• 2 - Started: The ride has begun
• 3 - Canceled by Driver: The ride was canceled by the driver
• 4 - Canceled by Fleet: The ride was canceled by fleet management
▶vehicle(object)
Vehicle assigned to this route.
▶departure(object)
Details of the departure location.
▶destination(object)
Details of the destination location.
shape(string)
Encoded polyline or list of locations representing the route.
creationTimestamp(integer)
Timestamp of when the route was created.
neededFuel(float)
Total fuel consumption for the route (liters or kWh based on fuel type).
matrixBuildType(integer)
Defines how the distance matrix is built. Possible values:
- 0 - Set by user using 'matrices' fieldmatrices field
- 1 - Real road map distances and times (default) distances and times
price(float)
Total cost of the route, calculated based on fuel consumption and distance.
totalWaitTime(integer)
Total wait time for the route (in seconds).
totalServiceTime(integer)
Total service time for all orders in the route (in seconds).
▶orders(array[object])
List of orders included in the route.
▶breaks(array[object])
List of breaks taken during the route execution.
totalTime(integer)
Total duration of the route (in seconds).
totalDistance(float)
Total route distance (in kilometers or miles based on settings).
matrices(array[object])
Contains distance and time matrices (set only if matrixBuildType = 0).

{
  "id": 255145,
  "optimizationId": 139950,
  "configurationParameters": {
    "name": "Paris - test optimization - Part 1",
    "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": []
  },
  "vehicleConstraints": {
    "fuelPrice": 1.0700000524520874,
    "startDate": 1596758400000,
    "maxNumberOfPackages": 53,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 100000000,
    "maxRevenue": 85
  },
  "rideStatus": 1,
  "vehicle": {
    "id": 139813,
    "type": 0,
    "status": 0,
    "name": "Car vehicle",
    "manufacturer": "",
    "model": "",
    "fuelType": 2,
    "lastPosition": [
      48.868507,
      2.359727
    ],
    "consumption": 6.5,
    "plate": "",
    "maxLoadWeight": 60,
    "maxLoadCube": 50,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 10,
    "startTime": 420,
    "endTime": 1439,
    "availableBreaks": [
      {
        "duration": 1800,
        "timeWindows": [
          [
            720,
            780
          ],
          [
            900,
            960
          ]
        ]
      }
    ]
  },
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591,
    "departureTime": 1596783600000
  },
  "destination": {
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "traveledDistance": 0.6638350486755371,
    "arrivalTime": 1596783691000
  },
  "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
  "creationTimestamp": 1744096606089,
  "neededFuel": 0.04314928129315376,
  "matrixBuildType": 1,
  "price": 0.04616973176598549,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": [
    {
      "orderInfo": {
        "id": 933799,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.82734625,
        2.3421875
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    },
    {
      "orderInfo": {
        "id": 899037,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.2345678,
        2.9876523
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    },
    {
      "orderInfo": {
        "id": 899038,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.237432,
        2.425215
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    }
  ],
  "breaks": [
    {
      "duration": 1800,
      "startTime": 720
    }
  ],
  "totalTime": 91,
  "totalDistance": 0.6638350486755371
}

{
  "id": 0,
  "optimizationId": 0,
  "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": []
  },
  "vehicleConstraints": [
    {
      "fuelPrice": 0,
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ],
  "rideStatus": 0,
  "vehicle": {
    "id": 0,
    "type": 0,
    "status": 0,
    "name": "string",
    "manufacturer": "string",
    "model": "string",
    "fuelType": 0,
    "lastPosition": [
      0,
      0
    ],
    "consumption": 0,
    "plate": "string",
    "maxLoadWeight": 0,
    "maxLoadCube": 0,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 0,
    "startTime": 0,
    "endTime": 0,
    "availableBreaks": []
  },
  "departure": {
    "depotId": 0,
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 0,
    "distanceToNext": 0,
    "departureTime": 0
  },
  "destination": {
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "traveledDistance": 0,
    "arrivalTime": 0
  },
  "shape": "string",
  "creationTimestamp": 0,
  "neededFuel": 0,
  "matrixBuildType": 1,
  "price": 0,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": {
    "orders": [
      {
        "id": 0,
        "creationTimestamp": 0,
        "customerInfo": {
          "id": 0,
          "alias": "string",
          "firstName": "string",
          "lastName": "string",
          "address": {
            "country": "string",
            "state": "string",
            "county": "string",
            "city": "string",
            "postalCode": "string",
            "streetName": "string",
            "streetNumber": "string",
            "extra": "string"
          },
          "email": "string",
          "phoneNumber": "string",
          "location": [
            0,
            0
          ],
          "customData": "string"
        },
        "location": [
          0,
          0
        ],
        "alias": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "phoneNumber": "string",
        "customData": "string",
        "type": 0,
        "status": 0,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          0,
          0
        ],
        "serviceTime": 0,
        "depotId": 0
      }
    ]
  },
  "breaks": [],
  "totalTime": 0,
  "totalDistance": 0
}

7. Delete an Order from a Route

Description: Delete an order from an existing route. The order will also be deleted from the optimization.

Method: DELETE
Endpoint: /routes/{id}/orders/{orderId}
Headers:
- Authorization: YOUR_API_KEY
URL: https://fleetmanagement.magiclaneapis.com/v1/routes/{id}/orders/{orderId}
Path Parameters:
- id (integer, *required) - The unique route ID.
- orderId (integer, *required) - The unique order ID.
Query Parameter:
- encodeShape (integer, optional)
  - 0: The route's shape will not be encoded.
  - 1(default) : - The route's shape will be encoded.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	If the route has only one order, the order cannot be deleted.
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	The route’s optimization was not found. The solution of the route’s optimization was not found. The order was not scheduled for any route.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Note

A route must contain at least two orders for one to be deleted. If the order you want to delete is the only one in the route, it cannot be deleted.

Example:

Response Body: (error code 200)

Schema View
JSON Example
JSON View

id(integer)
Unique identifier for the route.
optimizationId(integer)
ID of the associated optimization.
▶configurationParameters(object)
Configuration parameters for the route.
▶vehicleConstraints(array[object])
List of vehicle constraints applied to the route.
rideStatus(integer)
Current status of the ride.
Possible values:
• 0 - Finished: The ride is completed
• 1 - New: The ride is ready to start
• 2 - Started: The ride has begun
• 3 - Canceled by Driver: The ride was canceled by the driver
• 4 - Canceled by Fleet: The ride was canceled by fleet management
▶vehicle(object)
Vehicle assigned to this route.
▶departure(object)
Details of the departure location.
▶destination(object)
Details of the destination location.
shape(string)
Encoded polyline or list of locations representing the route.
creationTimestamp(integer)
Timestamp of when the route was created.
neededFuel(float)
Total fuel consumption for the route (liters or kWh based on fuel type).
matrixBuildType(integer)
Defines how the distance matrix is built. Possible values:
- 0 - Set by user using 'matrices' fieldmatrices field
- 1 - Real road map distances and times (default) distances and times
price(float)
Total cost of the route, calculated based on fuel consumption and distance.
totalWaitTime(integer)
Total wait time for the route (in seconds).
totalServiceTime(integer)
Total service time for all orders in the route (in seconds).
▶orders(array[object])
List of orders included in the route.
▶breaks(array[object])
List of breaks taken during the route execution.
totalTime(integer)
Total duration of the route (in seconds).
totalDistance(float)
Total route distance (in kilometers or miles based on settings).
matrices(array[object])
Contains distance and time matrices (set only if matrixBuildType = 0).

{
  "id": 255145,
  "optimizationId": 139950,
  "configurationParameters": {
    "name": "Paris - test optimization - Part 1",
    "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": []
  },
  "vehicleConstraints": {
    "fuelPrice": 1.0700000524520874,
    "startDate": 1596758400000,
    "maxNumberOfPackages": 53,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 100000000,
    "maxRevenue": 85
  },
  "rideStatus": 1,
  "vehicle": {
    "id": 139813,
    "type": 0,
    "status": 0,
    "name": "Car vehicle",
    "manufacturer": "",
    "model": "",
    "fuelType": 2,
    "lastPosition": [
      48.868507,
      2.359727
    ],
    "consumption": 6.5,
    "plate": "",
    "maxLoadWeight": 60,
    "maxLoadCube": 50,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 10,
    "startTime": 420,
    "endTime": 1439,
    "availableBreaks": [
      {
        "duration": 1800,
        "timeWindows": [
          [
            720,
            780
          ],
          [
            900,
            960
          ]
        ]
      }
    ]
  },
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591,
    "departureTime": 1596783600000
  },
  "destination": {
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "traveledDistance": 0.6638350486755371,
    "arrivalTime": 1596783691000
  },
  "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
  "creationTimestamp": 1744096606089,
  "neededFuel": 0.04314928129315376,
  "matrixBuildType": 1,
  "price": 0.04616973176598549,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": [
    {
      "orderInfo": {
        "id": 933799,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.82734625,
        2.3421875
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    }
  ],
  "breaks": [
    {
      "duration": 1800,
      "startTime": 720
    }
  ],
  "totalTime": 91,
  "totalDistance": 0.6638350486755371
}

{
  "id": 0,
  "optimizationId": 0,
  "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": []
  },
  "vehicleConstraints": [
    {
      "fuelPrice": 0,
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ],
  "rideStatus": 0,
  "vehicle": {
    "id": 0,
    "type": 0,
    "status": 0,
    "name": "string",
    "manufacturer": "string",
    "model": "string",
    "fuelType": 0,
    "lastPosition": [
      0,
      0
    ],
    "consumption": 0,
    "plate": "string",
    "maxLoadWeight": 0,
    "maxLoadCube": 0,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 0,
    "startTime": 0,
    "endTime": 0,
    "availableBreaks": []
  },
  "departure": {
    "depotId": 0,
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 0,
    "distanceToNext": 0,
    "departureTime": 0
  },
  "destination": {
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "traveledDistance": 0,
    "arrivalTime": 0
  },
  "shape": "string",
  "creationTimestamp": 0,
  "neededFuel": 0,
  "matrixBuildType": 1,
  "price": 0,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": {
    "orders": [
      {
        "id": 0,
        "creationTimestamp": 0,
        "customerInfo": {
          "id": 0,
          "alias": "string",
          "firstName": "string",
          "lastName": "string",
          "address": {
            "country": "string",
            "state": "string",
            "county": "string",
            "city": "string",
            "postalCode": "string",
            "streetName": "string",
            "streetNumber": "string",
            "extra": "string"
          },
          "email": "string",
          "phoneNumber": "string",
          "location": [
            0,
            0
          ],
          "customData": "string"
        },
        "location": [
          0,
          0
        ],
        "alias": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "phoneNumber": "string",
        "customData": "string",
        "type": 0,
        "status": 0,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          0,
          0
        ],
        "serviceTime": 0,
        "depotId": 0
      }
    ]
  },
  "breaks": [],
  "totalTime": 0,
  "totalDistance": 0
}

8. Merge Routes

Description: Merge multiple routes into a new one. A new optimization will be created for the merged route. The optimization will have same configuration parameters, vehicle constraints and the rest of the fields as the first route from the list. The merged route will not be optimized.

Method: POST
Endpoint: /routes/merge
Headers:
- Authorization: YOUR_API_KEY
- Content-Type: application/json
URL: https://fleetmanagement.magiclaneapis.com/v1/routes/merge
Query Parameter:
- encodeShape (integer, optional)
  - 0: The route's shape will not be encoded.
  - 1(default) : - The route's shape will be encoded.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	One of the routes has matrix build type = Set by user and cannot be merged because of that. The routes do not have the same vehicle type.
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	One of the routes was not found.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Warning

Routes with matrices build type set to EMatrixBuildType::MBT_Set, cannot be merged.

Example:

Request Body:

{
  [250995, 250996]
}

Response Body: (error code 200)

Schema View
JSON Example
JSON View

id(integer)
Unique identifier for the route.
optimizationId(integer)
ID of the associated optimization.
▶configurationParameters(object)
Configuration parameters for the route.
▶vehicleConstraints(array[object])
List of vehicle constraints applied to the route.
rideStatus(integer)
Current status of the ride.
Possible values:
• 0 - Finished: The ride is completed
• 1 - New: The ride is ready to start
• 2 - Started: The ride has begun
• 3 - Canceled by Driver: The ride was canceled by the driver
• 4 - Canceled by Fleet: The ride was canceled by fleet management
▶vehicle(object)
Vehicle assigned to this route.
▶departure(object)
Details of the departure location.
▶destination(object)
Details of the destination location.
shape(string)
Encoded polyline or list of locations representing the route.
creationTimestamp(integer)
Timestamp of when the route was created.
neededFuel(float)
Total fuel consumption for the route (liters or kWh based on fuel type).
matrixBuildType(integer)
Defines how the distance matrix is built. Possible values:
- 0 - Set by user using 'matrices' fieldmatrices field
- 1 - Real road map distances and times (default) distances and times
price(float)
Total cost of the route, calculated based on fuel consumption and distance.
totalWaitTime(integer)
Total wait time for the route (in seconds).
totalServiceTime(integer)
Total service time for all orders in the route (in seconds).
▶orders(array[object])
List of orders included in the route.
▶breaks(array[object])
List of breaks taken during the route execution.
totalTime(integer)
Total duration of the route (in seconds).
totalDistance(float)
Total route distance (in kilometers or miles based on settings).
matrices(array[object])
Contains distance and time matrices (set only if matrixBuildType = 0).

{
  "id": 255145,
  "optimizationId": 139950,
  "configurationParameters": {
    "name": "Merge routes 250996  250995  - Part 01",
    "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": []
  },
  "vehicleConstraints": {
    "fuelPrice": 1.0700000524520874,
    "startDate": 1596758400000,
    "maxNumberOfPackages": 53,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 100000000,
    "maxRevenue": 85
  },
  "rideStatus": 1,
  "vehicle": {
    "id": 139813,
    "type": 0,
    "status": 0,
    "name": "Car vehicle",
    "manufacturer": "",
    "model": "",
    "fuelType": 2,
    "lastPosition": [
      48.868507,
      2.359727
    ],
    "consumption": 6.5,
    "plate": "",
    "maxLoadWeight": 60,
    "maxLoadCube": 50,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 10,
    "startTime": 420,
    "endTime": 1439,
    "availableBreaks": [
      {
        "duration": 1800,
        "timeWindows": [
          [
            720,
            780
          ],
          [
            900,
            960
          ]
        ]
      }
    ]
  },
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591,
    "departureTime": 1596783600000
  },
  "destination": {
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "traveledDistance": 0.6638350486755371,
    "arrivalTime": 1596783691000
  },
  "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
  "creationTimestamp": 1744096606089,
  "neededFuel": 0.04314928129315376,
  "matrixBuildType": 1,
  "price": 0.04616973176598549,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": [
    {
      "orderInfo": {
        "id": 933799,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.82734625,
        2.3421875
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    },
    {
      "orderInfo": {
        "id": 899037,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.2345678,
        2.9876523
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    },
    {
      "orderInfo": {
        "id": 899038,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.237432,
        2.425215
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    }
  ],
  "breaks": [
    {
      "duration": 1800,
      "startTime": 720
    }
  ],
  "totalTime": 91,
  "totalDistance": 0.6638350486755371
}

{
  "id": 0,
  "optimizationId": 0,
  "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": []
  },
  "vehicleConstraints": [
    {
      "fuelPrice": 0,
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ],
  "rideStatus": 0,
  "vehicle": {
    "id": 0,
    "type": 0,
    "status": 0,
    "name": "string",
    "manufacturer": "string",
    "model": "string",
    "fuelType": 0,
    "lastPosition": [
      0,
      0
    ],
    "consumption": 0,
    "plate": "string",
    "maxLoadWeight": 0,
    "maxLoadCube": 0,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 0,
    "startTime": 0,
    "endTime": 0,
    "availableBreaks": []
  },
  "departure": {
    "depotId": 0,
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 0,
    "distanceToNext": 0,
    "departureTime": 0
  },
  "destination": {
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "traveledDistance": 0,
    "arrivalTime": 0
  },
  "shape": "string",
  "creationTimestamp": 0,
  "neededFuel": 0,
  "matrixBuildType": 1,
  "price": 0,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": {
    "orders": [
      {
        "id": 0,
        "creationTimestamp": 0,
        "customerInfo": {
          "id": 0,
          "alias": "string",
          "firstName": "string",
          "lastName": "string",
          "address": {
            "country": "string",
            "state": "string",
            "county": "string",
            "city": "string",
            "postalCode": "string",
            "streetName": "string",
            "streetNumber": "string",
            "extra": "string"
          },
          "email": "string",
          "phoneNumber": "string",
          "location": [
            0,
            0
          ],
          "customData": "string"
        },
        "location": [
          0,
          0
        ],
        "alias": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "phoneNumber": "string",
        "customData": "string",
        "type": 0,
        "status": 0,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          0,
          0
        ],
        "serviceTime": 0,
        "depotId": 0
      }
    ]
  },
  "breaks": [],
  "totalTime": 0,
  "totalDistance": 0
}

9. Unlink a Route from its Optimization

Description: Unlinks a route from its optimization. The route will no longer be a part of the optimization's solution. The orders used in this route will be deleted from the optimization. A new optimization will be created for the unlinked route. The new optimization will have same configuration parameters, vehicle constraints and the rest of the fields as the unlinked route.

Method: POST
Endpoint: /routes/{id}/unlink
Headers:
- Authorization: YOUR_API_KEY
URL: https://fleetmanagement.magiclaneapis.com/v1/routes/{id}/unlink
Path Parameters:
- id (integer, *required) - The unique route ID.
Query Parameter:
- encodeShape (integer, optional)
  - 0: The route's shape will not be encoded.
  - 1 (default): The route's shape will be encoded.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	If the route is the only one in the optimization’s solution it cannot be deleted (Tip: delete the optimization instead).
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	The route’s optimization was not found. The solution of the route’s optimization was not found.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Info

The route cannot be unlinked if it is the only route in the optimization's solution.

Example:

Response Body: (error code 200)

Schema View
JSON Example
JSON View

id(integer)
Unique identifier for the route.
optimizationId(integer)
ID of the associated optimization.
▶configurationParameters(object)
Configuration parameters for the route.
▶vehicleConstraints(array[object])
List of vehicle constraints applied to the route.
rideStatus(integer)
Current status of the ride.
Possible values:
• 0 - Finished: The ride is completed
• 1 - New: The ride is ready to start
• 2 - Started: The ride has begun
• 3 - Canceled by Driver: The ride was canceled by the driver
• 4 - Canceled by Fleet: The ride was canceled by fleet management
▶vehicle(object)
Vehicle assigned to this route.
▶departure(object)
Details of the departure location.
▶destination(object)
Details of the destination location.
shape(string)
Encoded polyline or list of locations representing the route.
creationTimestamp(integer)
Timestamp of when the route was created.
neededFuel(float)
Total fuel consumption for the route (liters or kWh based on fuel type).
matrixBuildType(integer)
Defines how the distance matrix is built. Possible values:
- 0 - Set by user using 'matrices' fieldmatrices field
- 1 - Real road map distances and times (default) distances and times
price(float)
Total cost of the route, calculated based on fuel consumption and distance.
totalWaitTime(integer)
Total wait time for the route (in seconds).
totalServiceTime(integer)
Total service time for all orders in the route (in seconds).
▶orders(array[object])
List of orders included in the route.
▶breaks(array[object])
List of breaks taken during the route execution.
totalTime(integer)
Total duration of the route (in seconds).
totalDistance(float)
Total route distance (in kilometers or miles based on settings).
matrices(array[object])
Contains distance and time matrices (set only if matrixBuildType = 0).

{
  "id": 255145,
  "optimizationId": 139950,
  "configurationParameters": {
    "name": "Merge routes 250996  250995  - Part 01",
    "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": []
  },
  "vehicleConstraints": {
    "fuelPrice": 1.0700000524520874,
    "startDate": 1596758400000,
    "maxNumberOfPackages": 53,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 100000000,
    "maxRevenue": 85
  },
  "rideStatus": 1,
  "vehicle": {
    "id": 139813,
    "type": 0,
    "status": 0,
    "name": "Car vehicle",
    "manufacturer": "",
    "model": "",
    "fuelType": 2,
    "lastPosition": [
      48.868507,
      2.359727
    ],
    "consumption": 6.5,
    "plate": "",
    "maxLoadWeight": 60,
    "maxLoadCube": 50,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 10,
    "startTime": 420,
    "endTime": 1439,
    "availableBreaks": [
      {
        "duration": 1800,
        "timeWindows": [
          [
            720,
            780
          ],
          [
            900,
            960
          ]
        ]
      }
    ]
  },
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591,
    "departureTime": 1596783600000
  },
  "destination": {
    "alias": "Departure2",
    "location": [
      48.82674,
      2.342116
    ],
    "address": {
      "country": "France",
      "state": "",
      "county": "Nouvelle-Aquitaine",
      "city": "Poitiers",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "streetNumber": "34"
    },
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "traveledDistance": 0.6638350486755371,
    "arrivalTime": 1596783691000
  },
  "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
  "creationTimestamp": 1744096606089,
  "neededFuel": 0.04314928129315376,
  "matrixBuildType": 1,
  "price": 0.04616973176598549,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": [
    {
      "orderInfo": {
        "id": 933799,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.82734625,
        2.3421875
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    },
    {
      "orderInfo": {
        "id": 899037,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.2345678,
        2.9876523
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    },
    {
      "orderInfo": {
        "id": 899038,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 1,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "matchedLocation": [
        48.237432,
        2.425215
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0.07019499689340591,
      "traveledDistance": 0.5936400294303894,
      "distanceToNextOrder": 0,
      "revenueAtArrival": 0
    }
  ],
  "breaks": [
    {
      "duration": 1800,
      "startTime": 720
    }
  ],
  "totalTime": 91,
  "totalDistance": 0.6638350486755371
}

{
  "id": 0,
  "optimizationId": 0,
  "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": []
  },
  "vehicleConstraints": [
    {
      "fuelPrice": 0,
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ],
  "rideStatus": 0,
  "vehicle": {
    "id": 0,
    "type": 0,
    "status": 0,
    "name": "string",
    "manufacturer": "string",
    "model": "string",
    "fuelType": 0,
    "lastPosition": [
      0,
      0
    ],
    "consumption": 0,
    "plate": "string",
    "maxLoadWeight": 0,
    "maxLoadCube": 0,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 0,
    "startTime": 0,
    "endTime": 0,
    "availableBreaks": []
  },
  "departure": {
    "depotId": 0,
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "numberOfPackages": 0,
    "weight": 0,
    "cube": 0,
    "timeToNext": 0,
    "distanceToNext": 0,
    "departureTime": 0
  },
  "destination": {
    "alias": "string",
    "location": [
      0,
      0
    ],
    "address": {
      "country": "string",
      "state": "string",
      "county": "string",
      "city": "string",
      "postalCode": "string",
      "streetName": "string",
      "streetNumber": "string",
      "extra": "string"
    },
    "matchedLocation": [
      0,
      0
    ],
    "traveledDistance": 0,
    "arrivalTime": 0
  },
  "shape": "string",
  "creationTimestamp": 0,
  "neededFuel": 0,
  "matrixBuildType": 1,
  "price": 0,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "orders": {
    "orders": [
      {
        "id": 0,
        "creationTimestamp": 0,
        "customerInfo": {
          "id": 0,
          "alias": "string",
          "firstName": "string",
          "lastName": "string",
          "address": {
            "country": "string",
            "state": "string",
            "county": "string",
            "city": "string",
            "postalCode": "string",
            "streetName": "string",
            "streetNumber": "string",
            "extra": "string"
          },
          "email": "string",
          "phoneNumber": "string",
          "location": [
            0,
            0
          ],
          "customData": "string"
        },
        "location": [
          0,
          0
        ],
        "alias": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "phoneNumber": "string",
        "customData": "string",
        "type": 0,
        "status": 0,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          0,
          0
        ],
        "serviceTime": 0,
        "depotId": 0
      }
    ]
  },
  "breaks": [],
  "totalTime": 0,
  "totalDistance": 0
}

Route Object Fields​

Endpoints​

1. Get All Routes​

Example:​

2. Get a Route by ID​

Example:​

3. Update a Route​

Example:​

4. Delete Routes​

Example:​

5. Reoptimize a Route​

Example:​

6. Add Route Orders​

Example:​

7. Delete an Order from a Route​

Example:​

8. Merge Routes​

Example:​

9. Unlink a Route from its Optimization​

Example:​

Route Object Fields

Endpoints

1. Get All Routes

Example:

2. Get a Route by ID

Example:

3. Update a Route

Example:

4. Delete Routes

Example:

5. Reoptimize a Route

Example:

6. Add Route Orders

Example:

7. Delete an Order from a Route

Example:

8. Merge Routes

Example:

9. Unlink a Route from its Optimization

Example: