Asynchronous Request

The asynchronous request to get solution for the problem consists of several steps:

• The solution calculation request
• Polling for the solution status
• The request to download the solution.

Each of these steps is described in next sections. Please note, that the asynchronous request flow has a limit of 3000 jobs and 150 vehicle types.

Request a Solution for the Problem

Create a problem definition and send a solution calculation request to the corresponding endpoint:

POST https://tourplanning.hereapi.com/v2/problems/async
Authorization: Bearer <TOKEN>
Content-Type: application/json

Body:

{
  "plan": {
    "jobs": [
      {
        "id": "myJob",
        "places": {
          "deliveries": [
            {
              "location": {"lat": 52.46642, "lng": 13.28124},
              "times": [["2020-07-04T10:00:00.000Z","2020-07-04T12:00:00.000Z"]],
              "duration": 180,
              "demand": [1]
            }
          ]
        }
      }
    ]
  },
  "fleet": {
    "types": [
      {
        "id": "myVehicle",
        "profile": "normal_car",
        "costs": {
          "distance": 0.0002,
          "time": 0.005,
          "fixed": 22
        },
        "shifts": [{
          "start": {
            "time": "2020-07-04T09:00:00Z",
            "location": {"lat": 52.52568, "lng": 13.45345}
          },
          "end": {
            "time": "2020-07-04T18:00:00Z",
            "location": {"lat": 52.52568, "lng": 13.45345}
          }
        }],
        "limits": {
          "maxDistance": 300000,
          "shiftTime": 28800
        },
        "capacity": [10],
        "amount": 1
      }
    ],
    "profiles": [{
      "name": "normal_car",
      "type": "car",
      "departureTime": "2020-07-04T09:15:00Z"
    }]
  }
}

The service will return the following response body:

{
    "statusId": "<globally unique id>",
    "href": "https://tourplanning.hereapi.com/v2/status/<same as in statusId>"
}

The elements in the response are:

• statusId — a unique identifier of the status which is used for tracking the solution calculation status and for downloading the solution result.
• href — the URL for polling the status

Check the Status of the Solution

To get the status of a solution calculation for a given problem Id, use the href obtained when submitting a request:

> GET https://tourplanning.hereapi.com/v2/status/<statusId>
> Authorization: Bearer <token>
---
< HTTP/1.1 200 OK
< Content-Type: application/json

Body:

{
    "status": "pending"
}

If you get status pending or inProgress, then you should keep polling until the calculation is finished and status success, timeout or failure is returned.

A response with success returns a resource link to download the calculated solution:

{
    "status": "success",
    "resource": {
      "resourceId": "<globally unique id>",
      "href": "https://tourplanning.hereapi.com/v2/problems/<same as resourceId>/solution"
    }
}

A response with failure returns an error object:

{
    "status": "failure",
    "error": {
      "message": "There was an error solving the problem"
    }
}

You can use the statusId to get error details via the solution endpoint as described in the next section.

Download the Solution

If the status of a solution calculation is success, the calculated solution is available using the Id provided in the resourceId element which is effectively a problemId:

> GET https://tourplanning.hereapi.com/v2/problems/<problemId>/solution
> Content-Type: application/json

Response body:

{
  "statistic": {
    "cost": 54.459916,
    "distance": 35277,
    "duration": 5286,
    "times": {
      "driving": 5106,
      "serving": 180,
      "waiting": 0,
      "break": 0
    }
  },
  "tours": [
    {
      "vehicleId": "myVehicle_1",
      "typeId": "myVehicle",
      "stops": [
        {
          "location": {"lat": 52.52568, "lng": 13.45345},
          "time": {
            "arrival": "2020-07-04T09:19:01Z",
            "departure": "2020-07-04T09:19:01Z"
          },
          "load": [1],
          "activities": [
            {
              "jobId": "departure",
              "type": "departure"
            }
          ]
        },
        {
          "location": {"lat": 52.46642, "lng": 13.28124},
          "time": {
            "arrival": "2020-07-04T10:00:00Z",
            "departure": "2020-07-04T10:03:00Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "myJob",
              "type": "delivery"
            }
          ]
        },
        {
          "location": {"lat": 52.52568, "lng": 13.45345},
          "time": {
            "arrival": "2020-07-04T10:47:07Z",
            "departure": "2020-07-04T10:47:07Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "arrival",
              "type": "arrival"
            }
          ]
        }
      ],
      "statistic": {
        "cost": 54.459916,
        "distance": 35277,
        "duration": 5286,
        "times": {
          "driving": 5106,
          "serving": 180,
          "waiting": 0,
          "break": 0
        }
      }
    }
  ]
}

See solution topic for a detailed explanation.

If an error occurs during solving the problem, the error response is returned:

{
    "title": "Unprocessable entity",
    "status": 422,
    "code": "E613000",
    "cause": "E613420, 'Vehicle's arrival time is earlier than its departure time' 'Correct arrival time of 'vehicle' to be earlier than its departure'",
    "action": "",
    "correlationId": "REQ-497fdde4-048d-4db5-9d6e-8e44a952dede"
}

Requesting a solution of an unfinished calculation will result in the HTTP status code 404 Not Found.