Migrate to 1.1.3

_|

This guide outlines the changes introduced in REST API version 1.1.3. Required updates may vary depending on your use case.

Version 1.1.3 introduces significant changes to the response formats and adds new capabilities.

Breaking Changes

1. /optimize endpoint - asynchronous execution:

   • Major Change: /optimize now returns a request object instead of immediate results
   • New Workflow: Submit request → Get requestId → Poll for completion → Retrieve solution
   • New Endpoint: /optimize/solution endpoint added for retrieving solutions

2. /optimize endpoint schema changes:

   • Added support for user-defined matrices when matrixBuildType = 0
   • Added orders sequences option for specifying delivery order constraints

3. /optimizations/solution and /optimizations/{id}/solution endpoints:

   • Output format changed: added droppedOrders field

Changes to /optimize endpoint schema

Input Schema Changes

• Added user-defined matrices only when matrixBuildType = 0 (matrices are set by user)
• Added orderSequenceOptions option for making association between orders that should be visited in a certain order.

Previous version of input:

{
  "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
  },
  "orders": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "departures": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ]
    }
  ],
  "destinations": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ]
    }
  ],
  "vehicles": [
    {
      "name": "string",
      "type": 0,
      "maxLoadWeight": 0,
      "maxLoadCube": 0,
      "startTime": 0,
      "endTime": 1439,
      "licensePlate": "string",
      "consumption": 0
    }
  ],
  "vehiclesConstraints": [
    {
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ]
}

Updated version of input:

{
  "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": [[1, 4], [3, 7]]
  },
  "matrixBuildType": 0,
  "matrices": [
     {
       "vehicleType": 0,
       "distMatrix": [
         [0, 612.4, 389.7],
         [612.4, 0, 467.2],
         [389.7, 467.2, 0]
       ],
       "timeMatrix": [
         [0, 205, 128],
         [205, 0, 150],
         [128, 150, 0]
       ]
     }
   ],
  "orders": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "departures": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ]
    }
  ],
  "destinations": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ]
    }
  ],
  "vehicles": [
    {
      "name": "string",
      "type": 0,
      "maxLoadWeight": 0,
      "maxLoadCube": 0,
      "startTime": 0,
      "endTime": 1439,
      "licensePlate": "string",
      "consumption": 0
    }
  ],
  "vehiclesConstraints": [
    {
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ]
}

Output Schema Changes

Note

Solving an /optimize request returns a request object that allows you to track the optimization process status. Once the request status is completed, retrieve the solution using the new /optimize/{id}/solution endpoint.

The solution contains one or more routes, where each route represents a vehicle's trip to visit assigned orders. The maximum number of routes returned equals the number of vehicles provided in the request.

Previous version of output:

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

Updated version of output:

• Use new /optimize/solution?requestId={id} endpoint to retrieve results

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

New /optimize/{id}/solution Endpoint

Version 1.1.3 introduces a new endpoint specifically for retrieving optimization solutions:

Endpoint: GET /optimize/{id}/solution

Purpose: Retrieve the solution for a previously submitted /optimize request.

Migration Summary

Breaking Changes - Immediate Action Required

• Update /optimize integration to handle asynchronous request/response pattern
• Implement polling mechanism using new /optimize/{id}/solution endpoint
• Handle request tracking object instead of direct solution response

Optional Enhancements

• Use user-defined matrices by setting matrixBuildType = 0 and providing matrices
• Implement order sequences using orderSequenceOptions in configuration parameters

Critical Update

The asynchronous execution change for /optimize is a breaking change. Applications will fail without updating the integration workflow.