Send a Request

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. If you don't want to define the region yourself, simply request autoCircle as the regionDefinition type. You can provide a margin, or use the default value. See Region. If you want to calculate a matrix with routes of arbitrary length you need to specify one of the predefined profile IDs and use region definition world. See Profiles.

POST https://largescalematrix.router.hereapi.com/v1/matrix
Authorization: Bearer <TOKEN>
Content-Type: application/json
Body:
{
    "origins": [{"lat": 0.0, "lng": 0.0}, {"lat": 0.1, "lng": 0.1}, ...],
    "destinations": [...],  // if omitted same as origins
    "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.
  • 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 on, in case autoCircle was requested.

Check the Status of the Matrix Calculation

To get the status of a matrix calculation for a given matrix ID, use this request:

GET https://largescalematrix.router.hereapi.com/v1/{matrix_id}/status
Authorization: Bearer <TOKEN>
Content-Type: application/json

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

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

If the calculation was finished successfully, the HTTP status code 303 See Other and a Location header which coincides with the field resultUrl is added with the location to the matrix result. Therefore, clients which support automatic redirect, will be automatically redirected to the result.

Download the Calculated Matrix

If the status of a matrix calculation is completed, the calculated matrix is available at 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 https://largescalematrix.router.hereapi.com/v1/{matrix_id}
Authorization: Bearer <TOKEN>
Content-Type: application/json

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. Some clients are configured to add the Bearer authorization header to each requests, 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 correponds 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
    }
}

results matching ""

    No results matching ""