Get started

This section outlines how to quickly get started using the Matrix Routing service on the HERE platform.

1. Get a HERE account
2. Get an API key
3. Send a request

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.

Get an API Key

To get an API Key, you should first create an app. To create an app, follow these steps:

1. Sign in to the HERE platform using your HERE account.
2. Open the Access Manager from the launcher.
3. Select the tab Apps.
4. Click Register new app.
5. Enter a name for the app.
6. Select No project under Default access to a project.
7. Click Register.

To get an API key, follow these steps:

1. Open your app by clicking onto the app name in the list on the Apps tab.
2. Select the tab Credentials.
3. Click API Keys.
4. Click Create API Key.

Send a request

Matrix Routing can be performed with a synchronous requst 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 these tutorials:

• Calculate routes in Flexible mode
• Calculate routes in Region mode
• Calculate routes in Profile mode

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:

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_destinations * 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:

• The matrix calculation request.
• Polling the calculation status.
• Downloading the matrix result.

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.

> 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 as follows

• 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 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_destinations * 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
    }
}

Next steps

For a full list of available examples, see the Tutorials chapter. For the terms and conditions covering this documentation, see the HERE Documentation License. Data privacy is of fundamental importance to HERE and our customers. We practice data minimization and don't collect data we don't need. And we promote pseudonymity for data subjects wherever a service does not require personal information to function. We employ privacy by design in services we develop. We strive to go beyond mere regulatory compliance and make privacy an integral part of our corporate culture. We believe that our approach to privacy is vital to earning and retaining the trust of our customers - and the bedrock of our future success as a data-driven location platform. For more information on how data privacy is of fundamental importance to HERE and our customers, see the HERE Privacy Charter).