Quick Start - Sequence Optimization API

With the Sequence Optimization service you can find the best route for your transports. To schedule a route, the first step is to start the optimization, the second is to retrieve the optimized route.

For an easy integration you can use the clients for Java, C# and TypeScript on GitHub.

Please note the individual rate and request limits for each API. You can find all limits in our FAQ.

Get your free API Access Key

Start optimization

Use the following endpoint via POST to schedule a route.

https://api.myptv.com/sequenceoptimization/v1/routes

The following simple request with two transports is inserted into the request body in JSON representation.

{
  "locations": [
    {
      "id": "Depot",
      "type": "DEPOT",
      "latitude": 49.010940598,
      "longitude": 8.408450135,
      "openingIntervals": [
        {
          "start": "2020-12-06T08:00:00+00:00",
          "end": "2020-12-06T18:00:00+00:00"
        }
      ]
    },
    {
      "id": "Customer",
      "type": "CUSTOMER",
      "latitude": 48.767780269,
      "longitude": 9.1720305036,
      "openingIntervals": [
        {
          "start": "2020-12-06T10:00:00+00:00",
          "end": "2020-12-06T11:00:00+00:00"
        }
      ]
    }
  ],
  "vehicle": {
    "profile": "EUR_VAN",
    "capacities": [
      500
    ],
    "startLocationId": "Depot",
    "endLocationId": "Depot"
  },
  "driver": {
    "availability": {
      "start": "2020-12-06T00:00:00+00:00",
      "end": "2020-12-07T00:00:00+00:00"
    }
  },
  "transports": [
    {
      "id": "Transport1",
      "quantities": [
        100
      ],
      "pickupLocationId": "Customer",
      "pickupServiceTime": 60,
      "deliveryLocationId": "Depot",
      "deliveryServiceTime": 60
    },
    {
      "id": "Transport2",
      "quantities": [
        100
      ],
      "pickupLocationId": "Depot",
      "pickupServiceTime": 60,
      "deliveryLocationId": "Customer",
      "deliveryServiceTime": 60
    }
  ]

}

You can test the simple request by choosing one of the following options.

cURL:

curl --location --request POST "https://api.myptv.com/sequenceoptimization/v1/routes" --header "Content-Type: application/json" --header "ApiKey: YOUR_API_KEY" --data-raw "{ \"locations\": [ { \"id\": \"Depot\", \"type\": \"DEPOT\", \"latitude\": 49.010940598, \"longitude\": 8.408450135, \"openingIntervals\": [ { \"start\": \"2020-12-06T08:00:00+00:00\", \"end\": \"2020-12-06T18:00:00+00:00\" } ] }, { \"id\": \"Customer\", \"type\": \"CUSTOMER\", \"latitude\": 48.767780269, \"longitude\": 9.1720305036, \"openingIntervals\": [ { \"start\": \"2020-12-06T10:00:00+00:00\", \"end\": \"2020-12-06T11:00:00+00:00\" } ] } ], \"vehicle\": { \"profile\": \"EUR_VAN\", \"capacities\": [ 500 ], \"startLocationId\": \"Depot\", \"endLocationId\": \"Depot\" }, \"driver\": { \"availability\": { \"start\": \"2020-12-06T00:00:00+00:00\", \"end\": \"2020-12-07T00:00:00+00:00\" } }, \"transports\": [ { \"id\": \"Transport1\", \"quantities\": [ 100 ], \"pickupLocationId\": \"Customer\", \"pickupServiceTime\": 60, \"deliveryLocationId\": \"Depot\", \"deliveryServiceTime\": 60 }, { \"id\": \"Transport2\", \"quantities\": [ 100 ], \"pickupLocationId\": \"Depot\", \"pickupServiceTime\": 60, \"deliveryLocationId\": \"Customer\", \"deliveryServiceTime\": 60 } ] }"

PowerShell:

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("ApiKey", "YOUR_API_KEY")
$headers.Add("Content-Type", "application/json")

$body='{ "locations": [ { "id": "Depot", "type": "DEPOT", "latitude": 49.010940598, "longitude": 8.408450135, "openingIntervals": [ { "start": "2020-12-06T08:00:00+00:00", "end": "2020-12-06T18:00:00+00:00" } ] }, { "id": "Customer", "type": "CUSTOMER", "latitude": 48.767780269, "longitude": 9.1720305036, "openingIntervals": [ { "start": "2020-12-06T10:00:00+00:00", "end": "2020-12-06T11:00:00+00:00" } ] } ], "vehicle": { "profile": "EUR_VAN", "capacities": [ 500 ], "startLocationId": "Depot", "endLocationId": "Depot" }, "driver": { "availability": { "start": "2020-12-06T00:00:00+00:00", "end": "2020-12-07T00:00:00+00:00" } }, "transports": [ { "id": "Transport1", "quantities": [ 100 ], "pickupLocationId": "Customer", "pickupServiceTime": 60, "deliveryLocationId": "Depot", "deliveryServiceTime": 60 }, { "id": "Transport2", "quantities": [ 100 ], "pickupLocationId": "Depot", "pickupServiceTime": 60, "deliveryLocationId": "Customer", "deliveryServiceTime": 60 } ] }'

