Quickstart

Search…
Quickstart
Using the Nextmv Cloud API.
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, go to the API page and click "Click to reveal API Key" under the header "Your API Key". The key will automatically be copied to your clipboard. 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>
Bash
1
Authorization: Bearer <YOUR-API-KEY>
Copied!
post
https://api.cloud.nextmv.io
/v0/run
Create a new run.
get
https://api.cloud.nextmv.io
/v0/run/{run_id}/status
Get a run status.
get
https://api.cloud.nextmv.io
/v0/run/{run_id}/result
Get the result of the run.
For the full specification, please visit the Nextmv Cloud API OpenAPI specification.
Using the API
The Nextmv Cloud API should be used through polling.
polling-sample
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:
JSON
1
{ "runID": "<YOUR_RUN_ID>" }
Copied!
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 or started, 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 is succeeded. Instead of retries, you can also use a timeout, as outlined in our code samples.
If the status is failed or timed_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 [email protected].
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.
sample-input.json
2KB
Code
Input
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:
JSON
1
{
2
    "vehicles": [
3
        {
4
            "id": "vehicle-1",
5
            "capacity": 100,
6
            "speed": 20
7
        },
8
        {
9
            "id": "vehicle-2",
10
            "capacity": 50
11
        }
12
    ]
13
}
Copied!
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:
JSON
1
{
2
    "stops": [
3
        {
4
            "id": "location-1",
5
            "position": { "lon": -96.71038, "lat": 33.20580 },
6
            "quantity": -27
7
        },
8
        {
9
            "id": "location-2",
10
            "position": { "lon": -96.65613, "lat": 33.22591 },
11
            "quantity": -30
12
        }
13
    ]
14
}
Copied!
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:
JSON
1
{
2
    "run_profile": { 
3
      "id": "<MY-RUN-PROFILE-ID>"
4
    }
5
}
Copied!
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 } }
0 (no limit)
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 } }
0 (no limit)
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 (no limit)
The number of child nodes to generate on each pass.
Here is an example of custom options:
JSON
1
{
2
  "options": {
3
    "solver": {
4
      "limits": {
5
        "duration": "5s",
6
        "solutions": 1,
7
        "nodes": 10
8
      },
9
      "diagram":{
10
        "expansion": {
11
          "limit": 1
12
        }
13
      }
14
    }
15
  }
16
}
Copied!
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.
JSON
1
{
2
    "defaults": {
3
        "vehicles": {
4
            "start": { "lon": -96.65922, "lat": 33.12274 },
5
            "end": { "lon": -96.65922, "lat": 33.12274 },
6
            "shift_start": "2021-10-17T09:00:00-06:00",
7
            "speed": 10  
8
        },
9
        "stops": {
10
            "stop_duration": 120
11
        }
12
    }
13
}
Copied!
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:
JSON
1
{
2
    "stop_groups": [
3
      [
4
        "stop1", 
5
        "stop2"
6
      ],
7
      [
8
        "stop3", 
9
        "stop4", 
10
        "stop5"
11
      ]
12
  ]
13
}
Copied!
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:
JSON
1
{
2
    "alternate_stops": [
3
        {
4
          "id": "as-1",
5
          "position": { "lon": -96.71038, "lat": 33.20580 },
6
        },
7
        {
8
          "id": "as-2",
9
          "position": { "lon": -96.65613, "lat": 33.22591 },
10
        }
11
    ]
12
}
Copied!
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:
JSON
1
{
2
    "duration_groups": [
3
        {
4
            "group": ["location-4", "location-3", "location-2", "location-1"],
5
            "duration": 300
6
        },
7
        {
8
            "group": ["location-5", "location-6", "location-7"],
9
            "duration": 600
10
        }
11
    ]
12
}
Copied!
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.
sample-output.json
8KB
Code
Output
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
Name / identifier
id
string
"id": "vehicle-1"
Value
value
int
"value": 5745
Total travel distance
travel_distance
float [meters]
"travel_distance": 51450.103837858944
Total travel time
travel_time
float [seconds]
"travel_time": 5745.074947478
Initialization cost
vehicle_initialization_costs
int
"vehicle_initialization_costs": 0
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 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.
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 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.
JSON
1
{
2
  "vehicles": [
3
    {
4
      "id": "vehicle-1",
5
      "value": 5346,
6
      "travel_distance": 48659.494999999995,
7
      "travel_time": 5346.0749,
8
      "vehicle_initialization_costs": 0,
9
      "route": [
10
        {
11
          "id": "vehicle-1-start",
12
          "lon": -96.659222,
13
          "lat": 33.122746,
14
          "distance": 0,
15
          "eta": "2021-10-17T09:00:00-06:00",
16
          "ets": "2021-10-17T09:00:00-06:00"
17
        },
18
        {
19
          "id": "location-1",
20
          "lon": -96.75038245222623,
21
          "lat": 33.20580830033956,
22
          "distance": 12542.225,
23
          "eta": "2021-10-17T09:20:54-06:00",
24
          "ets": "2021-10-17T09:20:54-06:00"
25
        }
26
      ]
27
    }
28
  ]
29
}
Copied!
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.
JSON
1
{
2
  "unassigned": [
3
    {
4
      "id": "location-3",
5
      "lon": -96.61059803136642,
6
      "lat": 33.23528740544529
7
    }
8
  ]
9
}
Copied!
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.
JSON
1
{
2
  "value_summary": {
3
    "value": 211264,
4
    "total_travel_distance": 101843.988,
5
    "total_travel_time": 11265.113,
6
    "total_earliness_penalty": 0,
7
    "total_lateness_penalty": 0,
8
    "total_unassigned_penalty": 200000,
9
    "total_vehicle_initialization_costs": 0
10
  }
11
}
Copied!
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.
JSON
1
{
2
  "statistics": {
3
    "bounds": {
4
      "lower": -9223372036854776000,
5
      "upper": 211264
6
    },
7
    "search": {
8
      "generated": 10,
9
      "filtered": 0,
10
      "expanded": 10,
11
      "reduced": 0,
12
      "restricted": 10,
13
      "deferred": 10,
14
      "explored": 0,
15
      "solutions": 1
16
    },
17
    "time": {
18
      "elapsed": "1.152495ms",
19
      "elapsed_seconds": "0.001152495",
20
      "start": "2022-03-02T14:17:59.295985184Z"
21
    },
22
    "value": 211264
23
  }
24
}
Copied!
Cloud - Previous
API reference
Configuration
Last modified 2d ago
Export as PDF
Copy link
Contents
/v0/run/{run_id}/status
get
/v0/run/{run_id}/result
Using the API
Input schema
Output schema