Quick Start

This section outlines how to quickly get started using the Matrix Routing service:

  1. Get a HERE Account
  2. Register your App
  3. Get an API Key
  4. Send a Request

Note

This section provides information on the minimum setup required to quickly begin using the Matrix Routing service. For more detailed information on HERE account setup, app registration, and authentication, see the Identity & Access Management Developer Guide.

Get a HERE Account

If your organization has signed up for HERE Workspace or HERE Marketplace, contact your organization admin who can invite you to join the HERE platform organization established for your company. You can also request a free trial of the HERE platform if your company does not have an organization established for it. For more information, see the HERE platform pricing.

Register your App

To register your app, follow these steps:

  1. Sign in to the HERE platform using your HERE account.
  2. Open the Access Manager from the Launcher.
  3. On the Apps tab, click Register new app and provide the requested information.
  4. Click Register. The platform creates a new app with a unique app ID.

Get an API Key

To get an API key, follow these steps:

  1. Sign in to the HERE platform using your HERE account.
  2. Open the Access Manager from the Launcher.
  3. On the Apps tab, click the app you created in the previous section, Register your App, or an existing group app for which you want to generate an API key.
  4. On the Credentials tab, select API Keys then click Create API key to generate a maximum of two API Keys for your application authentication credentials. The API key is created and displayed.

Send a Request

Matrix Routing can be performed with a synchronous request or asynchronous request. All modes are available for both synchronous and asynchronous requests, however synchronous requests have additional limitations on matrix size. For a detailed description of available modes, see Modes.

Depending on the type of request, you need to follow different steps. Regardless of request type, you need to specify a regionDefinition. You can define a region containing the origins and destinations, or if you don't want to define the region yourself, simply request autoCircle as the regionDefinition type. For more information, see Region.

If you want to calculate a matrix with routes of arbitrary length, use region definition world. In this case you either need to specify one of the predefined profile IDs or, if you want to define custom options, limit the size of the matrix. For more information, see Profiles.

Synchronous Request

Using the synchronous API means sending a matrix calculation request to the server and waiting for the response. Synchronous requests have further limitations on matrix dimensions.

To request a synchronous matrix calculation set the async query parameter to a value of false, otherwise the contents of a synchronous matrix request are the same as those of an asynchronous request.

Then, submit a matrix calculation request. The service validates the request and adds it to a queue until resources are available to calculate the matrix. When the calculation is finished or if an error occurred, the service directly returns the matrix result.

Note the query parameter async=false in the following example:

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 request shown here. For details, see the Identity & Access Management Developer Guide.

POST https://matrix.router.hereapi.com/v8/matrix?async=false
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
    }
}

If you receive status code 200, your request was successfully calculated.

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
    },
    // same as request
    "regionDefinition": {
        "type": "circle",
        "center": {"lat": 0.0, "lng": 0.0},
        "radius": 10000
    }
}

In addition to the calculated routing matrix, the matrix result contains:

  • A matrixId - a unique identifier of the matrix.
  • A regionDefinition - the region definition used to calculate the matrix. Either the one specified by the user, or an automatically derived one (if autoCircle was requested).

Asynchronous Request

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

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 starts the calculation when resources are available.

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.
  • 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 (if 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 receive 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 automatically be redirected to the matrix result, which will redirect to an S3 resource.

Warning For users of API key authentication

The URL in the Location header returned from the status request doesn't include the apiKey parameter. You should configure your client to disable redirects, and instead download the matrix results as described in the following section. Ensure that you 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. 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 onflicting 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
    }
}

Note

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 ""