Skip to content

Input/output schema

Input

Info

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:

{
  "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

Info

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}

Vehicle

Info

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}

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:

{
  "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,
        "distance": 0,
        "early_arrival_penalty": 1,
        "late_arrival_penalty": 1,
        "min_stops": 1,
        "stop_balance": 0,
        "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
        },
        "maximum_time_horizon": 15552000
      },
      "validate": {
        "disable": {
          "resources": false,
          "start_time": false
        },
        "enable": {
          "matrix": false,
          "matrix_asymmetry_tolerance": 20
        }
      }
    },
    "solve": {
      "duration": 10000000000,
      "iterations": 50,
      "parallel_runs": 1,
      "plateau": {
        "absolute_threshold": -1,
        "delay": 0,
        "duration": 0,
        "iterations": 0,
        "relative_threshold": 0
      },
      "run_deterministically": true,
      "solver": {
        "plan_group_size": {
          "delta": 0,
          "delta_after_iterations": 1000000000,
          "max_value": 2,
          "min_value": 2,
          "snap_back_after_improvement": true,
          "start_value": 2,
          "zigzag": true
        },
        "unplan_units": {
          "delta": 2,
          "delta_after_iterations": 125,
          "max_value": -1,
          "min_value": 2,
          "snap_back_after_improvement": true,
          "start_value": 2,
          "zigzag": true
        },
        "unplan_weights": "Vehicle:3,Island:1,Location:293"
      },
      "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": 0.123,
        "max_stops_in_vehicle": 10,
        "max_travel_duration": 0.123,
        "min_duration": 0.123,
        "min_stops_in_vehicle": 9,
        "min_travel_duration": 0.123,
        "unplanned_stops": 7
      },
      "duration": 0.123,
      "value": 0.123
    },
    "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

Info

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 metrics 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
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 } }

run

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}

series_data

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

series

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

data_point

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}