Note, the HERE integration is available as an early access alpha. Using the HERE measure will result in charges to your HERE account. Make sure you understand these costs before using this measure. To find out more or to request early access to the alpha, please contact support.
HERE is a platform that provides a number of location-based APIs. The Nextmv Cloud API can leverage HERE's matrix routing service to make routing decisions informed by street routes and real-time or projected traffic conditions. Nextmv's HERE integration allows you to construct measures using HERE routing data, providing more accurate routes than the haversine measure.
Endpoints
Note, all requests must be authenticated with Bearer Authentication. Make sure your request has a header containing your Nextmv Cloud API key, as such:
- Key:
Authorization
- Value:
Bearer <YOUR-API-KEY>
Create a new HERE integration.
Create a new HERE integration. HERE is a mapping provider offering street data to estimate the distance and duration of going from A to B. HERE has the possibility to incorporate real-time or historical traffic data in their estimations.
Get an existing HERE integration.
Get an existing HERE integration using the `id` associated with it.
Modify an existing HERE integration.
Modify an existing HERE integration using the `id` associated with it.
Delete an existing HERE integration.
Delete an existing HERE integration using the `id` associated with it.
For the full specification, please visit the Nextmv Cloud API OpenAPI specification.
Using the integration
Follow the steps below to use the HERE integration.
- Get the Nextmv and HERE API keys. This only needs to be done once. Note, The HERE API key will need to be associated with a plan that has access to the HERE matrix API.
- Set up a HERE integration on Nextmv to securely store the HERE API key. We will securely store your API key and use it when you request new runs. This only needs to be done once.
- Create a run profile for using the HERE integration when requesting new runs, using the integration
id
andtype
obtained in the previous step. This only needs to be done once. - Follow the Nextmv Cloud API reference guide to create a new run, using the run profile
id
obtained in the previous step with therun_profile
key. When using a run profile with the HERE integration, you may also specify additional information to incorporate traffic. After, you can poll the status of your run and get the result. - Manage your configurations using the endpoints.
Note, the HERE integration can also be set up and edited through the Nextmv Cloud Console. See the console configuration page for more information.
Using Traffic Conditions in Your Measure
You can specify real-time or historical traffic data when using the HERE integration. Traffic data is specified in the run_profile
field of your JSON
input when making a new run using the departure_time
field (see example below). Specifying a departure_time
for your vehicles will cause HERE to factor traffic conditions into its route lengths in one of two ways:
- If you set
departure_time
to current time, HERE will use real-time conditions. - If you set
departure_time
to a future time, HERE will use estimates based on historical data.
The format for the departure time must follow an RFC3339 formatted timestamp.
See the HERE documentation for more information on historical and real-time traffic information. Note that we do not support the any
parameter used by HERE. If you want your route lengths to be calculated without considering traffic, simply omit the departure time parameter from the run profile. If you want to use current traffic conditions, provide a timestamp for the current time.
Cost
Your HERE account will incur charges for each run of a Nextmv model that uses a run profile configured with the HERE integration. Make sure you understand the cost implications of the HERE API before you start using the HERE integration. We recommend testing against the Nextmv API using another measure, such as the Streets or haversine (default) measures to avoid incurring significant costs during development.
For each run, Nextmv will request a matrix of routes where the number of sources and destinations are equal to the number of stops plus the number of vehicle stop and end locations. For example, if your run has 1000 stops and 20 vehicles, each with start and end locations, we will request a 1040x1040 matrix.
HERE charges based on the number of "transactions" your account performs, as described in the HERE documentation. The exact cost per transaction depends on your HERE account's plan.
Set up the integration
The HERE integration lets you securely store one or more HERE API keys inside of Nextmv Cloud. Send a request to the /v1/routing/profiles/integration/here
endpoint with a JSON
payload that follows this schema:
Key | Description | Required | Sample value | Type |
---|---|---|---|---|
name | Human-readable name to identify the integration key. | Yes | "Sample HERE integration key" | string |
description | A description of the integration. | No | "Sample HERE integration description" | string |
id | ID for the HERE integration; only lower case letters, numbers, and dashes permitted; max length 32 characters. | Yes | "here-key" | string |
configuration | Object with the HERE API key you want to set. | Yes | { "api_key": "<YOUR_ONFLEET_API_KEY>" } | object |
A sample schema and response are provided below:
Make sure to store the id
and type
, as you will need them to add the integration to your run profile. Please note that you may set up multiple integration profiles using this method. You only need to do this process once for each API key.
To modify an existing HERE integration, you can use the PUT /v1/routing/profiles/integration/here/{profile_id}
endpoint with a JSON
payload that follows the same schema as when creating a new integration (described in the table above). Note that you may not modify the original id
.