Nextmv Cloud API provides you with endpoints to run a model, check the status of your run, and get the results of a run. Follow the steps below to use Nextmv Cloud API.
Note, you can use Nextmv Cloud either via the API or console user interface, however some defaults or options may differ. Any differences are noted in the input schema.
Get your API key
After you have logged in to the Nextmv Cloud Console, navingate to your account page to find and copy your key. Keep it safe, as it alone provides unfettered access to the cloud API.
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 run.
Request a new run to the Nextmv Cloud API. You can use a `run_profile` to specify configurations and integrations that do not vary run to run. Use the `profiles` endpoints to create and manage run profiles.
Get a run status.
Poll the status of the run requested with the `/v0/run` endpoint, using the `run_id` obtained. If the status is `succeeded`, it means that the solution can be queried using the `/v0/run/{run_id}/result` endpoint.
Get the result of the run.
Get the result of the run requested with the `/v0/run` endpoint, using the `run_id` obtained. The solution can be found under the `state` key.
Using the API
The Nextmv Cloud API should be used through polling.
Visit our code snippets section for code snippets that showcase how to use the API in selected programming languages.
Send a request to the /v0/run
endpoint with a JSON
body that follows the input schema. The API server should return a runID
similar to the following:
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. Wait for approximately the duration
set in the run options
. Depending on the problem, the solver may finish sooner than the alloted time.
Poll the /v0/run/{run_id}/status
endpoint with the runID
obtained from the previous request.
- If the status of the run is
succeeded
, you may request the result using the last endpoint. - If the status is
requested
orstarted
, it means that the solver is still running and you should wait to request the result. We recommend you set a maximum number of retries for the polling. Sleep for a short time, then poll the endpoint until there are no retries left or the status issucceeded
. Instead of retries, you can also use a timeout, as outlined in our code samples. - If the status is
failed
ortimed_out
, it means that you will not be able to request the result.
Request the result from the /v0/run/{run_id}/result
endpoint using the runID
obtained from the first request. The response is a JSON
payload that follows the output schema. Modify the input of your run request to see how your result changes. If you have any questions or need help, please contact us at support@nextmv.io.
Input schema
The input schema is a JSON payload defining the vehicles, stops, and options for a given routing problem. Nextmv's tools are designed to operate directly on business data (in JSON
) to produce decisions that are actionable by software systems. This makes decisions more interpretable and easier to test. It also makes integration with data warehouses and business intelligence platforms significantly easier. An input contains the following components:
Property | Required | Field name | Type | Description |
---|---|---|---|---|
Vehicles | Yes | vehicles | array of object | Vehicles to route. |
Stops | Yes | stops | array of object | Stops that will be routed and assigned to the vehicles. |
Run profile | No | run_profile | object | Profile for configurations that do not vary run to run. |
Options | No | options | object | Options to configure the solver. |
Defaults | No | defaults | object | Default properties for vehicles and stops. |
Stop groups | No | stop_groups | array of array of string | Group of stops that must be part of the same route. |
Alternate stops | No | alternate_stops | array of object | Alternate locations that a vehicle can visit. |
Duration groups | No | duration_groups | array of object | Group of stops that add an overall service time. |
A sample input for a fleet of 2 vehicles and 10 stops is provided as a .json
file. Sign up for Nextmv Cloud Console for additional sample input files.
Vehicles
vehicles
define all vehicles in a fleet. Available vehicle property fields and type requirements are detailed in the table below. Besides being a mandatory field, the id
must be unique. Except for id
, required fields can be set as defaults instead of being set for each vehicle.
Note, the field alternate_stops
references stops by ID in the alternate_stops
object, not the stops
object.
Property | Required | Field name | Type | Example |
---|---|---|---|---|
Name / identifier | Yes | id | string | "id": "vehicle-1" |
Average speed | Yes | speed | float [meters/second] | "speed": 25 |
Shift start | Yes | shift_start | timestamp | "shift_start": "2021-10-17T09:00:00-06:00" |
Shift end | No | shift_end | timestamp | "shift_end": "2021-10-17T11:00:00-06:00" |
Starting position | No | start | object | "start": { "lon":-96.659222, "lat": 33.122746 } |
Ending position | No | end | object | "end": { "lon": -96.659222, "lat": 33.122746 } |
Carrying capacity | No | capacity | object or int | "capacity": { "weight": 500 } or "capacity": 500 |
Compatibility attributes | No | compatibility_attributes | array of string | "compatibility_attributes": ["refrigerated"] |
Max stops | No | max_stops | int | "max_stops": 1 |
Max distance | No | max_distance | int [meters] | "max_distance": 50000 |
Max duration | No | max_duration | int [seconds] | "max_duration": 3600 |
Stop duration multiplier | No | stop_duration_multiplier | float | "stop_duration_multiplier": 1.2 |
Backlog | No | backlog | array of string | "backlog": ["location-1"] |
Alternate stops | No | alternate_stops | array of string | "alternate_stops": ["as-1"] |
Initialization cost | No | initialization_cost | int | "initialization_cost": 34000 |
Here is an example of vehicles
:
Stops
stops
define all stops (or requests) that are candidates for assignment. Just like id
for vehicles, id
for stops must be unique. Available stop property fields and type requirements are detailed in the table below.
Property | Required | Field name | Type | Example |
---|---|---|---|---|
Name / identifier | Yes | id | string | "id": "order-1-pickup" |
Stop location | Yes | position | object | "position": { "lon": -96.827094, "lat": 33.004745 } |
Stop duration | No | stop_duration | int [seconds] | "stop_duration": 120 |
Quantity picked up (-) or dropped off (+) | No | quantity | object or int | "quantity": { "weight": -50 } or "quantity": -50 |
Target time | No | target_time | timestamp | "target_time": "2021-10-17T09:45:00-06:00" |
Hard window | No | hard_window | array of timestamp | "hard_window": [ "2021-10-17T09:00:00-06:00", "2021-10-17T10:00:00-06:00" ] |
Max wait time | No | max_wait | int [seconds] | "max_wait": 900 |
Penalty for being early | No | earliness_penalty | float | "earliness_penalty": 2 |
Penalty for being late | No | lateness_penalty | float | "lateness_penalty": 5 |
Penalty for not visiting | No | unassigned_penalty | int | "unassigned_penalty": 200000 |
Precedence - visit before | No | precedes | array of string or string | "precedes": ["order-1-drop", "order-2-drop"] or "precedes": "order-1-drop" |
Precedence - visit after | No | succeeds | array of string or string | "succeeds": ["order-1-drop", "order-2-drop"] or "succeeds": "order-1-drop" |
Compatibility attributes | No | compatibility_attributes | array of array of string | "compatibility_attributes": ["refrigerated"] |
Here is an example of stops
:
Run profile
run_profile
is a single JSON
object with an id
attribute specifying a previously configured run profile. Settings for the profile are merged with the input for the run. Additional integration-specific fields may be added to the run profile. Please note that third-party integrations are configured as part of a run profile. See available integrations for more information.
Property | Required | Field name | Type | Example |
---|---|---|---|---|
Name / identifier | Yes | id | string | "id": "<MY-RUN-PROFILE-ID>" |
Here is an example of a run_profile
:
Options
Solver options
can also be added to the input file. Note, in the Nextmv Cloud console, options added to an input file will override options configured using the graphical user interface (e.g., a duration specified in an input file will override a duration set using the runtime slider). Available option fields and type requirements are detailed in the table below.
Property | Required | Field name | Type | Example | Default (limits) | Description |
---|---|---|---|---|---|---|
Time limit | No | duration | string | "solver": { "limits": { "duration": "5s" } } | API: 3s (600s limit); Console: 3s (30s limit) | The length of time a solver must run. |
Solution limit | No | solutions | int | "solver": { "limits": { "solutions": 1 } } | model.MaxInt | The number of feasible solutions that must be found before stopping or reaching a time limit if specified. |
Node limit | No | nodes | int | "solver": { "limits": { "nodes": 10 } } | model.MaxInt | The number of nodes that must be generated before stopping or reaching a time limit if specified. |
Diagram expansion limit | No | expansion | int | "solver": { "diagram": { "expansion": { "limit": 1 } } | 1 | The number of child nodes to generate on each pass. |
Here is an example of custom options
:
Defaults
defaults
apply default properties to all vehicles, stops and alternate stops. Properties added to specific vehicles or stops override the default settings (see vehicles and stops). Here is an example of using defaults
.
Stop groups
stop_groups
define a list of stops to be grouped together. Each group must consist of at least 2 stops, given by their IDs. Here is an example of using stop_groups
:
Alternate stops
alternate_stops
defines a list of stops. An alternate stop can be referenced by a vehicle by using the alternate_stops
property. In addition to the stops already assigned to the vehicle, one alternate stop will be assigned from all referenced alternate stops. An alternate stop has the same fields as a normal stop. Here is an example of using alternate_stops
:
Duration groups
duration_groups
define groups of stops that would take on an additional duration cost if any stop in the group is approached from a location outside of it. Any individual stop durations will be applied as usual. Two fields are required for each duration group: group
and duration
. A location must not be repeated within a group and must not be part of several groups. The table below defines the schema for a duration group.
Property | Required | Field name | Type | Example |
---|---|---|---|---|
Stop group | Yes | group | array of string | "group": ["location-1"] |
Duration | Yes | duration | int [seconds] | "duration": 120 |
Here is an example of using duration_groups
:
Output schema
The output schema defines the solution to the routing problem, in addition to the options that were used and summary statistics, all in JSON
format. The output schema contains the following components.
Property | Field name | Type | Description |
---|---|---|---|
Hop version | hop | string | The version of the Nextmv solver (Hop ) used. |
Options | options | object | The options defined in the input file and used by the solver. |
Solution | state | object | The solution to the problem. |
Statistics | statistics | object | Summary statistics of the search for the best solution. |
Here, we focus on the state
object containing a solution. The state
contains the following components:
Property | Field name | Type | Description |
---|---|---|---|
Vehicles' solution | vehicles | array of object | Vehicles with assigned routes. |
Unassigned stops | unassigned | array of object | Stops not assigned to any vehicle (if any). |
Value summary | value_summary | object | Breakdown of a vehicle's solution. |
A sample output is provided as a .json
file.
Vehicles output
The vehicles
key contains the route per vehicle and different fields with statistics for that vehicle. The components of a vehicle's solution are described in the following table.
Property | Field name | Type | Example | Description |
---|---|---|---|---|
Name / identifier | id | string | "id": "vehicle-1" | ID of the vehicle. |
Value | value | int | "value": 5745 | Costs associated with this vehicle. |
Total travel distance | travel_distance | float [meters] | "travel_distance": 51450.103837858944 | Total distance traveled by this vehicle. |
Total travel time | travel_time | float [seconds] | "travel_time": 5745.074947478 | Total travel time for this vehicle. |
Initialization cost | vehicle_initialization_costs | int | "vehicle_initialization_costs": 0 | The one-time costs that are applied for using this vehicle. |
Polyline | polyline | string | "polyline": "??gotiEjpomQ??fotiEkpomQ" | A polyline from start to end encoded in Google's polyline format. |
Route | route | array of object | "route": {"id":"location-1", "lon": -96.7503, "lat": 33.2058 "distance": 12542.225,"eta": "2022-02-22T09:20:54:06-00","ets": "2022-02-22T09:20:54:06-00"}, {...}, ...] | The vehicle's route with stops and additional stop information. |
The components for a vehicle's route
are described in the following table.
Property | Field name | Type | Example | Description |
---|---|---|---|---|
Name / identifier | id | string | "id": "location-1" | ID of the stop. |
Longitude | lon | float | "lon": -96.659222 | Longitude of the stop. |
Latitude | lat | float | "lat": 33.122746 | Latitude of the stop. |
Accumulated distance | distance | float [meters] | "distance": 0 | Total route distance up to this stop. |
Polyline | polyline | string | "polyline": "styrFv~xiM??" | A polyline from this stop to the next stop, encoded in Google's polyline format. |
Estimated time of arrival | eta | timestamp | "eta": "2021-10-17T09:00:00-06:00" | Estimated time at which the vehicle will arrive at this stop. |
Estimated time of departure | etd | timestamp | "etd": "2021-10-17T09:00:00-06:00" | Estimated time at which the vehicle will depart from this stop. |
Estimated time of service | ets | timestamp | "ets": "2021-10-17T09:00:00-06:00" | When using time windows there are potential wait times when arriving before the window opens. This is the estimated time at which service at the stop starts. |
Here is an example of the solution for a vehicle.
Unassigned output
The unassigned
key holds an array of unassigned stops (objects). Each unassigned stop has the following fields:
Property | Field name | Type | Example |
---|---|---|---|
Name / identifier | id | string | "id": "location-1" |
Longitude | lon | float | "lon": -96.659222 |
Latitude | lat | float | "lat": 33.122746 |
Here is an example of how unassigned
stops look like in the output.
Summary output
The value_summary
key holds summary statistics of the overall solution, like the total distance traveled and the value of the solution. The components of the value summary are described below.
Property | Field name | Type | Example |
---|---|---|---|
Value | value | int | "value": 211264 |
Total travel distance | total_travel_distance | float [meters] | "total_travel_distance": 101843.988 |
Total travel time | total_travel_time | float [seconds] | "total_travel_time": 11265.113 |
Total earliness penalty | total_earliness_penalty | float [seconds] | "total_earliness_penalty": 0 |
Total lateness penalty | total_lateness_penalty | float [seconds] | "total_lateness_penalty": 0 |
Total unassigned penalty | total_unassigned_penalty | int [seconds] | "total_unassigned_penalty": 200000 |
Total vehicle initialization costs | total_vehicle_initialization_costs | int [seconds] | "total_vehicle_initialization_costs": 0 |
Here is an example of how the value_summary
looks like in the output.
Statistics
This section details the schema in the statistics
object for each solution returned by the solver.
Property | Field name | Type | Description |
---|---|---|---|
Solution bounds | bounds | object | Bounds for the value of the solution. |
Solution state exploration | search | object | Summary of the solver's search mechanism. |
Solution time statistics | time | object | Time it took for the solver to find the solution. |
Solution value | value | int | Total value of the solution. |
The bounds
key follows the schema described below.
Property | Field name | Type | Description |
---|---|---|---|
Lower bound | lower | int | Lower bound of the solution. |
Upper bound | upper | int | Upper bound of the solution. |
In cases where the Nextmv solver is maximizing or minimizing an objective, the upper
and lower
bounds are continuously updated after generating a new state.
- If the bounds are the same in value, Nextmv solver has mathematically proven optimality of its best solution.
- When bounds are not the same value, Nextmv solver terminated early while searching the state space proving optimality. In that case, Nextmv solver will return the best solution found to date.
The search
object shows the solver's search mechanism, which is a state exploration. It projects states forward from the root state to determine what decisions you should make. Every transition in that search produces a new state which is then explored. Each of these categories contain both feasible and infeasible states. See the solver overview for more information.
Property | Field name | Type | Description |
---|---|---|---|
Generated states | generated | int | All of the states the solver created. |
Filtered states | filtered | int | All states that have been removed from the search because they have been bounded out. The solver has determined that it cannot, from a certain set of solutions, produce a solution that will be better than the best solution found so far. |
Expanded states | expanded | int | All states that are not 'Filtered' |
Reduced states | reduced | int | States that have been removed from the search because a 'Reducer' determined that no states directly dominate them. |
Deferred states | restricted | int | States saved for later exploration. This is how the solver manages an explosion of the state space. It will explore the most fruitful options first, then defer the others. |
Restricted states | deferred | int | States that have not been deferred and will be investigated immediately. |
Explored states | explored | int | All states that have been fully explored. Explored states cannot produce more child states. |
Total solutions | solutions | int | Number of solutions that the solver has found thus far. |
Lastly, the time
object shows the time it took for the solver to find the solution shown.
Property | Field name | Type | Description |
---|---|---|---|
Elapsed time | elapsed | string | Human-readable elapsed time to find the solution. |
Elapsed seconds | elapsed_seconds | float | Total seconds to find the solution. |
Run start time | start | timestamp | Timestamp indicating when the search began. |
Below is an example of output statistics for a solver result.