Quick start - HERE developer portal

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

  1. Get a HERE account
  2. Register your app
  3. Get an API key
  4. Creating a sample application

Note

This section provides information on the minimum setup required to begin quickly 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 you are an individual developer who has signed up for one of the plans listed on our Developer plans page on developer.here.com., you received a HERE account ID when you signed up. You can use your HERE account to log in to developer.here.com. to create applications. Applications (uniquely identified by an app ID) enable development with HERE products and services.

Register your app

To register your app, follow these steps:

  1. Sign in to developer.here.com..
  2. Click your name, select Projects, and then choose your project from the list. Your project details and available application credentials are then displayed.
  3. Select JavaScript or REST and click Generate App. When your application is created, its app ID is displayed.

Get an API key

To get an API key, follow these steps:

  1. Sign in to developer.here.com..
  2. Click your name, select Projects, and then choose your project from the list. Your project details and available application credentials are then displayed.
  3. Click Create API key to generate a maximum of two API keys for your application. 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 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
    }
}

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