Input/output schema

Input

The format for timestamps should be RFC3339, e.g.: "2023-01-01T00:00:00Z".

The input schema is a JSON payload defining the vehicles, stops, and features 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:

Field name	Required	Data type	SI Unit	Description	Example
`vehicles`	Yes	`array` of `vehicle`	NA	Vehicles to route.	See `vehicle`
`stops`	Yes	`array` of `stop`	NA	Stops that will be routed and assigned to the vehicles.	See `stop`
`alternate_stops`	No	`array` of `alternate_stop`	NA	Alternate stops which can be serviced.	`{"alternate_stops": [{"id": "Inafuku","location": { "lon": 123, "lat": 456 }}]}`
`defaults`	No	`object`	NA	Default properties for vehicles and stops.	`{"defaults": {"stops": {"duration": 1.23}}}`
`stop_groups`	No	`array` of `array` of `string`	NA	Group of stops that must be part of the same route.	`{"stop_groups": [["foo", "bar"], ["baz", "roh"]]}`
`duration_matrix`	No	`array` of `array` of `float`	`seconds`	Matrix of durations between locations.	`{"duration_matrix": [[1.23, 4.56], [7.89, 0.12]]}`
`distance_matrix`	No	`array` of `array` of `float`	`meters`	Matrix of distances between locations.	`{"distance_matrix": [[1.23, 4.56], [7.89, 0.12]]}`
`duration_groups`	No	`array` of `duration_group`	NA	Duration added when approaching the group.	`{"duration_groups": [{"group":["foo", "bar"], "duration": 200}]`
`custom_data`	No	`any`	NA	Custom data to be used arbitrarily within the model.	`{"custom_data": {"foo": "bar"}}`
`options`	No	`object`	NA	Arbitrary options.	`{"options": {"foo": "bar"}}`

Here you can find a sample .json with the input schema:

JSON

