Input Schema

Last updatedJuly 21, 2021

Input files define the vehicles, stops, and options for a given routing problem. This page details the properties available in the input schema for Nextmv Cloud.

Note, you can use Nextmv Cloud either via the API or console user interface, however some defaults or options (such as application runtime) may differ when using Nextmv Cloud via the console vs the API. Any differences are noted in the tables below.

Input files are written in JSON (see below for a sample input file). 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.

Input file components

An input file contains defaults (optional), vehicles, stops, and other configuration for the solver (optional).

Defaults

defaults apply default properties to all vehicles and stops. Properties added to specific vehicles or stops override the default settings (see vehicle and stop property configurations below).

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

Vehicles

vehicles define all vehicles in a fleet (see the table below for a list of vehicle field names and types).

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

The "id" field is required for vehicles and must be unique. Available vehicle property fields and value input requirements are detailed in the table below.

Configuration	Field name	Value input	Example
name / identifier	`id`	string	`"id": "vehicle-1"`
starting position	`start`	longitude, latitude	`"start": { "lon":-96.659222, "lat": 33.122746 }`
ending position	`end`	longitude, latitude	`"end": { "lon": -96.659222, "lat": 33.122746 }`
carrying capacity	`capacity`	integer	`"capacity": 50`
average speed	`speed`	integer in meters per second	`"speed": 25`
shift start	`shift_start`	timestamp	`"shift_start": "2021-10-17T09:00:00-06:00"`
shift end	`shift_end`	timestamp	`"shift_end": "2021-10-17T11:00:00-06:00"`
compatibility attributes	`compatibility_attributes`	array of strings	`"compatibility_attributes" : ["refrigerated"]`

Stops

stops define all stops (or requests) that are candidates for assignment (see the table below for a list of stop field names and types).

{
    "stops":[
        {
            "id": "location-1",
            "position": {
                "lon": -96.71038245222624,
                "lat": 33.20580830033956
            },
            "quantity": -27
        },
        {
            "id": "location-2",
            "position": {
                "lon": -96.65613745932127,
                "lat": 33.2259142720506
            },
            "quantity": -30
        },
        ...
    ]
}

Two fields are required for stops: "id" and "position". Just like IDs for vehicles, IDs for stops must be unique. Available stop property fields and value input requirements are detailed in the table below.

Configuration	Field name	Value input	Example
name / identifier	`id`	string	`"id": "order-1-pickup"`
stop location	`position`	longitude, latitude	`"position": { "lon": -96.827094, "lat": 33.004745 }`
stop duration	`stop_duration`	time in seconds	`"stop_duration": 120`
quantity picked up or dropped off	`quantity`	integer (positive for drop offs because capacity is added or negative for pickups because capacity is removed)	`"quantity": 10`
target time for visiting a stop	`target_time`	timestamp	`"target_time": "2021-10-17T09:45:00-06:00"`
hard window for visiting a stop	`hard_window`	timestamp	`"hard_window": [ "2021-10-17T09:00:00-06:00", "2021-10-17T10:00:00-06:00" ]`
penalty for arriving at a stop early	`earliness_penalty`	scalar multiplied by seconds early	`"earliness_penalty": 2`
penalty for arriving at a stop late	`lateness_penalty`	scalar multiplied by seconds late	`"lateness_penalty": 5`
penalty for not visiting a stop	`unassigned_penalty`	time in seconds	`"unassigned_penalty": 200000`
delivery precedence	`precedes`	string	`"precedes": "order-1-dropoff"`
multi-pickup delivery precedence	`precedes`	string	`"precedes": "order-1-pickup-3"`
compatibility attributes	`compatibility_attributes`	array of strings	`"compatibility_attributes" : ["refrigerated"]`

Options

Solver options can also be added to the input file. Note, in Nextmv Cloud console, options added to an input file in Nextmv Cloud console 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).

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

Available option fields and value input requirements are detailed in the table below.

Configuration (Description)	Field name	Value input	Example	Default (limits)
Time limit (the length of time a solver must run)	`duration`	string	`"solver": { "limits": { "duration": "5s" } }`	API: 0 (600s limit); Console: 3s (30s limit)
Solution limit (the number of feasible solutions that must be found before stopping or reaching a time limit if specified)	`solutions`	integer	`"solver": { "limits": { "solutions": 1 } }`	0 (no limit)
Node limit (the number of nodes that must be generated before stopping or reaching a time limit if specified)	`nodes`	integer	`"solver": { "limits": { "nodes": 10 } }`	0 (no limit)
Diagram expansion limit (the number of child nodes to generate on each pass)	`expansion`	integer	`"solver": { "diagram": { "expansion": 1 } }`	0 (no limit)

Sample input file

A sample input file for a fleet of 2 vehicles and 10 stops is provided below. Sign up for Nextmv Cloud Console for additional sample input files.

{
  "defaults": {
    "vehicles": {
      "start": {
        "lon": -96.659222,
        "lat": 33.122746
      },
      "end": {
        "lon": -96.659222,
        "lat": 33.122746
      },
      "shift_start": "2021-10-17T09:00:00-06:00",
      "speed": 10
    },
    "stops": {
      "stop_duration": 120
    }
  },
  "vehicles": [
    {
      "id": "vehicle-1",
      "capacity": 305
    },
    {
      "id": "vehicle-2",
      "capacity": 205
    }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": {
        "lon": -96.71038245222624,
        "lat": 33.20580830033956
      },
      "quantity": -27
    },
    {
      "id": "location-2",
      "position": {
        "lon": -96.65613745932127,
        "lat": 33.2259142720506
      },
      "quantity": -30
    },
    {
      "id": "location-3",
      "position": {
        "lon": -96.63759803136642,
        "lat": 33.21528740544529
      },
      "quantity": -36
    },
    {
      "id": "location-4",
      "position": {
        "lon": -96.61356543957307,
        "lat": 33.20379744909628
      },
      "quantity": -19
    },
    {
      "id": "location-5",
      "position": {
        "lon": -96.64137458150537,
        "lat": 33.178801586789376
      },
      "quantity": -31
    },
    {
      "id": "location-6",
      "position": {
        "lon": -96.83157538607735,
        "lat": 33.02896457334468
      },
      "quantity": -15
    },
    {
      "id": "location-7",
      "position": {
        "lon": -96.82951544963792,
        "lat": 33.05170100884261
      },
      "quantity": -31
    },
    {
      "id": "location-8",
      "position": {
        "lon": -96.86007117348946,
        "lat": 33.08133590083287
      },
      "quantity": -52
    },
    {
      "id": "location-9",
      "position": {
        "lon": -96.87346076034575,
        "lat": 33.092841906114394
      },
      "quantity": -48
    },
    {
      "id": "location-10",
      "position": {
        "lon": -96.79586982112724,
        "lat": 33.10492159118987
      },
      "quantity": -40
    }
  ],
  "options": {
    "solver": {
      "limits": {
        "duration": "5s",
        "solutions": 1,
        "nodes": 10
      },
      "diagram":{
        "expansion": 1,
      }
    }
  }
}

Was this helpful?