Asynchronous Request

When using the asynchronous API, the full matrix calculation cycle consists of several requests to the service:

  • The matrix calculation request
  • Polling of the calculation status
  • The request to download the matrix result.

Each of these steps is described below.

Request a Matrix Calculation

Create a new matrix calculation request. If the request is valid, the service adds it to the queue of all matrix calculations and, when resources are available, starts the calculation.

Note

Depending on your authentication method you either need to add an Authorization header with a Bearer token or a query parameter to the example requests shown here. For details, see the Identity & Access Management Developer Guide.

> POST https://matrix.router.hereapi.com/v8/matrix
> Authorization: Bearer <token>
> Content-Type: application/json

with a JSON request body:

{
    "origins": [{"lat": 0.0, "lng": 0.0}, {"lat": 0.1, "lng": 0.1}, ...],
    "destinations": [...],  // if omitted, origins are used as destinations
    "regionDefinition": {
        "type": "circle",
        "center": {"lat": 0.0, "lng": 0.0},
        "radius": 10000
    }
}

The response to the above request is:

{
    "matrixId": "<globally unique id>",
    "status": "inProgress",
    "statusUrl": "<url to status endpoint>",
    "error": {
    // error object in case of an error
    },
    "regionDefinition": "<same as in request>"
}

The elements in the response are:

  • matrixId — a unique identifier of the matrix which is used for tracking the calculation status and for downloading the matrix result.
  • status — the status of the calculation.
  • statusUrl — the URL to poll the status of
  • error — an error object, usually returned when the request did not pass validation.
  • regionDefinition — the region definition used to calculate the matrix. Either the one specified by the user, or an automatically derived one (in case autoCircle was requested).

Poll the Status of the Matrix Calculation

To get the status of a matrix calculation for a given matrix ID, use the statusUrl obtained when submitting a request:

> GET <statusUrl>
> Authorization: Bearer <token>
---
< HTTP/1.1 303 See Other
< Content-Type: application/json
< Location: <url to download calculation result>

The response is the same schema as the initial calculation request:

{
    "matrixId": "<globally unique id>",
    "status": "completed",
    "resultUrl": "<url to download calculation result>",
    "error": {
        // error object in case of an error
    },
    // same as request
    "regionDefinition": {
        "type": "circle",
        "center": {"lat": 0.0, "lng": 0.0},
        "radius": 10000
    }
}

if you get status code 200, status accepted or inProgress, then you should keep polling until the calculation is finished and the HTTP status code 303 See Other is returned. A Location header which coincides with the field resultUrl is added with the location to the matrix result. Clients which support automatic redirect, will be automatically redirected to the matrix result (which will, in turn redirect to an S3 resource -- see Download the Matrix Result, below).

Warning: For users of API key authentication

The URL in the Location header returned from the status request does not include the apiKey parameter. You should therefore configure your client to disable redirects, and instead download the matrix results as described below, making sure to include the API key query parameter in your request.

Download the Matrix Result

If the status of a matrix calculation is completed, the calculated matrix is available using the ID provided in the matrixId element. Requesting a matrix result of an unfinished calculation will result in the HTTP status code 404 Not Found.

> GET <resultUrl>
> Content-Type: application/json
> Accept-Encoding: gzip

The response to the above request delivers a redirect to a compressed (gzip) JSON document.

Note that the redirect is a self-signed URL to an S3 resource.

Warning: For users of OAuth 2.0 Authentication

Some clients are configured to add the Authorization header to each request, even after a redirect. Such clients will produce an error when accessing the self-signed S3 URL due to conflicting authorization methods. Make sure that the Authorization header is not sent to the S3 endpoint.

The matrix result has the following structure:

{
    "matrixId": "{matrixId}",
    "matrix": {
        "numOrigins": 10,
        "numDestinations": 1000,
        // 10,000 travel times
        // entry k corresponds to origin i and destination j by the formula:
        // k = num_origins * i + j
        "travelTimes": [10, 20, 0, ...],
        "errorCodes": [0, 0, 0, ...]   // error for each pair of (origin, dest) if any
    },
    "error" {
        // error object in case of an error
    }
}

Please note that the results of previous matrix calculations are discarded after some time and will only be available for the next few hours.

results matching ""

    No results matching ""