API Quickstart

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.

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

Authorization: Bearer <YOUR-API-KEY>

Using the API

The Nextmv Cloud API should be used through polling.

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:

{ "runID": "<YOUR_RUN_ID>" }

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 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:

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.

Here is an example of vehicles:

{
    "vehicles": [
        {
            "id": "vehicle-1",
            "capacity": 100,
            "speed": 20
        },
        {
            "id": "vehicle-2",
            "capacity": 50
        }
    ]
}

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.

Here is an example of stops:

{
    "stops": [
        {
            "id": "location-1",
            "position": { "lon": -96.71038, "lat": 33.20580 },
            "quantity": -27
        },
        {
            "id": "location-2",
            "position": { "lon": -96.65613, "lat": 33.22591 },
            "quantity": -30
        }
    ]
}

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.

Here is an example of a run_profile:

{
    "run_profile": { 
      "id": "<MY-RUN-PROFILE-ID>"
    }
}

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.

Here is an example of custom options:

{
  "options": {
    "solver": {
      "limits": {
        "duration": "5s",
        "solutions": 1,
        "nodes": 10
      },
      "diagram":{
        "expansion": {
          "limit": 1
        }
      }
    }
  }
}

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.

{
    "defaults": {
        "vehicles": {
            "start": { "lon": -96.65922, "lat": 33.12274 },
            "end": { "lon": -96.65922, "lat": 33.12274 },
            "shift_start": "2021-10-17T09:00:00-06:00",
            "speed": 10  
        },
        "stops": {
            "stop_duration": 120
        }
    }
}

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:

{
    "stop_groups": [
      [
        "stop1", 
        "stop2"
      ],
      [
        "stop3", 
        "stop4", 
        "stop5"
      ]
  ]
}

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:

{
    "alternate_stops": [
        {
          "id": "as-1",
          "position": { "lon": -96.71038, "lat": 33.20580 },
        },
        {
          "id": "as-2",
          "position": { "lon": -96.65613, "lat": 33.22591 },
        }
    ]
}

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.

Here is an example of using duration_groups:

{
    "duration_groups": [
        {
            "group": ["location-4", "location-3", "location-2", "location-1"],
            "duration": 300
        },
        {
            "group": ["location-5", "location-6", "location-7"],
            "duration": 600
        }
    ]
}

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.

Here, we focus on the state object containing a solution. The state contains the following components:

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.

The components for a vehicle's route are described in the following table.

Here is an example of the solution for a vehicle.

{
  "vehicles": [
    {
      "id": "vehicle-1",
      "polyline": "??gotiEjpomQ??fotiEkpomQ",
      "travel_distance": 48659.494999999995,
      "travel_time": 5346.0749,
      "value": 5346,
      "vehicle_initialization_costs": 0,
      "route": [
        {
          "id": "vehicle-1-start",
          "lon": -96.659222,
          "lat": 33.122746,
          "distance": 0,
          "eta": "2021-10-17T09:00:00-06:00",
          "etd": "2021-10-17T09:00:00-06:00",
          "ets": "2021-10-17T09:00:00-06:00",
          "polyline": "styrFv~xiM??"
        },
        {
          "id": "location-1",
          "lon": -96.75038245222623,
          "lat": 33.20580830033956,
          "distance": 12542.225,
          "eta": "2021-10-17T09:20:54-06:00",
          "etd": "2021-10-17T09:20:54-06:00",
          "ets": "2021-10-17T09:20:54-06:00"
        }
      ]
    }
  ]
}

Unassigned output

The unassigned key holds an array of unassigned stops (objects). Each unassigned stop has the following fields:

Here is an example of how unassigned stops look like in the output.

{
  "unassigned": [
    {
      "id": "location-3",
      "lon": -96.61059803136642,
      "lat": 33.23528740544529
    }
  ]
}

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.

Here is an example of how the value_summary looks like in the output.

{
  "value_summary": {
    "value": 211264,
    "total_travel_distance": 101843.988,
    "total_travel_time": 11265.113,
    "total_earliness_penalty": 0,
    "total_lateness_penalty": 0,
    "total_unassigned_penalty": 200000,
    "total_vehicle_initialization_costs": 0
  }
}

Statistics

This section details the schema in the statistics object for each solution returned by the solver.

The bounds key follows the schema described below.

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.

Lastly, the time object shows the time it took for the solver to find the solution shown.

Below is an example of output statistics for a solver result.

{
  "statistics": {
    "bounds": {
      "lower": -9223372036854776000,
      "upper": 211264
    },
    "search": {
      "generated": 10,
      "filtered": 0,
      "expanded": 10,
      "reduced": 0,
      "restricted": 10,
      "deferred": 10,
      "explored": 0,
      "solutions": 1
    },
    "time": {
      "elapsed": "1.152495ms",
      "elapsed_seconds": "0.001152495",
      "start": "2022-03-02T14:17:59.295985184Z"
    },
    "value": 211264
  }
}