{
  "defaults": {
    "vehicles": {
      "capacity": {
        "bunnies": 20,
        "rabbits": 10
      },
      "start_location": {
        "lat": 35.791729813680874,
        "lon": -78.7401685145487
      },
      "end_location": {
        "lat": 35.791729813680874,
        "lon": -78.7401685145487
      },
      "speed": 10
    },
    "stops": {
      "duration": 300,
      "quantity": {
        "bunnies": -1,
        "rabbits": -1
      },
      "unplanned_penalty": 200000,
      "target_arrival_time": "2023-01-01T10:00:00Z",
      "early_arrival_time_penalty": 1.5,
      "late_arrival_time_penalty": 1.5
    }
  },
  "stops": [
    {
      "id": "s1",
      "location": {
        "lon": -78.90919,
        "lat": 35.72389
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s2",
      "location": {
        "lon": -78.813862,
        "lat": 35.75712
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s3",
      "location": {
        "lon": -78.92996,
        "lat": 35.932795
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s4",
      "location": {
        "lon": -78.505745,
        "lat": 35.77772
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s5",
      "location": {
        "lon": -78.75084,
        "lat": 35.732995
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s6",
      "location": {
        "lon": -78.788025,
        "lat": 35.813025
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s7",
      "location": {
        "lon": -78.749391,
        "lat": 35.74261
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s8",
      "location": {
        "lon": -78.94658,
        "lat": 36.039135
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s9",
      "location": {
        "lon": -78.64972,
        "lat": 35.64796
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s10",
      "location": {
        "lon": -78.747955,
        "lat": 35.672955
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s11",
      "location": {
        "lon": -78.83403,
        "lat": 35.77013
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s12",
      "location": {
        "lon": -78.864465,
        "lat": 35.782855
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s13",
      "location": {
        "lon": -78.952142,
        "lat": 35.88029
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s14",
      "location": {
        "lon": -78.52748,
        "lat": 35.961465
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s15",
      "location": {
        "lon": -78.89832,
        "lat": 35.83202
      }
    },
    {
      "id": "s16",
      "location": {
        "lon": -78.63216,
        "lat": 35.83458
      }
    },
    {
      "id": "s17",
      "location": {
        "lon": -78.76063,
        "lat": 35.67337
      }
    },
    {
      "id": "s18",
      "location": {
        "lon": -78.911485,
        "lat": 36.009015
      }
    },
    {
      "id": "s19",
      "location": {
        "lon": -78.522705,
        "lat": 35.93663
      }
    },
    {
      "id": "s20",
      "location": {
        "lon": -78.995162,
        "lat": 35.97414
      }
    },
    {
      "id": "s21",
      "location": {
        "lon": -78.50509,
        "lat": 35.7606
      }
    },
    {
      "id": "s22",
      "location": {
        "lon": -78.828547,
        "lat": 35.962635
      },
      "precedes": ["s16", "s23"]
    },
    {
      "id": "s23",
      "location": {
        "lon": -78.60914,
        "lat": 35.84616
      },
      "start_time_window": [
        "2023-01-01T09:00:00-06:00",
        "2023-01-01T09:30:00-06:00"
      ]
    },
    {
      "id": "s24",
      "location": {
        "lon": -78.65521,
        "lat": 35.740605
      },
      "start_time_window": [
        "2023-01-01T09:00:00-06:00",
        "2023-01-01T09:30:00-06:00"
      ],
      "succeeds": "s25"
    },
    {
      "id": "s25",
      "location": {
        "lon": -78.92051,
        "lat": 35.887575
      },
      "start_time_window": [
        "2023-01-01T09:00:00-06:00",
        "2023-01-01T09:30:00-06:00"
      ],
      "precedes": "s26"
    },
    {
      "id": "s26",
      "location": {
        "lon": -78.84058,
        "lat": 35.823865
      },
      "start_time_window": [
        "2023-01-01T09:00:00-06:00",
        "2023-01-01T09:30:00-06:00"
      ]
    }
  ],
  "vehicles": [
    {
      "id": "vehicle-0",
      "start_time": "2023-01-01T06:00:00-06:00",
      "end_time": "2023-01-01T10:00:00-06:00",
      "activation_penalty": 4000,
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "vehicle-1",
      "start_time": "2023-01-01T10:00:00-06:00",
      "end_time": "2023-01-01T16:00:00-06:00",
      "max_duration": 21000,
      "compatibility_attributes": ["basic"]
    }
  ]
}

Alternate stop

An alternate stop has all the same fields as a stop excluding the following:

precedes
succeeds
compatibility_attributes

The id of the alternate stop is used as part of the alternate_stops field in the vehicle schema.

Defaults

The defaults schema defines the default values for all the vehicles and stops. Please go to each section to determine which fields are configurable as defaults.

Field name	Required	Data type	Description	Example
`vehicles`	No	`vehicle`	Default values for the vehicle.	`{"vehicle": {"capacity": 5}}`
`stops`	No	`stop`	Default values for the stop.	`{"stop": {"duration": 123}}`

Duration Group

A duration groups is used in the input schema.

Field name	Required	Data type	SI Unit	Description	Example
`group`	Yes	`array` of `string`	NA	Stop IDs contained in the group.	`{"group": ["foo", "bar"]}`
`duration`	Yes	`int`	`seconds`	Duration to add when visiting the group.	`{"duration": 4}`

Location

A location is used in the vehicle and stop schemas.

Field name	Required	Data type	Description	Example
`lon`	Yes	`float`	Longitude of the location.	`{"lon": 1.23}`
`lat`	Yes	`float`	Latitude of the location.	`{"lat": 4.56}`

Stop

The target_arrival_time is used in the early_arrival_time_penalty and late_arrival_time_penalty features.

Field name	Required	Data type	SI Unit	Description	Example	Configurable via `defaults`
`id`	Yes	`string`	NA	Unique identifier for the stop.	`{"id": "foo"}`	➖
`location`	Yes	`location`	NA	Location of the stop.	`{"location": {"lon": 1.23, "lat": 4.56}}`	➖
`precedes`	No	`array` of `string` or `string`	NA	Stops that must be visited after this one on the same route.	`{"precedes": ["foo", "bar"]}`	➖
`succeeds`	No	`array` of `string` or `string`	NA	Stops that must be visited before this one on the same route.	`{"succeeds": ["foo", "bar"]}`	➖
`quantity`	No	`object` (`string` to `int`) or `int`	NA	Quantity of the stop.	`{"quantity": -1}`	✅
`target_arrival_time`	No	`timestamp`	NA	Target arrival time at the stop.	`{"target_arrival_time": "2023-01-01T00:00:00Z"}`	✅
`start_time_window`	No	`array` of `timestamp` or `array` of `array` of `timestamp`	NA	Time window in which the stop can start service.	`{"start_time_window": [["2023-01-01T12:00:00Z", "2023-01-01T12:05:00Z"], ["2023-01-01T12:30:00Z", "2023-01-01T13:35:00Z"]]}`	✅
`max_wait`	No	`int`	`seconds`	Maximum waiting time at the stop.	`{"max_wait": 123}`	✅
`duration`	No	`int`	`seconds`	Duration of the service time at the stop.	`{"duration": 123}`	✅
`unplanned_penalty`	No	`int`	NA	Penalty for not planning the stop.	`{"unplanned_penalty": 123}`	✅
`early_arrival_time_penalty`	No	`float`	NA	Penalty for arriving at the stop before the target arrival time.	`{"early_arrival_time_penalty": 1.23}`	✅
`late_arrival_time_penalty`	No	`float`	NA	Penalty for arriving at the stop after the target arrival time.	`{"late_arrival_time_penalty": 1.23}`	✅
`compatibility_attributes`	No	`array` of `string`	NA	Attributes that the stop is compatible with.	`{"compatibility_attributes": ["foo", "bar"]}`	✅
`mixing_items`	No	`map` of `string` to `mix_item`	NA	Propoerties which can not be on a vehicle at the same time.	`{"mixing_items": {"hazchem": {"name": "F-A-W-E","quantity": 1}}`	➖
`custom_data`	No	`any`	NA	Custom data to be used arbitrarily within the model.	`{"custom_data": {"foo": "bar"}}`	➖

Here you can find additional definitions used in the stop schema:

mix_item
Field name Required Data type Description Example
name Yes string Name of the "ingredient" to avoid mixing. {"id": "vegan"}
quantity Yes int Quantity the stop adds / removes of the "ingredient" {"quantity": 1}

Field name	Required	Data type	Description	Example
`name`	Yes	`string`	Name of the "ingredient" to avoid mixing.	`{"id": "vegan"}`
`quantity`	Yes	`int`	Quantity the stop adds / removes of the "ingredient"	`{"quantity": 1}`

Vehicle

If the duration_matrix is not specified in the input, the speed must be present.

Field name	Required	Data type	SI Unit	Description	Example	Configurable via `defaults`
`id`	Yes	`string`	NA	Unique identifier for the vehicle.	`{"id": "foo"}`	➖
`capacity`	No	`object` (`string` to `int`) or `int`	NA	Capacity of the vehicle.	`{"capacity": {"bar": 2}}`	✅
`start_level`	No	`object` (`string` to `int`) or `int`	NA	Initial capacity of the vehicle.	`{"start_level": {"bar": 2}}`	✅
`start_location`	No	`location`	NA	Location where the vehicle starts.	`{"start_location": {"lon": 1.23, "lat": 4.56}}`	✅
`end_location`	No	`location`	NA	Location where the vehicle ends.	`{"end_location": {"lon": 1.23, "lat": 4.56}}`	✅
`min_stops`	No	`int`	NA	Minimum stops that a vehicle should visit.	`{"min_stops": 8}`	✅
`min_stops_penalty`	No	`float`	NA	Penalty for not complying with minimum stops.	`{"min_stops_penalty": 1000}`	✅
`speed`	No	`float`	`meters/second`	Speed of the vehicle.	`{"speed": 1.23}`	✅
`start_time`	No	`timestamp`	NA	Time when the vehicle starts its route.	`{"start_time": "2023-01-01T00:00:00Z"}`	✅
`end_time`	No	`timestamp`	NA	Latest time at which the vehicle ends its route.	`{"end_time": "2023-01-01T00:00:00Z"}`	✅
`compatibility_attributes`	No	`array` of `string`	NA	Attributes that the vehicle is compatible with.	`{"compatibility_attributes": ["foo", "bar"]}`	✅
`max_stops`	No	`int`	NA	Maximum number of stops that the vehicle can visit.	`{"max_stops": 2}`	✅
`max_distance`	No	`int`	`meters`	Maximum distance that the vehicle can travel.	`{"max_distance": 123}`	✅
`max_duration`	No	`int`	`seconds`	Maximum duration that the vehicle can travel.	`{"max_duration": 123}`	✅
`max_wait`	No	`int`	`seconds`	Maximum aggregated waiting time that the vehicle can wait across route stops.	`{"max_wait": 123}`	✅
`stop_duration_multiplier`	No	`float`	NA	Multiplier on a stop's duration.	`{"stop_duration_multiplier": 1.23}`	✅
`activation_penalty`	No	`int`	NA	Cost of using the vehicle.	`{"activation_penalty": 1.23}`	✅
`alternate_stops`	No	`array` of `string`	NA	Alternate stops IDs to service for the vehicle.	`{"alternate_stops": ["foo", "bar"]}`	✅
`initial_stops`	No	`array` of `initial_stop`	NA	Initial stops planned on the vehicle.	`{"initial_stops": [{"id": "bar"}]}`	➖
`custom_data`	No	`any`	NA	Custom data to be used arbitrarily within the model.	`{"custom_data": {"foo": "bar"}}`	➖

Here you can find additional definitions used in the vehicle schema:

initial_stop
Field name Required Data type Description Example
id Yes string Unique identifier for the stop. {"id": "foo"}
fixed No bool Whether the stop is fixed or not. {"fixed": true}

Field name	Required	Data type	Description	Example
`id`	Yes	`string`	Unique identifier for the stop.	`{"id": "foo"}`
`fixed`	No	`bool`	Whether the stop is fixed or not.	`{"fixed": true}`

Input schema Validation

The Nextmv SDK runner implements automatic schema validation for:

correctly named fields,
unknown fields,
invalid data types.

This validation applies to any input passed to the runner including custom input.

If you prefer to turn off schema validation, you can add the run.InputValidate argument.

    runner := run.CLI(solver.Solver, run.InputValidate[run.CLIRunnerConfig, schema.Input, solver.Options, schema.Output](nil))

Output

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.

Field name	Always present	Data type	SI Unit	Description	Example
`options`	Yes	`options`	NA	Options used to generate the solution.	`{"options": {"solve": {"iterations": 50}}}`
`solutions`	Yes	`array` of `solution`	NA	Solutions to the routing problem.	`{"solutions": []}`
`statistics`	Yes	`statistics`	NA	Summary statistics of the solution.	`{"statistics": {"total_cost": 123}}`
`version`	Yes	`object`	NA	Version of the Nextmv SDK used to generate the solution.	`{"version": {"sdk": "v1.2.3"}}`

Here you can find a sample .json with the output schema:

JSON

{
  "options": {
    "check": {
      "duration": 30000000000,
      "verbosity": "off"
    },
    "format": {
      "disable": {
        "progression": true
      }
    },
    "model": {
      "constraints": {
        "disable": {
          "attributes": false,
          "capacities": null,
          "capacity": false,
          "distance_limit": false,
          "groups": false,
          "maximum_duration": false,
          "maximum_stops": false,
          "maximum_wait_stop": false,
          "maximum_wait_vehicle": false,
          "mixing_items": false,
          "precedence": false,
          "start_time_windows": false,
          "vehicle_end_time": false,
          "vehicle_start_time": false
        },
        "enable": {
          "cluster": false
        }
      },
      "objectives": {
        "capacities": "",
        "cluster": 0,
        "early_arrival_penalty": 1,
        "late_arrival_penalty": 1,
        "min_stops": 1,
        "travel_duration": 0,
        "unplanned_penalty": 1,
        "vehicle_activation_penalty": 1,
        "vehicles_duration": 1
      },
      "properties": {
        "disable": {
          "duration_groups": false,
          "durations": false,
          "initial_solution": false,
          "stop_duration_multipliers": false
        }
      },
      "validate": {
        "disable": {
          "resources": false,
          "start_time": false
        },
        "enable": {
          "matrix": false,
          "matrix_asymmetry_tolerance": 20
        }
      }
    },
    "solve": {
      "duration": 10000000000,
      "iterations": 50,
      "parallel_runs": 1,
      "run_deterministically": true,
      "start_solutions": 1
    }
  },
  "solutions": [
    {
      "objective": {
        "name": "1 * vehicle_activation_penalty + 1 * vehicles_duration + 1 * unplanned_penalty + 1 * early_arrival_penalty + 1 * late_arrival_penalty",
        "objectives": [
          {
            "base": 4000,
            "factor": 1,
            "name": "vehicle_activation_penalty",
            "value": 4000
          },
          {
            "base": 34394.3133084774,
            "factor": 1,
            "name": "vehicles_duration",
            "value": 34394.3133084774
          },
          {
            "base": 1400000,
            "factor": 1,
            "name": "unplanned_penalty",
            "value": 1400000
          },
          {
            "factor": 1,
            "name": "early_arrival_penalty",
            "value": 0
          },
          {
            "base": 621271.1251366138,
            "factor": 1,
            "name": "late_arrival_penalty",
            "value": 621271.1251366138
          }
        ],
        "value": 2059665.4384450912
      },
      "unplanned": [
        {
          "id": "s16",
          "location": {
            "lat": 35.83458,
            "lon": -78.63216
          }
        },
        {
          "id": "s22",
          "location": {
            "lat": 35.962635,
            "lon": -78.828547
          }
        },
        {
          "id": "s23",
          "location": {
            "lat": 35.84616,
            "lon": -78.60914
          }
        },
        {
          "id": "s24",
          "location": {
            "lat": 35.740605,
            "lon": -78.65521
          }
        },
        {
          "id": "s25",
          "location": {
            "lat": 35.887575,
            "lon": -78.92051
          }
        },
        {
          "id": "s26",
          "location": {
            "lat": 35.823865,
            "lon": -78.84058
          }
        },
        {
          "id": "s4",
          "location": {
            "lat": 35.77772,
            "lon": -78.505745
          }
        }
      ],
      "vehicles": [
        {
          "id": "vehicle-0",
          "route": [
            {
              "arrival_time": "2023-01-01T06:00:00-06:00",
              "cumulative_travel_duration": 0,
              "end_time": "2023-01-01T06:00:00-06:00",
              "start_time": "2023-01-01T06:00:00-06:00",
              "stop": {
                "id": "vehicle-0-start",
                "location": {
                  "lat": 35.791729813680874,
                  "lon": -78.7401685145487
                }
              },
              "travel_duration": 0
            },
            {
              "arrival_time": "2023-01-01T06:09:12-06:00",
              "cumulative_travel_distance": 5524,
              "cumulative_travel_duration": 552,
              "duration": 300,
              "end_time": "2023-01-01T06:14:12-06:00",
              "late_arrival_duration": 7752,
              "start_time": "2023-01-01T06:09:12-06:00",
              "stop": {
                "id": "s7",
                "location": {
                  "lat": 35.74261,
                  "lon": -78.749391
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 5524,
              "travel_duration": 552
            },
            {
              "arrival_time": "2023-01-01T06:28:29-06:00",
              "cumulative_travel_distance": 14094,
              "cumulative_travel_duration": 1409,
              "duration": 300,
              "end_time": "2023-01-01T06:33:29-06:00",
              "late_arrival_duration": 8909,
              "start_time": "2023-01-01T06:28:29-06:00",
              "stop": {
                "id": "s6",
                "location": {
                  "lat": 35.813025,
                  "lon": -78.788025
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 8570,
              "travel_duration": 857
            },
            {
              "arrival_time": "2023-01-01T06:49:20-06:00",
              "cumulative_travel_distance": 23604,
              "cumulative_travel_duration": 2360,
              "duration": 300,
              "end_time": "2023-01-01T06:54:20-06:00",
              "late_arrival_duration": 10160,
              "start_time": "2023-01-01T06:49:20-06:00",
              "stop": {
                "id": "s5",
                "location": {
                  "lat": 35.732995,
                  "lon": -78.75084
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 9510,
              "travel_duration": 951
            },
            {
              "arrival_time": "2023-01-01T07:05:29-06:00",
              "cumulative_travel_distance": 30292,
              "cumulative_travel_duration": 3029,
              "duration": 300,
              "end_time": "2023-01-01T07:10:29-06:00",
              "late_arrival_duration": 11129,
              "start_time": "2023-01-01T07:05:29-06:00",
              "stop": {
                "id": "s17",
                "location": {
                  "lat": 35.67337,
                  "lon": -78.76063
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 6688,
              "travel_duration": 668
            },
            {
              "arrival_time": "2023-01-01T07:34:43-06:00",
              "cumulative_travel_distance": 44835,
              "cumulative_travel_duration": 4483,
              "duration": 300,
              "end_time": "2023-01-01T07:39:43-06:00",
              "late_arrival_duration": 12883,
              "start_time": "2023-01-01T07:34:43-06:00",
              "stop": {
                "id": "s1",
                "location": {
                  "lat": 35.72389,
                  "lon": -78.90919
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 14543,
              "travel_duration": 1454
            },
            {
              "arrival_time": "2023-01-01T07:55:20-06:00",
              "cumulative_travel_distance": 54198,
              "cumulative_travel_duration": 5420,
              "duration": 300,
              "end_time": "2023-01-01T08:00:20-06:00",
              "late_arrival_duration": 14120,
              "start_time": "2023-01-01T07:55:20-06:00",
              "stop": {
                "id": "s2",
                "location": {
                  "lat": 35.75712,
                  "lon": -78.813862
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 9363,
              "travel_duration": 936
            },
            {
              "arrival_time": "2023-01-01T08:19:08-06:00",
              "cumulative_travel_distance": 65484,
              "cumulative_travel_duration": 6548,
              "duration": 300,
              "end_time": "2023-01-01T08:24:08-06:00",
              "late_arrival_duration": 15548,
              "start_time": "2023-01-01T08:19:08-06:00",
              "stop": {
                "id": "s15",
                "location": {
                  "lat": 35.83202,
                  "lon": -78.89832
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 11286,
              "travel_duration": 1128
            },
            {
              "arrival_time": "2023-01-01T08:43:25-06:00",
              "cumulative_travel_distance": 77046,
              "cumulative_travel_duration": 7705,
              "duration": 300,
              "end_time": "2023-01-01T08:48:25-06:00",
              "late_arrival_duration": 17005,
              "start_time": "2023-01-01T08:43:25-06:00",
              "stop": {
                "id": "s3",
                "location": {
                  "lat": 35.932795,
                  "lon": -78.92996
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 11562,
              "travel_duration": 1156
            },
            {
              "arrival_time": "2023-01-01T09:02:48-06:00",
              "cumulative_travel_distance": 85682,
              "cumulative_travel_duration": 8568,
              "duration": 300,
              "end_time": "2023-01-01T09:07:48-06:00",
              "late_arrival_duration": 18168,
              "start_time": "2023-01-01T09:02:48-06:00",
              "stop": {
                "id": "s18",
                "location": {
                  "lat": 36.009015,
                  "lon": -78.911485
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 8636,
              "travel_duration": 863
            },
            {
              "arrival_time": "2023-01-01T09:55:35-06:00",
              "cumulative_travel_distance": 114350,
              "cumulative_travel_duration": 11435,
              "end_time": "2023-01-01T09:55:35-06:00",
              "start_time": "2023-01-01T09:55:35-06:00",
              "stop": {
                "id": "vehicle-0-end",
                "location": {
                  "lat": 35.791729813680874,
                  "lon": -78.7401685145487
                }
              },
              "travel_distance": 28668,
              "travel_duration": 2866
            }
          ],
          "route_duration": 14135,
          "route_stops_duration": 2700,
          "route_travel_distance": 114350,
          "route_travel_duration": 11435
        },
        {
          "id": "vehicle-1",
          "route": [
            {
              "arrival_time": "2023-01-01T10:00:00-06:00",
              "cumulative_travel_duration": 0,
              "end_time": "2023-01-01T10:00:00-06:00",
              "start_time": "2023-01-01T10:00:00-06:00",
              "stop": {
                "id": "vehicle-1-start",
                "location": {
                  "lat": 35.791729813680874,
                  "lon": -78.7401685145487
                }
              },
              "travel_duration": 0
            },
            {
              "arrival_time": "2023-01-01T10:14:40-06:00",
              "cumulative_travel_distance": 8801,
              "cumulative_travel_duration": 880,
              "duration": 300,
              "end_time": "2023-01-01T10:19:40-06:00",
              "late_arrival_duration": 22480,
              "start_time": "2023-01-01T10:14:40-06:00",
              "stop": {
                "id": "s11",
                "location": {
                  "lat": 35.77013,
                  "lon": -78.83403
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 8801,
              "travel_duration": 880
            },
            {
              "arrival_time": "2023-01-01T10:24:48-06:00",
              "cumulative_travel_distance": 11889,
              "cumulative_travel_duration": 1188,
              "duration": 300,
              "end_time": "2023-01-01T10:29:48-06:00",
              "late_arrival_duration": 23088,
              "start_time": "2023-01-01T10:24:48-06:00",
              "stop": {
                "id": "s12",
                "location": {
                  "lat": 35.782855,
                  "lon": -78.864465
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 3088,
              "travel_duration": 308
            },
            {
              "arrival_time": "2023-01-01T10:56:41-06:00",
              "cumulative_travel_distance": 28011,
              "cumulative_travel_duration": 2801,
              "duration": 300,
              "end_time": "2023-01-01T11:01:41-06:00",
              "late_arrival_duration": 25001,
              "start_time": "2023-01-01T10:56:41-06:00",
              "stop": {
                "id": "s10",
                "location": {
                  "lat": 35.672955,
                  "lon": -78.747955
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 16122,
              "travel_duration": 1612
            },
            {
              "arrival_time": "2023-01-01T11:17:11-06:00",
              "cumulative_travel_distance": 37310,
              "cumulative_travel_duration": 3731,
              "duration": 300,
              "end_time": "2023-01-01T11:22:11-06:00",
              "late_arrival_duration": 26231,
              "start_time": "2023-01-01T11:17:11-06:00",
              "stop": {
                "id": "s9",
                "location": {
                  "lat": 35.64796,
                  "lon": -78.64972
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 9299,
              "travel_duration": 929
            },
            {
              "arrival_time": "2023-01-01T11:52:20-06:00",
              "cumulative_travel_distance": 55404,
              "cumulative_travel_duration": 5540,
              "duration": 300,
              "end_time": "2023-01-01T11:57:20-06:00",
              "late_arrival_duration": 28340,
              "start_time": "2023-01-01T11:52:20-06:00",
              "stop": {
                "id": "s21",
                "location": {
                  "lat": 35.7606,
                  "lon": -78.50509
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 18094,
              "travel_duration": 1809
            },
            {
              "arrival_time": "2023-01-01T12:34:43-06:00",
              "cumulative_travel_distance": 77830,
              "cumulative_travel_duration": 7783,
              "duration": 300,
              "end_time": "2023-01-01T12:39:43-06:00",
              "late_arrival_duration": 30883,
              "start_time": "2023-01-01T12:34:43-06:00",
              "stop": {
                "id": "s14",
                "location": {
                  "lat": 35.961465,
                  "lon": -78.52748
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 22426,
              "travel_duration": 2242
            },
            {
              "arrival_time": "2023-01-01T12:44:22-06:00",
              "cumulative_travel_distance": 80624,
              "cumulative_travel_duration": 8062,
              "duration": 300,
              "end_time": "2023-01-01T12:49:22-06:00",
              "late_arrival_duration": 31462,
              "start_time": "2023-01-01T12:44:22-06:00",
              "stop": {
                "id": "s19",
                "location": {
                  "lat": 35.93663,
                  "lon": -78.522705
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 2794,
              "travel_duration": 279
            },
            {
              "arrival_time": "2023-01-01T13:54:40-06:00",
              "cumulative_travel_distance": 119804,
              "cumulative_travel_duration": 11980,
              "duration": 300,
              "end_time": "2023-01-01T13:59:40-06:00",
              "late_arrival_duration": 35680,
              "start_time": "2023-01-01T13:54:40-06:00",
              "stop": {
                "id": "s13",
                "location": {
                  "lat": 35.88029,
                  "lon": -78.952142
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 39180,
              "travel_duration": 3918
            },
            {
              "arrival_time": "2023-01-01T14:18:14-06:00",
              "cumulative_travel_distance": 130935,
              "cumulative_travel_duration": 13094,
              "duration": 300,
              "end_time": "2023-01-01T14:23:14-06:00",
              "late_arrival_duration": 37094,
              "start_time": "2023-01-01T14:18:14-06:00",
              "stop": {
                "id": "s20",
                "location": {
                  "lat": 35.97414,
                  "lon": -78.995162
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 11131,
              "travel_duration": 1113
            },
            {
              "arrival_time": "2023-01-01T14:37:18-06:00",
              "cumulative_travel_distance": 139380,
              "cumulative_travel_duration": 13938,
              "duration": 300,
              "end_time": "2023-01-01T14:42:18-06:00",
              "late_arrival_duration": 38238,
              "start_time": "2023-01-01T14:37:18-06:00",
              "stop": {
                "id": "s8",
                "location": {
                  "lat": 36.039135,
                  "lon": -78.94658
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 8445,
              "travel_duration": 844
            },
            {
              "arrival_time": "2023-01-01T15:37:38-06:00",
              "cumulative_travel_distance": 172581,
              "cumulative_travel_duration": 17258,
              "end_time": "2023-01-01T15:37:38-06:00",
              "start_time": "2023-01-01T15:37:38-06:00",
              "stop": {
                "id": "vehicle-1-end",
                "location": {
                  "lat": 35.791729813680874,
                  "lon": -78.7401685145487
                }
              },
              "travel_distance": 33201,
              "travel_duration": 3320
            }
          ],
          "route_duration": 20258,
          "route_stops_duration": 3000,
          "route_travel_distance": 172581,
          "route_travel_duration": 17258
        }
      ]
    }
  ],
  "statistics": {
    "result": {
      "custom": {
        "activated_vehicles": 2,
        "max_duration": 20258,
        "max_stops_in_vehicle": 10,
        "max_travel_duration": 17258,
        "min_duration": 14135,
        "min_stops_in_vehicle": 9,
        "min_travel_duration": 11435,
        "unplanned_stops": 7
      },
      "duration": 0.123,
      "value": 2059665.4384450912
    },
    "run": {
      "duration": 0.123,
      "iterations": 50
    },
    "schema": "v1"
  },
  "version": {
    "sdk": "VERSION"
  }
}

Solution

Field name	Always present	Data type	SI Unit	Description	Example
`check`	No	`check`	NA	Information about feasibility of the input or solution.	See `check`
`objective`	Yes	`objective`	NA	Objective value of the solution.	See `objective`
`unplanned`	Yes	`array` of `output_stop`	NA	Unplanned stops.	See `output_stop`
`vehicles`	Yes	`array` of `output_vehicle`	NA	Vehicles with planned stops.	See `output_vehicle`

Check

Check holds information about the feasibility of the input or solution depending on the type of check that was performed. It is only used when the nextcheck feaure is used.

Field name	Always present	Data type	SI Unit	Description	Example
`duration_maximum`	Yes	`float`	`seconds`	The time allowed to generate a feasibility report.	`{"duration_maximum": 12.3}`
`duration_used`	Yes	`float`	`seconds`	The time it took to generate the feasibility report.	`{"duration_used": 12.3}`
`plan_units`	Yes	`array` of `plan_unit`	NA	Reports on the the individual plan units. It defines which stops are part of the plan unit and whether or not is has a best move; if there is no best move reasons are given for why. The level of detail for each plan unit in the plan units report depends on the verbosity defined for the report.	See `plan_unit`
`remark`	Yes	`string`	NA	This reports the status of the check report. Its value can be `completed` or `timedout`.	`{"remark": "completed"}`
`solution`	Yes	`solution`	NA	Contains a summary of the plan being examined. It includes information on the number of plan units that were parsed from the list of stops, the objective function that was defined, and the vehicle information.	See `solution`
`summary`	Yes	`summary`	NA	Summarizes how many plan units need to be checked and how many were checked. It also summarizes the results of the plan units that were checked.	See `summary`
`vehicles`	Yes	`array` of `vehicles`	NA	Aggregates the individual plan units per vehicle.	See `vehicles`
`verbosity`	Yes	`string`	NA	The level of verbosity used to generate the report.	`{"verbosity": "high"}`

Plan unit

A plan unit is a set of stops that need to be visited by one vehicle. Depending on features used in the model, plan units consist of one or more stops. Features that lead to plan units with more than one stop are e.g. Precedence or stop groups.

Field name	Always present	Data type	SI Unit	Description	Example
`stops`	Yes	array of `string`	NA	ID is the ID of the plan unit. The ID of the plan unit is the slice of ID's of the stops in the plan unit.	`{"stops": ["1", "2"]}`
`has_best_move`	Yes	`bool`	NA	True if a move is found for the plan unit. A plan unit has no move found if the plan unit is over-constrained or the move found is too expensive.	`{"has_best_move": true}`
`best_move_increases_objective`	Yes	`bool`	NA	True if the best move for the plan unit increases the objective.	`{"best_move_increases_objective": true}`
`best_move_failed`	Yes	`bool`	NA	True if the plan unit best move failed to execute.	`{"best_move_increases_objective": true}`
`vehicles_have_moves`	No	`int`	NA	The number of vehicles that have moves for the plan unit. Only calculated if the verbosity is `medium` or higher.	`{"vehicles_have_moves": 1}`
`vehicles_with_moves`	No	array of `string`	NA	The IDs of the vehicles that have moves for the plan unit. Only calculated if the verbosity is `very high`.	`{"vehicles_with_moves": ["1", "2"]}`
`constraints`	No	map of `string` to `int`	NA	Shows how often each violated constraint was violated.	`{"maximum_stops": 2}`
`best_move_objective`	No	objective	NA	The estimate of the objective of the best move if the plan unit has a best move.	See objective

Best move objective

Field name	Always present	Data type	SI Unit	Description	Example
`vehicle`	No	`string`	NA	The ID of the vehicle for which it reports the objective.	`{"vehicle": "1"}`
`value`	Yes	`float`	NA	The value of the objective.	`{"value": "1.0"}`
`terms`	Yes	array of `objective term`	NA	The value of the objective terms.	See `objective term`

Objective term

Field name	Always present	Data type	SI Unit	Description	Example
`name`	Yes	`string`	NA	The name of the objective term.	`{"name": "term1"}`
`factor`	Yes	`float`	NA	The factor of the objective term.	`{"factor": 2.0}`
`base`	Yes	`float`	NA	The base value of the objective term.	`{"base": 1.0}`
`value`	Yes	`float`	NA	The value of the objective term which is the `factor` times `base`.	`{"value": 2.0}`

Solution (Nextcheck)

Field name	Always present	Data type	SI Unit	Description	Example
`stops_planned`	Yes	`int`	NA	The number of stops planned in the start solution.	`{"stops_planned": 11}`
`plan_units_planned`	Yes	`int`	NA	The number of units planned in the start solution.	`{"plan_units_planned": 10}`
`plan_units_unplanned`	Yes	`int`	NA	The number of units unplanned in the start solution.	`{"plan_units_unplanned": 9}`
`vehicles_used`	Yes	`int`	NA	The number of vehicles used in the start solution.	`{"vehicles_used": 2}`
`vehicles_not_used`	Yes	`int`	NA	The number of vehicles not used in the start solution, the empty vehicles.	`{"vehicles_not_used": 3}`
`objective`	Yes	`objective`	NA	The objective of the start solution.	See `objective`

Objective (Nextcheck)

Field name	Always present	Data type	SI Unit	Description	Example
`vehicle`	No	`string`	NA	The ID of the vehicle for which it reports the objective.	`{"vehicle": "1"}`
`value`	Yes	`float`	NA	The value of the objective.	`{"value": 2.0}`
`terms`	Yes	array of `objective term`	NA	The check of the individual terms of the objective.	See `objective term`

Summary

Field name	Always present	Data type	SI Unit	Description	Example
`plan_units_to_be_checked`	Yes	`int`	NA	The number of plan units to be checked.	`{"duration_maximum": 12}`
`plan_units_checked`	Yes	`int`	NA	The number of plan units checked. If this is less than `plan_units_to_be_checked` the check timed out.	`{"plan_units_checked": 42}`
`plan_units_best_move_found`	Yes	`int`	NA	The number of plan units for which at least one move has been found and the move is executable.	`{"plan_units_best_move_found": 2}`
`plan_units_have_no_move`	Yes	`int`	NA	The number of plan units for which no feasible move has been found. This implies there is no move that can be executed without violating a constraint.	`{"plan_units_have_no_move": 12}`
`plan_units_best_move_increases_objective`	Yes	`int`	NA	The number of plan units for which the best move is executable but would increase the objective value instead of decreasing it.	`{"plan_units_best_move_increases_objective": 12}`
`plan_units_best_move_failed`	Yes	`int`	NA	The number of plan units for which the best move can not be planned. This should not happen if all the constraints are implemented correct.	`{"plan_units_best_move_failed": 12}`
`moves_failed`	Yes	`int`	NA	The number of moves that failed.	`{"moves_failed": 12}`

Vehicle (Nextcheck)

Field name	Always present	Data type	SI Unit	Description	Example
`id`	Yes	`string`	NA	The ID of the vehicle.	`{"id": "vehicle-1"}`
`plan_units_have_moves`	No	`int`	NA	The number of plan units that have moves for the vehicle. Only calculated if the depth is `medium`.	`{"plan_units_have_moves": 1}`

Objective

Field name	Always present	Data type	SI Unit	Description	Example
`name`	Yes	`string`	NA	Name of the objective.	`{"name": "foo"}`
`objectives`	No	`array` of `objective`	NA	Terms of the main objective.	`{"objectives": [{"name": "foo"}, {"name": "bar"}]}`
`factor`	Yes	`float`	NA	Factor of the objective.	`{"factor": 1.23}`
`base`	Yes	`float`	NA	Base value of the objective.	`{"base": 1.23}`
`value`	Yes	`float`	NA	Value of the objective, equivalent to `factor * base`.	`{"value": 1.23}`

Output stop

Field name	Always present	Data type	SI Unit	Description	Example
`id`	Yes	`string`	NA	Unique identifier for the stop.	`{"id": "foo"}`
`location`	Yes	`location`	NA	Location of the stop.	`{"location": {"lon": 1.23, "lat": 4.56}}`
`custom_data`	No, only if defined on the input `stop`	`any`	NA	Custom data to be used arbitrarily within the model.	`{"custom_data": {"foo": "bar"}}`

Output vehicle

Field name	Always present	Data type	SI Unit	Description	Example
`id`	Yes	`string`	NA	Unique identifier for the vehicle.	`{"id": "foo"}`
`route`	Yes	`array` of `planned_stop`	NA	Planned stops for the vehicle.	See `planned_stop`
`route_travel_duration`	Yes	`int`	`seconds`	Total travel duration of the route.	`{"route_travel_duration": 123}`
`route_duration`	Yes	`int`	`seconds`	Total duration of the route, including waiting times.	`{"route_duration": 123}`
`route_stops_duration`	No, only if greater than zero.	`int`	`seconds`	Total duration of the service times across all stops.	`{"route_stops_duration": 123}`
`route_waiting_duration`	No, only if greater than zero.	`int`	`seconds`	Total waiting time across all stops.	`{"route_waiting_duration": 123}`
`custom_data`	No, only if defined on the input `vehicle`	`any`	NA	Custom data to be used arbitrarily within the model.	`{"custom_data": {"foo": "bar"}}`
`route_travel_distance`	No, only if greater than zero.	`int`	`meters`	Total travel distance of the route.	`{"route_travel_distance": 123}`

Planned stop

Field name	Always present	Data type	SI Unit	Description	Example
`stop`	Yes	`output_stop`	NA	Stop that was planned.	See `output_stop`
`cumulative_travel_duration`	Yes	`int`	`seconds`	Cumulative travel duration of the route up to the stop.	`{"cumulative_travel_duration": 123}`
`travel_duration`	Yes	`int`	`seconds`	Travel duration from the previous stop to the current stop.	`{"travel_duration": 123}`
`target_arrival_time`	No, only if defined on the input `stop`	`timestamp`	NA	Target arrival time at the stop.	`{"target_arrival_time": "2023-01-01T00:00:00Z"}`
`arrival_time`	No, only if the input `vehicle` has `start_time`	`timestamp`	NA	Arrival time at the stop.	`{"arrival_time": "2023-01-01T00:00:00Z"}`
`start_time`	No, only if the input `vehicle` has `start_time`	`timestamp`	NA	Time at which the stop starts service.	`{"start_time": "2023-01-01T00:00:00Z"}`
`end_time`	No, only if the input `vehicle` has `start_time`	`timestamp`	NA	Time at which the stop ends service.	`{"end_time": "2023-01-01T00:00:00Z"}`
`waiting_duration`	No, only if greater than zero.	`int`	`seconds`	Waiting time at the stop.	`{"waiting_duration": 123}`
`duration`	No, only if greater than zero.	`int`	`seconds`	Duration of the service time at the stop.	`{"duration": 123}`
`early_arrival_duration`	No, only if greater than zero.	`int`	`seconds`	Duration by which the vehicle arrived early at the stop.	`{"early_arrival_duration": 123}`
`late_arrival_duration`	No, only if greater than zero.	`int`	`seconds`	Duration by which the vehicle arrived late at the stop.	`{"late_arrival_duration": 123}`
`cumulative_travel_distance`	No, only if greater than zero.	`int`	`meters`	Cumulative travel distance of the route up to the stop.	`{"cumulative_travel_distance": 123}`
`travel_distance`	No, only if greater than zero.	`int`	`meters`	Travel distance from the previous stop to the current stop.	`{"travel_distance": 123}`

Statistics

By default, all fields in statistics are always present. The -format.disable.progression option can be used to disable the result and series_data fields.

Field name	Always present	Data type	SI Unit	Description / Example
`result`	No	`result`	NA	Final result of the solutions. See `result`
`run`	Yes	`run`	NA	Information of the run. See `run`
`schema`	Yes	`string`	NA	Schema of the statistics. `{"schema": "v1"}`
`series_data`	No	`series_data`	NA	Data series of solution values. See `series_data`

See the Add custom statistics section for an example of how to add your own custom statistics.

Here you can find additional definitions used in the statistics schema:

`result`

Field name Always present Data type SI Unit Description / Example

Field name	Always present	Data type	SI Unit	Description / Example
`duration`	Yes	`float`	`seconds`	Time duration to get to the final result. `{"duration": 0.123}`
`value`	Yes	`float`	NA	Value of the final result. `{"value": 0.123}`
`custom`	No	`any`	NA	Custom metrics specified in the custom app (see below). `{ "custom": { "activated_vehicles": 2, "unplanned_stops": 4 } }`

duration

Yes

float

seconds

Time duration to get to the final result.

{"duration": 0.123}

value

Yes

float

Value of the final result.

{"value": 0.123}

custom

any

Custom metrics specified in the custom app (see below).

{ "custom": { "activated_vehicles": 2, "unplanned_stops": 4 } }

`run`

Field name Always present Data type SI Unit Description / Example

Field name	Always present	Data type	SI Unit	Description / Example
`duration`	Yes	`float`	`seconds`	Time duration of the run. `{"duration": 0.123}`
`iterations`	No	`integer`	NA	A measure of work done within the algorithm, typically to improve a solution. `{"iterations": 45093}`

duration

Yes

float

seconds

Time duration of the run.

{"duration": 0.123}

iterations

integer

A measure of work done within the algorithm, typically to improve a solution.

{"iterations": 45093}

`series_data`

Field name Always present Data type SI Unit Description / Example

Field name	Always present	Data type	SI Unit	Description / Example
`value`	Yes	`series`	NA	Value of the data series. See `series`
`custom`	No	`array` of `series`	NA	Custom data in the series, will only appear if specified explicitly. See `series`

value

Yes

series

Value of the data series.

See series

custom

array of series

Custom data in the series, will only appear if specified explicitly.

See series

`series`

Field name Always present Data type SI Unit Description / Example

Field name	Always present	Data type	SI Unit	Description / Example
`name`	Yes	`string`	NA	Name of the series. `{"name": "foo"}`
`data_points`	Yes	`array` of `data_point`	NA	Data points of the series. See `data_point`

name

Yes

string

Name of the series.

{"name": "foo"}

data_points

Yes

array of data_point

Data points of the series.

See data_point

`data_point`

Field name Always present Data type SI Unit Description / Example

Field name	Always present	Data type	SI Unit	Description / Example
`x`	Yes	`float`	NA	X value of the data point. `{"x": 0.123}`
`y`	Yes	`float`	NA	Y value of the data point. `{"y": 0.123}`

x

Yes

float

X value of the data point.

{"x": 0.123}

y

Yes

float

Y value of the data point.

{"y": 0.123}

A reference for the input and output schemas in vehicle routing.

Input

Alternate stop

Defaults

Duration Group

Location

Stop

Vehicle

Input schema Validation

Output

Solution

Check

Plan unit

Best move objective

Objective term

Solution (Nextcheck)

Objective (Nextcheck)

Summary

Vehicle (Nextcheck)

Objective

Output stop

Output vehicle

Planned stop

Statistics

`result`

`run`

`series_data`

`series`

`data_point`

Features

Options

Contents