Update Route

_{Estimated reading time: 10 minutes}

Overview

This example demonstrates how to update an existing route by making changes to its configuration, vehicle constraints, and other fields. The updated route can also be reoptimized to generate a new order of visits. If the route is not reoptimized, the changes will not affect the route's optimization. However, certain configuration changes (e.g., ignoring time windows, optimization criteria, etc.) automatically trigger reoptimization.

For updating orders, refer to the following examples:

• Adding Orders to a Route
• Updating an Order from a Optimization
• Deleting an Order from a Route

How to Use the Sample

When you run the example application:

1. The existing route is updated with new configurations, vehicle constraints, and other fields.
2. The route is reoptimized (if specified), and a new order of visits is returned.

Step-by-Step Guide

Step 1: Retrieve the Existing Route

To update 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: Update the Route

Once the route is retrieved, you can update its fields, such as configuration parameters, vehicle constraints, and other properties.

Update Configuration Parameters

1. Retrieve the existing configuration parameters from the route.
2. Modify the desired fields, such as the name and route type.

"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"
	}

Update Vehicle Constraints

1. Retrieve the existing vehicle constraints from the route.
2. Modify the desired fields, such as the maximum number of packages and maximum distance.

	"vehicleConstraints": {
		"startDate": 1596758400000,
		"maxNumberOfPackages": 85,
		"minNumberOfOrders": 0,
		"maxNumberOfOrders": 99999999,
		"minDistance": 0,
		"maxDistance": 999999,
		"maxRevenue": 85,
		"fuelPrice": 1.0700000524520874
	}

Step 3: Update the Route and Retrieve the New Solution

Once the route is updated, you can apply the changes and retrieve the new solution.

1. Set the updated configuration parameters and vehicle constraints to the route.
2. Once the route is updated, call the updateRoute reuqest following the steps below.

• 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, *required) - The unique route ID.
• Query Parameter:
  • encodeShape (integer, not required) - 0: The route's shape will not be encoded. 1:(default) - The route's shape will be encoded.

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.

Example:

• Request Body:

{
"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,
  "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
}

• Response
• Code 200 : Successful operation!

{
  "id": 123456,
  "optimizationId": 123456,
  "routeId": 123456,
  "status": 0,
  "message": "Operation done successfully!",
  "creationTimestamp": 123456
}

Step 4: Retrieve the Updated Route

If the route update was successful then the request will end with code 200. A new route will be returned: Updated route response:

Example:

• Response Body: (error code 200)

{
"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,
  "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 update an existing route by modifying its configuration, vehicle constraints, and other fields. 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 ](/docs/fleet-management-rest-api/Introduction/Introduction).