Streets
You will learn how to use the Streets integration.
Note, the Streets integration is available as an early access alpha. The alpha includes street information for the entire planet, using a car profile to determine route distance and duration. To find out more about Streets or to request early access to the alpha, please contact support.
Note, if you observe a large number of unassigned stops when using the Streets measure, it may be due to overly restrictive time-based constraints. You may need to adjust these constraints to account for longer durations with real-road networks.
Streets is an integration for extending Nextmv measures using real road networks when calculating the distance between two points. While the haversine measure can quickly estimate the cost of traveling between two points, this measure can be limited in its accuracy as it is based on "as the crow flies" distance. The Streets measure takes into account conditions such as one-way roads, bodies of water and speed limits when calculating distances and durations. Vehicle profiles are used to determine speed, so vehicle speeds do not need to be specified in the input file.

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>
Bash
1
Authorization: Bearer <YOUR-API-KEY>
Copied!
post
https://api.cloud.nextmv.io
/v1/routing/profiles/integration/streets
Create a new Streets integration.
get
https://api.cloud.nextmv.io
/v1/routing/profiles/integration/streets/{integration_id}
Get an existing Streets integration.
put
https://api.cloud.nextmv.io
/v1/routing/profiles/integration/streets/{integration_id}
Modify an existing Streets integration.
delete
https://api.cloud.nextmv.io
/v1/routing/profiles/integration/streets/{integration_id}
Delete an existing Streets integration.
For the full specification, please visit the Nextmv Cloud API OpenAPI specification.

Using the integration

Follow the steps below to use the Streets integration.
  1. 1.
    Contact support to request access to the Streets integration alpha.
  2. 2.
    Once your account has been granted access, get your Nextmv API key and set up a Streets integration. This only needs to be done once.
  3. 3.
    Create a run profile for using the Streets integration when requesting new runs, using the integration id and type obtained in the previous step. This only needs to be done once.
  4. 4.
    Follow the Nextmv Cloud API reference guide to create a new run, using the run profile id obtained in the previous step with the run_profile key. After, you can poll the status of your run and get the result.
  5. 5.
    Manage your configurations using the endpoints.
Note, the Streets integration can also be set up and edited through the Nextmv Cloud Console. See the console configuration page for more information.

Set up the integration

Send a request to the /v1/routing/profiles/integration/streets 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 Streets integration key"
string
description
A description of the integration.
No
"Sample Streets integration description"
string
id
ID for the Streets integration; only lower case letters, numbers, and dashes permitted; max length 32 characters.
Yes
"streets-key"
string
A sample schema and response are provided below:
sample schema (JSON)
sample response (JSON)
1
{
2
"name": "My Streets Configuration",
3
"id": "my-streets-integration"
4
}
Copied!
1
{
2
"name": "My Streets Configuration",
3
"id": "my-street-integration",
4
"version": "2022-01-13T18:22:07.472728Z",
5
"type": "streets"
6
}
Copied!
Make sure to store the id and type, as you will need them to add the integration to your run profile.
To modify an existing Streets integration, you can use the PUT /v1/routing/profiles/integration/streets/{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.