Skip to main content
GuidesExamples

Route

Estimated reading time: 38 minutes

Overview

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

Route Object Fields

FieldTypeDescription
idIntegerUnique identifier for the route.
optimizationIdIntegerID of the associated optimization.
idVehicleIntegerID of the vehicle assigned to this route.
matrixBuiltTypeInteger
Distance calculation method:
0 - Set by user using "matrices" field
1 - Real road distances and times
matricesArrayContains distance and time matrices (set only if matrixBuiltType = 0).
configurationParametersObjectConfiguration parameters for the route.
departureObjectDetails of the departure location.
destinationObjectDetails of the destination location.
vehicleConstraintsArrayList of vehicle constraints applied to the route.
ordersArrayList of orders included in the route.
totalDistanceFloatTotal route distance (in kilometers or miles based on settings).
totalTimeIntegerTotal duration of the route (in seconds).
totalServiceTimeIntegerTotal service time for all orders in the route (in seconds).
totalWaitTimeIntegerTotal wait time for the route (in seconds).
neededFuelFloatTotal fuel consumption for the route (liters or kWh based on fuel type).
priceFloatTotal cost of the route, calculated based on fuel consumption and distance.
shapeStringEncoded polyline or list of locations representing the route.
creationTimestampIntegerTimestamp 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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestThe values sent for page and per_page parameters are incorrect; should be greater than 0.
401 UnauthorizedAPI key is missing or invalid.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:

  • Response Body: (error code 200)
{
"routes": [
{
"id": 255145,
"optimizationId": 139950,
"configurationParameters": {
"orderSequenceOptions": [],
"distanceUnit": 0,
"maxTimeToOptimize": 300,
"optimizationQuality": 2,
"routeType": 0,
"arrangeCriterion": 0,
"restrictions": 0,
"maxWaitTime": 18000,
"balancedRoutes": 0,
"groupingOrders": false,
"optimizationCriterion": 0,
"allowDroppingOrders": false,
"ignoreTimeWindow": false,
"name": "Paris - test optimization - Part 1"
},
"vehicleConstraints": {
"startDate": 1596758400000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 100000000,
"maxRevenue": 85,
"fuelPrice": 1.0700000524520874
},
"rideStatus": 1,
"vehicle": {
"length": 0,
"weight": 0,
"width": 0,
"licensePlate": "",
"consumption": 6.5,
"fuelType": 2,
"make": "",
"id": 139813,
"name": "Car vehicle",
"model": "",
"costPerHour": 0,
"type": 0,
"status": 0,
"maxLoadWeight": 60,
"height": 0,
"maxLoadCube": 50,
"idDriver": 139813,
"endTime": 1439,
"fixedCost": 0,
"startTime": 420,
"lastPosition": [
2147483647,
2147483647
]
},
"destination": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"arrivalTime": 1596783691000,
"traveledDistance": 0.6638350486755371
},
"departure": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"numberOfpackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 1596783600000,
"timeToNext": 12,
"distanceToNext": 0.07019499689340591
},
"shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
"creationTimestamp": 1744096606089,
"neededFuel": 0.04314928129315376,
"matrixBuildType": 1,
"price": 0.04616973176598549,
"totalWaitTime": 0,
"totalServiceTime": 0,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1744096603223,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 933799,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c1@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1839506,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"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,
"traveledDistance": 0.07019499689340591,
"distanceToNextOrder": 0.5936400294303894,
"revenueAtArrival": 0,
"visitTimestamp": 0
}
],
"totalTime": 91,
"totalDistance": 0.6638350486755371,
}
]
}

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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestInvalid input or missing required fields..
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundRoute not found.
405 Method Not AllowedIncorrect method type.
425 Too EarlyRequest not finished.
500 Internal Server ErrorDatabase error occurred.