try
{
    $response = Invoke-RestMethod 'https://api.myptv.com/sequenceoptimization/v1/routes' -Method 'POST' -Headers $headers -Body $body
    $response | ConvertTo-Json -Depth 10
}
catch
{
    $streamReader = [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream())
    $streamReader.ReadToEnd() | ConvertFrom-Json
    $streamReader.Close()
}

The result is the unique ID of the optimized route.

{
  "id": "12c4e609-1f81-4b77-bd62-855f4f5f447c"
}

This ID is used in the following step in the URL path, indicated as {id}.

Get optimized route

The optimized route can be retrieved via GET from the following endpoint.

https://api.myptv.com/sequenceoptimization/v1/routes/{id}

The response contains status information about the optimization and, if the optimization is finished, the optimized route. The optimized route contains general information, e.g. total travel time, and the route itself. The route consists of a sequence of stops. Consider the following JSON representation for an example.

{
  "status": "SUCCEEDED",
  "optimizedRoute": {
    "route": [
      {
        "locationId": "Depot",
        "deliveryIds": [],
        "pickupIds": [
          "Transport2"
        ],
        "reportForWayToStop": {
          "distance": 0,
          "drivingTime": 0,
          "breakTime": 0
        },
        "reportForStop": {
          "arrivalTime": "2020-12-06T09:10:03.0000000+00:00",
          "departureTime": "2020-12-06T09:11:03.0000000+00:00",
          "serviceTime": 60,
          "waitingTime": 0,
          "breakTime": 0,
          "quantities": [
            100
          ]
        },
        "eventsOnWayToStop": [],
        "eventsAtStop": [
          {
            "type": "ROUTE_START",
            "startTime": "2020-12-06T09:10:03.0000000+00:00",
            "duration": 0,
            "transportId": null
          },
          {
            "type": "SERVICE",
            "startTime": "2020-12-06T09:10:03.0000000+00:00",
            "duration": 60,
            "transportId": "Transport2"
          }
        ],
        "violationsOnWayToStop": [],
        "violationsAtStop": []
      },
      {
        "locationId": "Customer",
        "deliveryIds": [
          "Transport2"
        ],
        "pickupIds": [
          "Transport1"
        ],
        "reportForWayToStop": {
          "distance": 77599,
          "drivingTime": 2937,
          "breakTime": 0
        },
        "reportForStop": {
          "arrivalTime": "2020-12-06T10:00:00.0000000+00:00",
          "departureTime": "2020-12-06T10:02:00.0000000+00:00",
          "serviceTime": 120,
          "waitingTime": 0,
          "breakTime": 0,
          "quantities": [
            100
          ]
        },
        "eventsOnWayToStop": [
          {
            "type": "DRIVING",
            "startTime": "2020-12-06T09:11:03.0000000+00:00",
            "duration": 2937,
            "transportId": null
          }
        ],
        "eventsAtStop": [
          {
            "type": "SERVICE",
            "startTime": "2020-12-06T10:00:00.0000000+00:00",
            "duration": 60,
            "transportId": "Transport2"
          },
          {
            "type": "SERVICE",
            "startTime": "2020-12-06T10:01:00.0000000+00:00",
            "duration": 60,
            "transportId": "Transport1"
          }
        ],
        "violationsOnWayToStop": [],
        "violationsAtStop": []
      },
      {
        "locationId": "Depot",
        "deliveryIds": [
          "Transport1"
        ],
        "pickupIds": [],
        "reportForWayToStop": {
          "distance": 77123,
          "drivingTime": 2926,
          "breakTime": 0
        },
        "reportForStop": {
          "arrivalTime": "2020-12-06T10:50:46.0000000+00:00",
          "departureTime": "2020-12-06T10:51:46.0000000+00:00",
          "serviceTime": 60,
          "waitingTime": 0,
          "breakTime": 0,
          "quantities": null
        },
        "eventsOnWayToStop": [
          {
            "type": "DRIVING",
            "startTime": "2020-12-06T10:02:00.0000000+00:00",
            "duration": 2926,
            "transportId": null
          }
        ],
        "eventsAtStop": [
          {
            "type": "SERVICE",
            "startTime": "2020-12-06T10:50:46.0000000+00:00",
            "duration": 60,
            "transportId": "Transport1"
          },
          {
            "type": "ROUTE_END",
            "startTime": "2020-12-06T10:51:46.0000000+00:00",
            "duration": 0,
            "transportId": null
          }
        ],
        "violationsOnWayToStop": [],
        "violationsAtStop": []
      }
    ],
    "startTime": "2020-12-06T09:10:03.0000000+00:00",
    "endTime": "2020-12-06T10:51:46.0000000+00:00",
    "travelTime": 6103,
    "distance": 154722,
    "drivingTime": 5863,
    "serviceTime": 240,
    "waitingTime": 0,
    "breakTime": 0,
    "unplannedTransportIds": null
  },
  "error": null
}

You can retrieve the response by choosing one of the following options.

cURL:

curl --location --request GET https://api.myptv.com/sequenceoptimization/v1/routes/{id} --header "ApiKey: YOUR_API_KEY"

PowerShell:

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("ApiKey", "YOUR_API_KEY")

$response = Invoke-RestMethod 'https://api.myptv.com/sequenceoptimization/v1/routes/{id}' -Method 'GET' -Headers $headers
$response | ConvertTo-Json -Depth 10