Reoptimize Route
Overview
This example demonstrates how to reoptimize an existing route to rearrange the orders in a better sequence of visits, if such a sequence exists. The reoptimization process uses the latest fuel prices to calculate the route's cost. For more details on retrieving fuel prices, refer to the Get Fuel Prices.
How to Use the Sample
When you run the example application:
- The existing route is reoptimized to improve the order of visits.
- The updated route is returned, reflecting the new sequence and cost.
Step-by-Step Guide
Step 1: Retrieve the Existing Route
To reoptimize a route, you first need to retrieve the existing route using 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.
Example:
- Response Body: (error code
200)
{
"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,
"optimizationId": 137211,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
1596783600000,
1596823600000
],
"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,
"id": 250806
}
Step 2: Reoptimize the Route
Once the route is retrieved, you can reoptimize it to improve the order of visits.
- 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.
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": 123456,
"optimizationId": 123456,
"routeId": 123456,
"status": 0,
"message": "Operation done successfully!",
"creationTimestamp": 123456
}
Step 3: Retrieve the Reoptimized Route
After the reoptimization process is complete, you can retrieve the updated route.
- 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.
Example:
- Response Body: (error code
200)
{
"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,
"optimizationId": 137211,
"orders": [
{
"orderInfo": {
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
1596783600000,
1596823600000
],
"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,
"id": 250806
}
Conclusion
This example demonstrates how to reoptimize an existing route to improve the order of visits and recalculate the route's cost using the latest fuel prices. By following the steps above, you can adapt this example to your specific use case and integrate it into your fleet management workflow.
For more details, refer to the RestAPI documentation .