Example:

  • Response Body: (error code 200)
{
"id": 255145,
"optimizationId": 139950,
"configurationParameters": {
"orderSequenceOptions": [],
"distanceUnit": 0,
"maxTimeToOptimize": 300,
"optimizationQuality": 2,
"routeType": 0,
"arrangeCriterion": 0,
"restrictions": 0,
"maxWaitTime": 18000,
"balancedRoutes": 0,
"groupingOrders": false,
"optimizationCriterion": 0,
"allowDroppingOrders": false,
"ignoreTimeWindow": false,
"name": "Paris - test optimization - Part 1"
},
"vehicleConstraints": {
"startDate": 1596758400000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 100000000,
"maxRevenue": 85,
"fuelPrice": 1.0700000524520874
},
"rideStatus": 1,
"vehicle": {
"length": 0,
"weight": 0,
"width": 0,
"licensePlate": "",
"consumption": 6.5,
"fuelType": 2,
"make": "",
"id": 139813,
"name": "Car vehicle",
"model": "",
"costPerHour": 0,
"type": 0,
"status": 0,
"maxLoadWeight": 60,
"height": 0,
"maxLoadCube": 50,
"idDriver": 139813,
"endTime": 1439,
"fixedCost": 0,
"startTime": 420,
"lastPosition": [
2147483647,
2147483647
]
},
"destination": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"arrivalTime": 1596783691000,
"traveledDistance": 0.6638350486755371
},
"departure": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"numberOfpackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 1596783600000,
"timeToNext": 12,
"distanceToNext": 0.07019499689340591
},
"shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
"creationTimestamp": 1744096606089,
"neededFuel": 0.04314928129315376,
"matrixBuildType": 1,
"price": 0.04616973176598549,
"totalWaitTime": 0,
"totalServiceTime": 0,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1744096603223,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 933799,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c1@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1839506,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"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,
"traveledDistance": 0.07019499689340591,
"distanceToNextOrder": 0.5936400294303894,
"revenueAtArrival": 0,
"visitTimestamp": 0
}
],
"totalTime": 91,
"totalDistance": 0.6638350486755371,
}

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 CodeDescription
200 SuccessfulSuccessful 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 UnauthorizedAPI key is missing or invalid.
404 Not Found
  • Route was not found.
  • Route’s optimization was not found.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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:
{
"id": 250806,
"optimizationId": 137211,
"configurationParameters": {
"orderSequenceOptions": [],
"distanceUnit": 0,
"maxTimeToOptimize": 300,
"optimizationQuality": 2,
"routeType": 0,
"arrangeCriterion": 0,
"restrictions": 0,
"maxWaitTime": 18000,
"balancedRoutes": 0,
"groupingOrders": false,
"optimizationCriterion": 0,
"allowDroppingOrders": false,
"ignoreTimeWindow": false,
"name": "Paris - test optimization - Part 1"
},
"vehicleConstraints": {
"startDate": 1596758400000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 100000000,
"maxRevenue": 85,
"fuelPrice": 1.0700000524520874
},
"rideStatus": 1,
"vehicle": {
"length": 0,
"weight": 0,
"width": 0,
"licensePlate": "",
"consumption": 6.5,
"fuelType": 2,
"make": "",
"id": 134764,
"name": "Car vehicle",
"model": "",
"costPerHour": 0,
"type": 0,
"status": 0,
"maxLoadWeight": 60,
"height": 0,
"maxLoadCube": 50,
"idDriver": 134764,
"endTime": 1439,
"fixedCost": 0,
"startTime": 420,
"lastPosition": [
2147483647,
2147483647
]
},
"destination": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"arrivalTime": 1596783691000,
"traveledDistance": 0.6638350486755371
},
"departure": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"numberOfpackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 1596783600000,
"timeToNext": 12,
"distanceToNext": 0.07019499689340591
},
"shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
"creationTimestamp": 1742220618730,
"neededFuel": 0.04314928129315376,
"matrixBuildType": 1,
"price": 0.04616973176598549,
"totalWaitTime": 0,
"totalServiceTime": 0,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1742220613856,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 876534,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c1@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1786643,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"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,
"traveledDistance": 0.07019499689340591,
"distanceToNextOrder": 0.5936400294303894,
"revenueAtArrival": 0,
"visitTimestamp": 0
}
],
"totalTime": 91,
"totalDistance": 0.6638350486755371,
}
  • Response Body: (error code 200)
{
"id": 250806,
"optimizationId": 137211,
"configurationParameters": {
"orderSequenceOptions": [],
"distanceUnit": 0,
"maxTimeToOptimize": 300,
"optimizationQuality": 2,
"routeType": 1,
"arrangeCriterion": 0,
"restrictions": 0,
"maxWaitTime": 18000,
"balancedRoutes": 0,
"groupingOrders": false,
"optimizationCriterion": 0,
"allowDroppingOrders": false,
"ignoreTimeWindow": false,
"name": "Paris - test optimization - Part 1 updated"
},
"vehicleConstraints": {
"startDate": 1596758400000,
"maxNumberOfPackages": 85,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 999999,
"maxRevenue": 85,
"fuelPrice": 1.0700000524520874
},
"rideStatus": 1,
"vehicle": {
"length": 0,
"weight": 0,
"width": 0,
"licensePlate": "",
"consumption": 6.5,
"fuelType": 2,
"make": "",
"id": 134764,
"name": "Car vehicle",
"model": "",
"costPerHour": 0,
"type": 0,
"status": 0,
"maxLoadWeight": 60,
"height": 0,
"maxLoadCube": 50,
"idDriver": 134764,
"endTime": 1439,
"fixedCost": 0,
"startTime": 420,
"lastPosition": [
2147483647,
2147483647
]
},
"destination": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"arrivalTime": 1596783691000,
"traveledDistance": 0.6638350486755371
},
"departure": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"numberOfpackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 1596783600000,
"timeToNext": 12,
"distanceToNext": 0.07019499689340591
},
"shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
"creationTimestamp": 1742220618730,
"neededFuel": 0.04314928129315376,
"matrixBuildType": 1,
"price": 0.04616973176598549,
"totalWaitTime": 0,
"totalServiceTime": 0,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1742220613856,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 876534,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c1@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1786643,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"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,
"traveledDistance": 0.07019499689340591,
"distanceToNextOrder": 0.5936400294303894,
"revenueAtArrival": 0,
"visitTimestamp": 0
}
],
"totalTime": 91,
"totalDistance": 0.6638350486755371,
}

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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestInvalid input or missing required fields.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCan't delete the routes because at least one of them does not exist.
405 Method Not AllowedIncorrect method type.
425 Too EarlyRequest not finished.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful 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 UnauthorizedAPI key is missing or invalid.
404 Not Found
  • Route was not found.
  • Route’s optimization was not found.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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)
{
"id": 767456,
"optimizationId": 56646,
"routeId": 221356,
"status": 0,
"message": "Operation done successfully!",
"creationTimestamp": 1743324342543
}

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 CodeDescription
200 SuccessfulSuccessful 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 UnauthorizedAPI 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 AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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:
{
"orders": [
{
"id": 899037,
"position": 0
},
{
"id": 899038,
"position": 0
}
],
"optimalPosition": true,
}
  • Response Body: (error code 200)
