Configuration is defined using profiles in Nextmv Cloud. Profiles let you define a configuration once for settings that are consistent across runs, and use it within a run by referencing the profile identifier. For certain types of functionality you'll need to define a run profile in order to be able to use the feature. For example, some integration profiles require you to specify a secret API key that you wouldn't necessarily want to provide repeatedly. With a run profile, you can set it once so we can store and manage the key securely.
We support two types of profiles: run profiles and integration profiles.
A run profile lets you configure information that impacts the behavior of a run.
An integration profile lets you configure information used for integrations.
Note, integrations and run profiles can be set up and edited through the Nextmv routing app API or Nextmv Console.
To use third-party integrations as part of a run, they must be referenced in a run profile. First configure the integrations and then create or update a run profile with your integration(s).
Run profiles
Run profiles let you configure information that impacts the behavior of a run but does not vary run to run, for example the type of measure used. A run profile optionally contains references to zero or more integration profiles. To create a run profile, send a request to the POST /v1/routing/profiles/run
endpoint with a JSON
payload that follows this schema:
Property | Required | Field name | Type | Description | Example |
---|---|---|---|---|---|
Name | Yes | name | string | Human-readable name to identify the run profile. | "name": "Sample run profile" |
ID | Yes | id | string | ID of the run profile; only lower case letters, numbers, and dashes permitted; max length 32 characters. | "id": "onfleet-run-profile" |
Description | No | description | string | A description of the run profile. | "description": "Delivery profile" |
Integrations | No | integrations | array of object | List of previously configured integrations you want to make available for the run profile. | "integrations": [{ "id": "onfleet-key", "type": "onfleet" }] |
Each integration object follows this schema:
Property | Required | Field name | Type | Description | Example |
---|---|---|---|---|---|
Type | Yes | type | string | Type of integration. | "type": "onfleet" |
ID | Yes | id | string | ID of a previously configured integration. | "id": "my-onfleet-integration" |
A sample schema and response are provided below:
Make sure to store the id
, as you will need it when creating a new run. Please note that you may set up multiple run profiles using this method. You only need to do this process once for each API key.
To modify an existing run profile, you can use the PUT /v1/routing/profiles/run/{profile_id}
endpoint with a JSON
payload that follows the same schema as when creating a new run profile (described in the table above). Note that you may not modify the original id
.
Onfleet integration
Onfleet is a logistics software focused on dispatch and fleet management. You can leverage the power of Nextmv's cloud API with the Onfleet integration.
Follow the steps below to configure the Onfleet integration.
- Nextmv will not push any information to the Onfleet API on your behalf. The integration is read-only.
- Onfleet is considered to be the source of truth for tasks (stops) and workers (vehicles).
- We highly recommend reading the routing app tutorial and API reference section given that using the Onfleet integration follows a very similar logic.
- Create the tasks and workers you want to route. To leverage the full feature set of the Nextmv Cloud API, please check out the following sections:
- Compatible features. Onfleet's API functionality that is compatible with Nextmv Cloud API.
- Extensible features. Use Nextmv Cloud API features not supported by the Onfleet API.
- Get the Nextmv and Onfleet API keys. This only needs to be done once.
- Set up an Onfleet integration on Nextmv to securely store the Onfleet API key.
- Create a run profile for using the Onfleet integration when requesting new runs, using the integration
id
andtype
obtained in the previous step. This only needs to be done once. - Send a request to the
/v1/integrations/onfleet/run
endpoint with aJSON
body that follows the input schema to route and assign the desired tasks and workers, using the run profileid
obtained in the previous step with therun_profile
key. The API server should return arun_id
that you will use to query your results. This means that a Nextmv solver has been spun up to solve the model with the given input. The time it takes to finish execution varies by the size of the input and solver options. - Poll the status of your run with the
/v0/run/{run_id}/status
endpoint, using therun_id
. Once the status issucceeded
, you can query your results. Please see our section on using the API for more information. - Get the result of your run with the
/v0/run/{run_id}/result
endpoint, using therun_id
. The result holds the Onfleet containers that represent the final assignments of tasks to workers and it will follow the structure of the output schema. Please see our section on using the API for more information. - Update the container's tasks in the Onfleet API using the results optimized by the Nextmv Cloud routing engine.
- Manage your configurations using the Onfleet endpoints.
Note, the Onfleet integration can also be set up and edited through the Nextmv Console.
Set up the Onfleet integration
The Onfleet integration lets you securely store one or more Onfleet API keys inside of Nextmv Cloud. Send a request to the /v1/routing/profiles/integration/onfleet
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 Onfleet integration key" | string |
description | A description of the integration. | No | "Sample Onfleet integration description" | string |
id | ID for the Onfleet integration; only lower case letters, numbers, and dashes permitted; max length 32 characters. | Yes | "onfleet-key" | string |
configuration | Object with the Onfleet configurations you want to set. | Yes | { "api_key": "<YOUR_ONFLEET_API_KEY>" } | object |
The configuration
object allows you to securely store your Onfleet API key and optionally set up the compatibility
feature explained below.
Key | Description | Required | Sample value | Type |
---|---|---|---|---|
api_key | Onfleet API key. | Yes | "<YOUR_ONFLEET_API_KEY>" | string |
compatibility | Flags to toggle on/off compatible attributes for tasks and workers. | No | { "tasks": {"quantity": false}, "workers": {"capacity": false} } | object |
The compatibility
object allows you to fine-tune which task and worker attributes are automatically parsed when supported by compatible functionality. Using the compatibility
feature is optional. Any attribute that is not explicitly defined as false
will be automatically parsed as true
. The object follows this schema:
Key | Description | Required | Sample value | Type |
---|---|---|---|---|
tasks | Flags to toggle on/off compatible Onfleet task attributes when parsing to a Nextmv stop. | No | { "service_time": false, "quantity": true } | object |
workers | Flags to toggle on/off compatible Onfleet worker attributes when parsing to a Nextmv vehicle. | No | { "capacity": false, "tasks": true } | object |
In the following two tables you will find the schema definition for the tasks
and workers
object, respectively.
tasks
schema (you can read more about compatible Onfleet task attributes here):Key Description Required Sample value Type complete_before_after
Parse the Onfleet task's completeBefore
andcompleteAfter
into a Nextmv stop'shard_window
.No false
boolean
dependencies
Parse the Onfleet task's dependencies
into Nextmv stop'ssucceeds
.No false
boolean
location
Parse the Onfleet task's destination.location
into the Nextmv stop'sposition
. NOTE: if you turn this toggle off (false
) you should make sure that you are specifyingposition
via task metadata, otherwise your stop will not have a location and will cause an error.No false
boolean
quantity
Parse the Onfleet task's quantity
into the Nextmv stop'squantity
.No false
boolean
service_time
Parse the Onfleet task's serviceTime
into the Nextmv stop'sstop_duration
.No false
boolean
workers
schema (you can read more about compatible Onfleet worker attributes here):Key Description Required Sample value Type active_task
Parse the Onfleet worker's activeTask
to be part of the Nextmv vehicle'sbacklog
.No false
boolean
capacity
Parse the Onfleet worker's capacity
into the Nextmv vehicle'scapacity
.No false
boolean
location
Parse the Onfleet worker's location
into the Nextmv vehicle'sstart
position.No false
boolean
tasks
Parse the Onfleet worker's tasks
to be part of the Nextmv vehicle'sbacklog
.No false
boolean
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 Onfleet integration, you can use the PUT/v1/routing/profiles/integration/onfleet/{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
.
Compatible functionality
Onfleet's API offers functionality that is compatible with Nextmv Cloud API. If compatible attributes are defined for tasks and/or workers, they will be parsed to Nextmv features. In the following tables you will find a list of these attributes.
Note, all the compatible fields for tasks and workers are parsed by default. You can toggle off (or back on) the specific fields you would like to automatically parse using the compatibility
feature in the Onfleet integration profile.
Task compatible attributes
Onfleet attribute | Onfleet type | Onfleet example | Nextmv attribute | Nextmv type (Go) | Nextmv example |
---|---|---|---|---|---|
completeBefore , completeAfter | number | 1609522200 , 1609529400 | hard_window | [2]time.Time | [ "2021-01-01T12:30:00-00:00", "2021-01-01T14:30:00-00:00" ] |
dependencies | array string | [ "id-1", "id-2" ] | succeeds | []string | [ "id-1", "id-2" ] |
destination.location | array number | [ 1.23, 4.56 ] | position | map[string]int | { "lon": 1.23, "lat": 4.56 } |
quantity | number | 10 | quantity | int | 10 |
serviceTime | number | 5 | stop_duration | int | 300 |
quantity
can be extended to be a multi-quantity.- If the field
pickupTask
on the task is set totrue
, thequantity
will default to be negative, regardless of how it is set. - Onfleet
serviceTime
(minutes) is converted tostop_duration
(seconds), given that durations are handled in seconds inside of the Nextmv Cloud API.
Worker compatible attributes
Onfleet attribute | Onfleet type | Onfleet example | Nextmv attribute | Nextmv type (Go) | Nextmv example |
---|---|---|---|---|---|
activeTask | string | "id-1" | backlog | []string | [ "id-1" ] |
capacity | number | 100 | capacity | int | 100 |
location | array number | [ 2.294223, 48.858591 ] | start | map[string]float64 | { "lon": 2.294223, "lat": 48.858591 } |
tasks | array string | [ "id-1", "id-2" ] | backlog | []string | [ "id-1", "id-2" ] |
capacity
can be extended to be a multi-capacity.activeTask
andtasks
, if defined, are parsed to be part of thebacklog
. Additional tasks can be added to the backlog if the worker is extended with the backlog metadata entry.
Extending functionality
To use Nextmv Cloud API features not supported by the Onfleet API, you may extend tasks and workers using Onfleet metadata. Metadata for tasks and workers is defined as an array of metadata objects. The name
of each metadata object should follow this pattern:
Where version
dictates the metadata version used and attribute
is the name of the Nextmv attribute used to extend the task or worker. An example of a name is: "nextmv:0.1:unassigned_penalty"
, used to set an unassigned penalty for a task (stop). You may use all (or none) supported metadata extensions for both tasks and workers. In the following tables you will find a list of these attributes.
Additional steps are required to ensure expected behavior when using alternate stops with Onfleet.
Task extended attributes
Attribute | Onfleet type | Onfleet subtype | Nextmv type (Go) | Example object |
---|---|---|---|---|
position | "object" | NA | map[string]float64 | { "name": "nextmv:0.1:position", "type": "object", "value": { "lon": 1.23, "lat": 4.56 } } |
unassigned_penalty | "number" | NA | int | { "name": "nextmv:0.1:unassigned_penalty", "type": "number", "value": 10500 } |
quantity | "object" | NA | map[string]int | { "name": "nextmv:0.1:quantity", "type": "object", "value": { "volume": 400, "weight": 600 } } |
precedes | "array" | "string" | []string | { "name": "nextmv:0.1:precedes", "type": "array", "subtype": "string", "value": [ "id-1", "id-2" ] } |
max_wait | "number" | NA | int | { "name": "nextmv:0.1:max_wait", "type": "number", "value": 300 } |
target_time | "string" | NA | time.Time | { "name": "nextmv:0.1:target_time", "type": "string", "value": "2021-10-17T09:45:00-06:00" } |
earliness_penalty | "number" | NA | float64 | { "name": "nextmv:0.1:earliness_penalty", "type": "number", "value": 125.1 } |
lateness_penalty | "number" | NA | float64 | { "name": "nextmv:0.1:lateness_penalty", "type": "number", "value": 125.1 } |
compatibility_attributes | "array" | "string" | []string | { "name": "nextmv:0.1:compatibility_attributes", "type": "array", "subtype": "string", "value": [ "comp-1", "comp-2" ] } |
- The example shown for
quantity
is for multi-capacity. You can use a single capacity dimension, in which case the Onfleet type is"number"
and the Nextmv type isint
. - If
quantity
is defined in the Onfleet task and through metadata, a multi-quantity type will be used. This applies to both metadata cases: an object with multiple dimensions or a single numerical quantity. - The example shown for
precedes
is for multi-precedes. You can use a single ID forprecedes
, in which case the Onfleet type is"string"
and the Nextmv type isstring
.
Worker extended attributes
Attribute | Onfleet type | Onfleet subtype | Nextmv type (Go) | Example object |
---|---|---|---|---|
start | "object" | NA | map[string]float64 | { "name": "nextmv:0.1:start", "type": "object", "value": { "lon": 2.294223, "lat": 48.858591 } } |
end | "object" | NA | map[string]float64 | { "name": "nextmv:0.1:end", "type": "object", "value": { "lon": 2.294223, "lat": 48.858591 } } |
speed | "number" | NA | float64 | { "name": "nextmv:0.1:speed", "type": "number", "value": 10.3 } |
capacity | "object" | NA | map[string]int | { "name": "nextmv:0.1:capacity", "type": "object", "value": { "volume": 4000, "weight": 6000 } } |
shift_start | "string" | NA | time.Time | { "name": "nextmv:0.1:shift_start", "type": "string", "value": "2021-10-17T09:45:00-06:00" } |
shift_end | "string" | NA | time.Time | { "name": "nextmv:0.1:shift_end", "type": "string", "value": "2021-10-17T09:45:00-06:00" } |
compatibility_attributes | "array" | "string" | []string | { "name": "nextmv:0.1:compatibility_attributes", "type": "array", "subtype": "string", "value": [ "comp-1", "comp-2" ] } |
max_stops | "number" | NA | int | { "name": "nextmv:0.1:max_stops", "type": "number", "value": 10 } |
max_distance | "number" | NA | int | { "name": "nextmv:0.1:max_distance", "type": "number", "value": 1000 } |
max_duration | "number" | NA | int | { "name": "nextmv:0.1:max_duration", "type": "number", "value": 3600 } |
stop_duration_multiplier | "number" | NA | float64 | { "name": "nextmv:0.1:stop_duration_multiplier", "type": "number", "value": 1.5 } |
backlog | "array" | "string" | []string | { "name": "nextmv:0.1:backlog", "type": "array", "subtype": "string", "value": [ "id-1", "id-2" ] } |
alternate_stops | "array" | "string" | []string | { "name": "nextmv:0.1:alternate_stops", "type": "array", "subtype": "string", "value": [ "id-1", "id-2" ] } |
initialization_cost | "number" | NA | int | { "name": "nextmv:0.1:initialization_cost", "type": "number", "value": 1500 } |
- For offline workers, their
location
isnull
, so you can use thestart
attribute to define where the route should start. If the starting location is defined through metadata, it overrides the worker'slocation
attribute. - You can assign the same
start
andend
to represent routes with depots. - The example shown for
capacity
is for multi-capacity. You can use a single capacity dimension, in which case the Onfleet type is"number"
and the Nextmv type isint
. - If
capacity
is defined in the Onfleet worker and through metadata, a multi-capacity type will be used. This applies to both metadata cases: an object with multiple dimensions or a single numerical quantity. - To specify a worker's shift, please use the
shift_start
andshift_end
metadata attributes. We do not support native Onfleet worker schedules given that they may contain multiple shifts.
HERE integration
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 access, 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.
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 Console.
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 HERE 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
.
Streets integration
The Streets integration 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, 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.
Using the Streets integration
Follow the steps below to use the Streets integration.
- Contact support to request access to the Streets integration alpha.
- 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.
- Create a run profile for using the Streets 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. After, you can poll the status of your run and get the result. - Manage your configurations using the streets endpoints.
Note, the Streets integration can also be set up and edited through the Nextmv Console.
Set up the Streets 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:
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
.