Early arrival time penalty

This feature is configurable via .json input, without the need for code customization and is available for both the Marketplace app and Platform. You can find a list of all available features here.

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

This how-to guide assumes you already completed the get started with vehicle routing tutorial.

Field name	Required	Data type	SI Unit	Defined on	Example	Configurable via `defaults`
`target_arrival_time`	No	`timestamp`	NA	`stop`	`{"target_arrival_time": "2023-01-01T00:00:00Z"}`	✅
`early_arrival_time_penalty`	No	`float`	NA	`stop`	`{"early_arrival_time_penalty": 1.23}`	✅

The early_arrival_time_penalty is a cost applied to the objective (value function) when a vehicle arrives at a stop before the given target_arrival_time. These fields are defined on stops, and are useful for discouraging behavior such as ride sharing vehicles arriving too early for an airport pickup.

The value added to the objective is calculated as follows:

early_arrival_time_penalty * max(target_arrival_time - arrival_time, 0)

For example, if a vehicle arrives at a stop 60 seconds before a target arrival time and the penalty is set to 10, 600 seconds are added to the value function.

Please note that:

The time duration given by target_arrival_time - arrival_time is in seconds.
When defining an early_arrival_time_penalty on a stop, you must also define a target_arrival_time for that stop.
Specifying early_arrival_time_penalty and target_arrival_time on a stop brings additional information on the output. For example, the early_arrival_duration of the stop defines the time duration given by target_arrival_time - arrival_time in seconds, when greater than zero.

Here is an example defining penalties for all stops. A sample output obtained after solving the problem is also shown.

Input (JSON)
Output (JSON)

{
  "defaults": {
    "vehicles": {
      "speed": 20,
      "start_time": "2023-01-01T12:00:00Z"
    },
    "stops": {
      "early_arrival_time_penalty": 1.5,
      "unplanned_penalty": 2000000
    }
  },
  "stops": [
    {
      "id": "Fushimi Inari Taisha",
      "location": { "lon": 135.772695, "lat": 34.967146 },
      "target_arrival_time": "2023-01-01T12:00:00Z"
    },
    {
      "id": "Kiyomizu-dera",
      "location": { "lon": 135.78506, "lat": 34.994857 },
      "target_arrival_time": "2023-01-01T12:05:00Z"
    },
    {
      "id": "Nijō Castle",
      "location": { "lon": 135.748134, "lat": 35.014239 },
      "target_arrival_time": "2023-01-01T12:10:00Z"
    },
    {
      "id": "Kyoto Imperial Palace",
      "location": { "lon": 135.762057, "lat": 35.025431 },
      "target_arrival_time": "2023-01-01T12:15:00Z"
    },
    {
      "id": "Gionmachi",
      "location": { "lon": 135.775682, "lat": 35.002457 },
      "target_arrival_time": "2023-01-01T12:20:00Z"
    },
    {
      "id": "Kinkaku-ji",
      "location": { "lon": 135.728898, "lat": 35.039705 },
      "target_arrival_time": "2023-01-01T12:25:00Z"
    },
    {
      "id": "Arashiyama Bamboo Forest",
      "location": { "lon": 135.672009, "lat": 35.017209 },
      "target_arrival_time": "2023-01-01T12:30:00Z"
    }
  ],
  "vehicles": [
    {
      "id": "v1"
    },
    {
      "id": "v2"
    }
  ]
}

Early arrival time penalty

A how-to guide for using early arrival time penalties with vehicle routing.

Duration matrix

Late arrival time penalty