note

There are two possible responses:

  1. If the route is reoptimized, the response will be a request object with the status of the request.
  2. If the route is not reoptimized, the response will be the updated route.
{
"id": 255145,
"optimizationId": 139950,
"configurationParameters": {
"orderSequenceOptions": [],
"distanceUnit": 0,
"maxTimeToOptimize": 300,
"optimizationQuality": 2,
"routeType": 0,
"arrangeCriterion": 0,
"restrictions": 0,
"maxWaitTime": 18000,
"balancedRoutes": 0,
"groupingOrders": false,
"optimizationCriterion": 0,
"allowDroppingOrders": false,
"ignoreTimeWindow": false,
"name": "Paris - test optimization - Part 1"
},
"vehicleConstraints": {
"startDate": 1596758400000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 100000000,
"maxRevenue": 85,
"fuelPrice": 1.0700000524520874
},
"rideStatus": 1,
"vehicle": {
"length": 0,
"weight": 0,
"width": 0,
"licensePlate": "",
"consumption": 6.5,
"fuelType": 2,
"make": "",
"id": 139813,
"name": "Car vehicle",
"model": "",
"costPerHour": 0,
"type": 0,
"status": 0,
"maxLoadWeight": 60,
"height": 0,
"maxLoadCube": 50,
"idDriver": 139813,
"endTime": 1439,
"fixedCost": 0,
"startTime": 420,
"lastPosition": [
2147483647,
2147483647
]
},
"destination": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"arrivalTime": 1596783691000,
"traveledDistance": 0.6638350486755371
},
"departure": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"numberOfpackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 1596783600000,
"timeToNext": 12,
"distanceToNext": 0.07019499689340591
},
"shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
"creationTimestamp": 1744096606089,
"neededFuel": 0.04314928129315376,
"matrixBuildType": 1,
"price": 0.04616973176598549,
"totalWaitTime": 0,
"totalServiceTime": 0,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1744096603223,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 933799,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c1@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1839506,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"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,
"traveledDistance": 0.07019499689340591,
"distanceToNextOrder": 0.5936400294303894,
"revenueAtArrival": 0,
"visitTimestamp": 0
},
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1744096603223,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 899037,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c1@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1839506,
"location": [
48.9867892,
2.3453345
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"matchedLocation": [
48.9867892,
2.3453345
],
"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,
"traveledDistance": 0.90019499689340591,
"distanceToNextOrder": 0.3640029430003894,
"revenueAtArrival": 0,
"visitTimestamp": 0
},
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1744096603223,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 899038,
"location": [
48.787420,
2.673783
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12234550181",
"email": "c2@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1839507,
"location": [
48.787420,
2.673783
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"matchedLocation": [
48.787420,
2.673783
],
"actualLocation": [
0,
0
],
"indexInRoute": 0,
"indexInOptimization": 1,
"arrivalTime": 1596783742000,
"timeToNextOrder": 79,
"waitTime": 0,
"numberOfPackagesAtArrival": 0,
"collectedNumberOfPackages": 0,
"deliveredNumberOfPackages": 0,
"weightAtArrival": 0,
"collectedWeight": 0,
"deliveredWeight": 0,
"cubeAtArrival": 0,
"collectedCube": 0,
"deliveredCube": 0,
"traveledDistance": 1.23019499689340591,
"distanceToNextOrder": 0.4536400294303894,
"revenueAtArrival": 0,
"visitTimestamp": 0
}
],
"totalTime": 91,
"totalDistance": 0.6638350486755371,
}

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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestIf the route has only one order, the order cannot be deleted.
401 UnauthorizedAPI 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 AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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)
{
"id": 255145,
"optimizationId": 139950,
"configurationParameters": {
"orderSequenceOptions": [],
"distanceUnit": 0,
"maxTimeToOptimize": 300,
"optimizationQuality": 2,
"routeType": 0,
"arrangeCriterion": 0,
"restrictions": 0,
"maxWaitTime": 18000,
"balancedRoutes": 0,
"groupingOrders": false,
"optimizationCriterion": 0,
"allowDroppingOrders": false,
"ignoreTimeWindow": false,
"name": "Paris - test optimization - Part 1"
},
"vehicleConstraints": {
"startDate": 1596758400000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 100000000,
"maxRevenue": 85,
"fuelPrice": 1.0700000524520874
},
"rideStatus": 1,
"vehicle": {
"length": 0,
"weight": 0,
"width": 0,
"licensePlate": "",
"consumption": 6.5,
"fuelType": 2,
"make": "",
"id": 139813,
"name": "Car vehicle",
"model": "",
"costPerHour": 0,
"type": 0,
"status": 0,
"maxLoadWeight": 60,
"height": 0,
"maxLoadCube": 50,
"idDriver": 139813,
"endTime": 1439,
"fixedCost": 0,
"startTime": 420,
"lastPosition": [
2147483647,
2147483647
]
},
"destination": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"arrivalTime": 1596783691000,
"traveledDistance": 0.6638350486755371
},
"departure": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"numberOfpackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 1596783600000,
"timeToNext": 12,
"distanceToNext": 0.07019499689340591
},
"shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
"creationTimestamp": 1744096606089,
"neededFuel": 0.04314928129315376,
"matrixBuildType": 1,
"price": 0.04616973176598549,
"totalWaitTime": 0,
"totalServiceTime": 0,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1744096603223,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 933799,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c1@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1839506,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"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,
"traveledDistance": 0.07019499689340591,
"distanceToNextOrder": 0.5936400294303894,
"revenueAtArrival": 0,
"visitTimestamp": 0
}
],
"totalTime": 91,
"totalDistance": 0.6638350486755371,
}

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 CodeDescription
200 SuccessfulSuccessful 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 UnauthorizedAPI key is missing or invalid.
404 Not FoundOne of the routes was not found.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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)
{  
"id": 250999,
"optimizationId": 137369,
"configurationParameters": {
"orderSequenceOptions": [],
"distanceUnit": 0,
"maxTimeToOptimize": 300,
"optimizationQuality": 2,
"routeType": 0,
"arrangeCriterion": 0,
"restrictions": 0,
"maxWaitTime": 0,
"balancedRoutes": 0,
"groupingOrders": false,
"optimizationCriterion": 1,
"allowDroppingOrders": false,
"ignoreTimeWindow": true,
"name": "Merge routes 250996 250995 - Part 0"
},
"vehicleConstraints": {
"startDate": 1742860800000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 100000000,
"maxRevenue": 85,
"fuelPrice": 1.0700000524520874
},
"rideStatus": 1,
"vehicle": {
"length": 0,
"weight": 0,
"width": 0,
"licensePlate": "",
"consumption": 6.5,
"fuelType": 2,
"make": "",
"id": 135027,
"name": "Car vehicle",
"model": "",
"costPerHour": 20,
"type": 0,
"status": 0,
"maxLoadWeight": 60,
"height": 0,
"maxLoadCube": 50,
"idDriver": 135027,
"endTime": 1439,
"fixedCost": 150.5,
"startTime": 727,
"lastPosition": [
2147483647,
2147483647
]
},
"destination": {
"depotId": 0,
"alias": "departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.826295,
2.343264
],
"matchedLocation": [
48.82623,
2.343238125
],
"arrivalTime": 1742948951000,
"traveledDistance": 90.75505065917969
},
"departure": {
"depotId": 0,
"alias": "departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.826295,
2.343264
],
"matchedLocation": [
48.82623,
2.343238125
],
"numberOfpackages": 34,
"weight": 49.20000076293945,
"cube": 21.600000381469727,
"departureTime": 1742927130605,
"timeToNext": 413,
"distanceToNext": 2.7538180351257324
},
"shape": "{j_iHgthMt@sJBq@t@_J@g@[aQkAyi@}",
"creationTimestamp": 1742904432224,
"neededFuel": 5.899078369140625,
"matrixBuildType": 1,
"price": 276.81201171875,
"totalWaitTime": 0,
"totalServiceTime": 8960,
"orders": [
{
"orderInfo": {
"revenue": 14.699999809265137,
"serviceTime": 750,
"timeWindow": [
1060,
1387
],
"creationTimestamp": 1742904432067,
"cube": 4.599999904632568,
"numberOfPackages": 11,
"depotId": 0,
"customData": "",
"weight": 12.100000381469727,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 1,
"priority": 0,
"id": 878525,
"location": [
48.827865,
2.379216
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c6@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1789281,
"location": [
48.827865,
2.379216
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"matchedLocation": [
48.82792,
2.3791415625
],
"actualLocation": [
0,
0
],
"indexInRoute": 0,
"indexInOptimization": 0,
"arrivalTime": 1742927544000,
"timeToNextOrder": 535,
"waitTime": 0,
"numberOfPackagesAtArrival": 34,
"collectedNumberOfPackages": 0,
"deliveredNumberOfPackages": 11,
"weightAtArrival": 49.20000076293945,
"collectedWeight": 0,
"deliveredWeight": 12.100000381469727,
"cubeAtArrival": 21.600000381469727,
"collectedCube": 0,
"deliveredCube": 4.599999904632568,
"traveledDistance": 2.7538180351257324,
"distanceToNextOrder": 3.6211578845977783,
"revenueAtArrival": 0,
"visitTimestamp": 0
},
{
"orderInfo": {
"revenue": 2.700000047683716,
"serviceTime": 200,
"timeWindow": [
1060,
1343
],
"creationTimestamp": 1742904432067,
"cube": 5.800000190734863,
"numberOfPackages": 8,
"depotId": 0,
"customData": "",
"weight": 15.399999618530273,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 1,
"priority": 0,
"id": 878526,
"location": [
48.845198,
2.402896
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c2@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1789277,
"location": [
48.845198,
2.402896
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"matchedLocation": [
48.8452625,
2.4027009375
],
"actualLocation": [
0,
0
],
"indexInRoute": 1,
"indexInOptimization": 1,
"arrivalTime": 1742928829000,
"timeToNextOrder": 855,
"waitTime": 0,
"numberOfPackagesAtArrival": 23,
"collectedNumberOfPackages": 0,
"deliveredNumberOfPackages": 8,
"weightAtArrival": 37.099998474121094,
"collectedWeight": 0,
"deliveredWeight": 15.399999618530273,
"cubeAtArrival": 17,
"collectedCube": 0,
"deliveredCube": 5.800000190734863,
"traveledDistance": 6.37497615814209,
"distanceToNextOrder": 9.219883918762207,
"revenueAtArrival": 14.699999809265137,
"visitTimestamp": 0
},
{
"orderInfo": {
"revenue": 10,
"serviceTime": 900,
"timeWindow": [
1093,
1360
],
"creationTimestamp": 1742904432067,
"cube": 9.699999809265137,
"numberOfPackages": 9,
"depotId": 0,
"customData": "",
"weight": 16.5,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 1,
"priority": 0,
"id": 878527,
"location": [
48.90092,
2.400039
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c4@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1789279,
"location": [
48.90092,
2.400039
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"matchedLocation": [
48.9005959375,
2.4000475
],
"actualLocation": [
0,
0
],
"indexInRoute": 2,
"indexInOptimization": 2,
"arrivalTime": 1742929884000,
"timeToNextOrder": 971,
"waitTime": 0,
"numberOfPackagesAtArrival": 15,
"collectedNumberOfPackages": 0,
"deliveredNumberOfPackages": 9,
"weightAtArrival": 21.69999885559082,
"collectedWeight": 0,
"deliveredWeight": 16.5,
"cubeAtArrival": 11.199999809265137,
"collectedCube": 0,
"deliveredCube": 9.699999809265137,
"traveledDistance": 15.594860076904297,
"distanceToNextOrder": 9.614479064941406,
"revenueAtArrival": 17.399999618530273,
"visitTimestamp": 0
},
{
"orderInfo": {
"revenue": 7.5,
"serviceTime": 600,
"timeWindow": [
1043,
1387
],
"creationTimestamp": 1742904432067,
"cube": 8.399999618530273,
"numberOfPackages": 9,
"depotId": 0,
"customData": "",
"weight": 16.200000762939453,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 878531,
"location": [
48.897163,
2.292865
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c3@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1789278,
"location": [
48.897163,
2.292865
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"matchedLocation": [
48.89706375,
2.29247
],
"actualLocation": [
0,
0
],
"indexInRoute": 6,
"indexInOptimization": 6,
"arrivalTime": 1742935187000,
"timeToNextOrder": 404,
"waitTime": 0,
"numberOfPackagesAtArrival": 29,
"collectedNumberOfPackages": 9,
"deliveredNumberOfPackages": 0,
"weightAtArrival": 16.299999237060547,
"collectedWeight": 16.200000762939453,
"deliveredWeight": 0,
"cubeAtArrival": 20.5,
"collectedCube": 8.399999618530273,
"deliveredCube": 0,
"traveledDistance": 34.35464096069336,
"distanceToNextOrder": 2.4328789710998535,
"revenueAtArrival": 37.79999923706055,
"visitTimestamp": 0
},
{
"orderInfo": {
"revenue": 2.9000000953674316,
"serviceTime": 800,
"timeWindow": [
1077,
1377
],
"creationTimestamp": 1742904432067,
"cube": 1.5,
"numberOfPackages": 6,
"depotId": 0,
"customData": "",
"weight": 5.199999809265137,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 1,
"priority": 0,
"id": 878532,
"location": [
48.887096,
2.283513
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c7@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1789282,
"location": [
48.887096,
2.283513
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"matchedLocation": [
48.886898125,
2.2838078125
],
"actualLocation": [
0,
0
],
"indexInRoute": 7,
"indexInOptimization": 7,
"arrivalTime": 1742936191000,
"timeToNextOrder": 1286,
"waitTime": 0,
"numberOfPackagesAtArrival": 38,
"collectedNumberOfPackages": 0,
"deliveredNumberOfPackages": 6,
"weightAtArrival": 32.5,
"collectedWeight": 0,
"deliveredWeight": 5.199999809265137,
"cubeAtArrival": 28.899999618530273,
"collectedCube": 0,
"deliveredCube": 1.5,
"traveledDistance": 36.78752136230469,
"distanceToNextOrder": 10.027785301208496,
"revenueAtArrival": 45.29999923706055,
"visitTimestamp": 0
}
],
"totalTime": 21820,
"totalDistance": 90.75505065917969,
}

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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestIf the route is the only one in the optimization’s solution it cannot be deleted (Tip: delete the optimization instead).
401 UnauthorizedAPI 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 AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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)
{  "id": 250807,
"optimizationId": 137212,
"configurationParameters": {
"orderSequenceOptions": [],
"distanceUnit": 0,
"maxTimeToOptimize": 300,
"optimizationQuality": 2,
"routeType": 0,
"arrangeCriterion": 0,
"restrictions": 0,
"maxWaitTime": 18000,
"balancedRoutes": 0,
"groupingOrders": false,
"optimizationCriterion": 0,
"allowDroppingOrders": false,
"ignoreTimeWindow": false,
"name": "Unlinked route Paris - test optimization - Part 1"
},
"vehicleConstraints": {
"startDate": 1596758400000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 100000000,
"maxRevenue": 85,
"fuelPrice": 1.0700000524520874
},
"rideStatus": 1,
"vehicle": {
"length": 0,
"weight": 0,
"width": 0,
"licensePlate": "",
"consumption": 6.5,
"fuelType": 2,
"make": "",
"id": 134764,
"name": "Car vehicle",
"model": "",
"costPerHour": 0,
"type": 0,
"status": 0,
"maxLoadWeight": 60,
"height": 0,
"maxLoadCube": 50,
"idDriver": 134764,
"endTime": 1439,
"fixedCost": 0,
"startTime": 420,
"lastPosition": [
2147483647,
2147483647
]
},
"destination": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"arrivalTime": 1596783691000,
"traveledDistance": 0.6638350486755371
},
"departure": {
"depotId": 0,
"alias": "Departure2",
"address": {
"streetNumber": "34",
"postalCode": "86000",
"streetName": "Boulevard Chasseigne",
"county": "Nouvelle-Aquitaine",
"state": "",
"extra": "",
"city": "Poitiers",
"country": "France"
},
"location": [
48.82674,
2.342116
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"numberOfpackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 1596783600000,
"timeToNext": 12,
"distanceToNext": 0.07019499689340591
},
"shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
"creationTimestamp": 1742220618730,
"neededFuel": 0.04314928129315376,
"matrixBuildType": 1,
"price": 0.04616973176598549,
"totalWaitTime": 0,
"totalServiceTime": 0,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"creationTimestamp": 1742220613856,
"cube": 0,
"numberOfPackages": 0,
"depotId": 0,
"customData": "",
"weight": 0,
"phoneNumber": "+12025550181",
"lastName": "",
"status": 1,
"firstName": "",
"alias": "",
"state": 1,
"type": 0,
"priority": 0,
"id": 876534,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
},
"customerInfo": {
"phoneNumber": "+12025550181",
"email": "c1@yahoo.com",
"lastName": "",
"firstName": "",
"alias": "",
"customData": "",
"id": 1786643,
"location": [
48.827327,
2.342267
],
"address": {
"streetNumber": "",
"postalCode": "",
"streetName": "",
"county": "",
"state": "",
"extra": "",
"city": "",
"country": ""
}
}
},
"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,
"traveledDistance": 0.07019499689340591,
"distanceToNextOrder": 0.5936400294303894,
"revenueAtArrival": 0,
"visitTimestamp": 0
}
],
"totalTime": 91,
"totalDistance": 0.6638350486755371
}