REST Resource: projects.locations.workspaces.vehicles

Resource: Vehicle

Models a vehicle in a shipment problem. Solving a shipment problem will build a route starting from startLocation and ending at endLocation for this vehicle. A route is a sequence of visits (see ShipmentRoute).

JSON representation 
{
  "name": string,
  "displayName": string,
  "travelMode": enum (TravelMode),
  "routeModifiers": {
    object (RouteModifiers)
  },
  "startLocation": {
    object (LatLng)
  },
  "startWaypoint": {
    object (Waypoint)
  },
  "endLocation": {
    object (LatLng)
  },
  "endWaypoint": {
    object (Waypoint)
  },
  "startTags": [
    string
  ],
  "endTags": [
    string
  ],
  "startTimeWindows": [
    {
      object (TimeWindow)
    }
  ],
  "endTimeWindows": [
    {
      object (TimeWindow)
    }
  ],
  "unloadingPolicy": enum (UnloadingPolicy),
  "loadLimits": {
    string: {
      object (LoadLimit)
    },
    ...
  },
  "costPerHour": number,
  "costPerTraveledHour": number,
  "costPerKilometer": number,
  "fixedCost": number,
  "usedIfRouteIsEmpty": boolean,
  "routeDurationLimit": {
    object (DurationLimit)
  },
  "travelDurationLimit": {
    object (DurationLimit)
  },
  "routeDistanceLimit": {
    object (DistanceLimit)
  },
  "extraVisitDurationForVisitType": {
    string: string,
    ...
  },
  "breakRule": {
    object (BreakRule)
  },
  "label": string,
  "ignore": boolean,
  "routeCommitments": {
    object (RouteCommitments)
  },
  "breakRuleIndices": [
    integer
  ],
  "capacities": [
    {
      object (CapacityQuantity)
    }
  ],
  "startLoadIntervals": [
    {
      object (CapacityQuantityInterval)
    }
  ],
  "endLoadIntervals": [
    {
      object (CapacityQuantityInterval)
    }
  ],
  "travelDurationMultiple": number
}
Fields
name

string

The resource name of the vehicle. This is a unique identifier. Format: projects/{project}/locations/{location}/workspaces/{workspace}/vehicles/{vehicle} This field would be ignored while calling OptimizeTours and BatchOptimizeTours methods.
displayName

string

The user-defined display name of the vehicle. It can be up to 63 characters long and may use UTF-8 characters.
travelMode

enum (TravelMode)

The travel mode which affects the roads usable by the vehicle and its speed. See also travelDurationMultiple.
routeModifiers

object (RouteModifiers)

Optional. A set of conditions to satisfy that affect the way routes are calculated for the given vehicle.
startLocation

object (LatLng)

Geographic location where the vehicle starts before picking up any shipments. If not specified, the vehicle starts at its first pickup. If the shipment model has duration and distance matrices, startLocation must not be specified.
startWaypoint

object (Waypoint)

Waypoint representing a geographic location where the vehicle starts before picking up any shipments. If neither startWaypoint nor startLocation is specified, the vehicle starts at its first pickup. If the shipment model has duration and distance matrices, startWaypoint must not be specified.
endLocation

object (LatLng)

Geographic location where the vehicle ends after it has completed its last VisitRequest. If not specified the vehicle's ShipmentRoute ends immediately when it completes its last VisitRequest. If the shipment model has duration and distance matrices, endLocation must not be specified.
endWaypoint

object (Waypoint)

Waypoint representing a geographic location where the vehicle ends after it has completed its last VisitRequest. If neither endWaypoint nor endLocation is specified, the vehicle's ShipmentRoute ends immediately when it completes its last VisitRequest. If the shipment model has duration and distance matrices, endWaypoint must not be specified.
startTags[]

string

Specifies tags attached to the start of the vehicle's route.

Empty or duplicate strings are not allowed.
endTags[]

string

Specifies tags attached to the end of the vehicle's route.

Empty or duplicate strings are not allowed.
startTimeWindows[]

object (TimeWindow)

Time windows during which the vehicle may depart its start location. They must be within the global time limits (see ShipmentModel.global_* fields). If unspecified, there is no limitation besides those global time limits.

Time windows belonging to the same repeated field must be disjoint, i.e. no time window can overlap with or be adjacent to another, and they must be in chronological order.

costPerHourAfterSoftEndTime and softEndTime can only be set if there is a single time window.
endTimeWindows[]

object (TimeWindow)

Time windows during which the vehicle may arrive at its end location. They must be within the global time limits (see ShipmentModel.global_* fields). If unspecified, there is no limitation besides those global time limits.

Time windows belonging to the same repeated field must be disjoint, i.e. no time window can overlap with or be adjacent to another, and they must be in chronological order.

costPerHourAfterSoftEndTime and softEndTime can only be set if there is a single time window.
unloadingPolicy

enum (UnloadingPolicy)

Unloading policy enforced on the vehicle.
loadLimits

map (key: string, value: object (LoadLimit))

Capacities of the vehicle (weight, volume, # of pallets for example). The keys in the map are the identifiers of the type of load, consistent with the keys of the Shipment.load_demands field. If a given key is absent from this map, the corresponding capacity is considered to be limitless.
costPerHour

number

Vehicle costs: all costs add up and must be in the same unit as Shipment.penalty_cost.

Cost per hour of the vehicle route. This cost is applied to the total time taken by the route, and includes travel time, waiting time, and visit time. Using costPerHour instead of just costPerTraveledHour may result in additional latency.
costPerTraveledHour

number

Cost per traveled hour of the vehicle route. This cost is applied only to travel time taken by the route (i.e., that reported in ShipmentRoute.transitions), and excludes waiting time and visit time.
costPerKilometer

number

Cost per kilometer of the vehicle route. This cost is applied to the distance reported in the ShipmentRoute.transitions and does not apply to any distance implicitly traveled from the arrivalLocation to the departureLocation of a single VisitRequest.
fixedCost

number

Fixed cost applied if this vehicle is used to handle a shipment.
usedIfRouteIsEmpty

boolean

This field only applies to vehicles when their route does not serve any shipments. It indicates if the vehicle should be considered as used or not in this case.

If true, the vehicle goes from its start to its end location even if it doesn't serve any shipments, and time and distance costs resulting from its start --> end travel are taken into account.

Otherwise, it doesn't travel from its start to its end location, and no breakRule or delay (from TransitionAttributes) are scheduled for this vehicle. In this case, the vehicle's ShipmentRoute doesn't contain any information except for the vehicle index and label.
routeDurationLimit

object (DurationLimit)

Limit applied to the total duration of the vehicle's route. In a given OptimizeToursResponse, the route duration of a vehicle is the difference between its vehicleEndTime and vehicleStartTime.
travelDurationLimit

object (DurationLimit)

Limit applied to the travel duration of the vehicle's route. In a given OptimizeToursResponse, the route travel duration is the sum of all its transitions.travel_duration.
routeDistanceLimit

object (DistanceLimit)

Limit applied to the total distance of the vehicle's route. In a given OptimizeToursResponse, the route distance is the sum of all its transitions.travel_distance_meters.
extraVisitDurationForVisitType

map (key: string, value: string (Duration format))

Specifies a map from visitTypes strings to durations. The duration is time in addition to VisitRequest.duration to be taken at visits with the specified visitTypes. This extra visit duration adds cost if costPerHour is specified. Keys (i.e. visitTypes) cannot be empty strings.

If a visit request has multiple types, a duration will be added for each type in the map.
breakRule

object (BreakRule)

Describes the break schedule to be enforced on this vehicle. If empty, no breaks will be scheduled for this vehicle.
label

string

Specifies a label for this vehicle. This label is reported in the response as the vehicleLabel of the corresponding ShipmentRoute.
ignore

boolean

If true, usedIfRouteIsEmpty must be false, and this vehicle will remain unused.

If a shipment is performed by an ignored vehicle in injectedFirstSolutionRoutes, it is skipped in the first solution but is free to be performed in the response.

If a shipment is performed by an ignored vehicle in injectedSolutionConstraint and any related pickup/delivery is constrained to remain on the vehicle (i.e., not relaxed to level RELAX_ALL_AFTER_THRESHOLD), it is skipped in the response. If a shipment has a non-empty allowedVehicleIndices field and all of the allowed vehicles are ignored, it is skipped in the response.
routeCommitments

object (RouteCommitments)

The route execution state of the vehicle. This field is used in the stateful service only.
breakRuleIndices[]
(deprecated)

integer

Deprecated: No longer used. Indices in the breakRule field in the source ShipmentModel. They correspond to break rules enforced on the vehicle.

As of 2018/03, at most one rule index per vehicle can be specified.
capacities[]
(deprecated)

object (CapacityQuantity)

Deprecated: Use Vehicle.load_limits instead.
startLoadIntervals[]
(deprecated)

object (CapacityQuantityInterval)

Deprecated: Use Vehicle.LoadLimit.start_load_interval instead.
endLoadIntervals[]
(deprecated)

object (CapacityQuantityInterval)

Deprecated: Use Vehicle.LoadLimit.end_load_interval instead.
travelDurationMultiple

number

Specifies a multiplicative factor that can be used to increase or decrease travel times of this vehicle. For example, setting this to 2.0 means that this vehicle is slower and has travel times that are twice what they are for standard vehicles. This multiple does not affect visit durations. It does affect cost if costPerHour or costPerTraveledHour are specified. This must be in the range [0.001, 1000.0]. If unset, the vehicle is standard, and this multiple is considered 1.0.

WARNING: Travel times will be rounded to the nearest second after this multiple is applied but before performing any numerical operations, thus, a small multiple may result in a loss of precision.

See also extraVisitDurationForVisitType below.

TravelMode

Travel modes which can be used by vehicles.

These should be a subset of the Google Maps Platform Routes Preferred API travel modes, see: https://developers.google.com/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode.

Enums
TRAVEL_MODE_UNSPECIFIED Unspecified travel mode, equivalent to DRIVING.
DRIVING Travel mode corresponding to driving directions (car, ...).
WALKING Travel mode corresponding to walking directions.

RouteModifiers

Encapsulates a set of optional conditions to satisfy when calculating vehicle routes. This is similar to RouteModifiers in the Google Maps Platform API; see: https://developers.google.com/maps/documentation/routes/reference/rest/v2/RouteModifiers.

JSON representation 
{
  "avoidTolls": boolean,
  "avoidHighways": boolean,
  "avoidFerries": boolean,
  "avoidIndoor": boolean
}
Fields
avoidTolls

boolean

Specifies whether to avoid toll roads where reasonable. Preference will be given to routes not containing toll roads. Applies only to motorized travel modes.
avoidHighways

boolean

Specifies whether to avoid highways where reasonable. Preference will be given to routes not containing highways. Applies only to motorized travel modes.
avoidFerries

boolean

Specifies whether to avoid ferries where reasonable. Preference will be given to routes not containing travel by ferries. Applies only to motorized travel modes.
avoidIndoor

boolean

Optional. Specifies whether to avoid navigating indoors where reasonable. Preference will be given to routes not containing indoor navigation. Applies only to the WALKING travel mode.

UnloadingPolicy

Policy on how a vehicle can be unloaded. Applies only to shipments having both a pickup and a delivery.

Other shipments are free to occur anywhere on the route independent of unloadingPolicy.

Enums
UNLOADING_POLICY_UNSPECIFIED Unspecified unloading policy; deliveries must just occur after their corresponding pickups.
LAST_IN_FIRST_OUT Deliveries must occur in reverse order of pickups
FIRST_IN_FIRST_OUT Deliveries must occur in the same order as pickups

LoadLimit

Defines a load limit applying to a vehicle, e.g. "this truck may only carry up to 3500 kg". See loadLimits.

JSON representation 
{
  "softMaxLoad": string,
  "costPerUnitAboveSoftMax": number,
  "startLoadInterval": {
    object (Interval)
  },
  "endLoadInterval": {
    object (Interval)
  },
  "maxLoad": string
}
Fields
softMaxLoad

string (int64 format)

A soft limit of the load. See costPerUnitAboveSoftMax.
costPerUnitAboveSoftMax

number

If the load ever exceeds softMaxLoad along this vehicle's route, the following cost penalty applies (only once per vehicle): (load - softMaxLoad) * costPerUnitAboveSoftMax. All costs add up and must be in the same unit as Shipment.penalty_cost.
startLoadInterval

object (Interval)

The acceptable load interval of the vehicle at the start of the route.
endLoadInterval

object (Interval)

The acceptable load interval of the vehicle at the end of the route.
maxLoad

string (int64 format)

The maximum acceptable amount of load.

Interval

Interval of acceptable load amounts.

JSON representation 
{
  "min": string,
  "max": string
}
Fields
min

string (int64 format)

A minimum acceptable load. Must be ≥ 0. If they're both specified, min must be ≤ max.
max

string (int64 format)

A maximum acceptable load. Must be ≥ 0. If unspecified, the maximum load is unrestricted by this message. If they're both specified, min must be ≤ max.

DurationLimit

A limit defining a maximum duration of the route of a vehicle. It can be either hard or soft.

When a soft limit field is defined, both the soft max threshold and its associated cost must be defined together.

JSON representation 
{
  "maxDuration": string,
  "softMaxDuration": string,
  "quadraticSoftMaxDuration": string,
  "costPerHourAfterSoftMax": number,
  "costPerSquareHourAfterQuadraticSoftMax": number
}
Fields
maxDuration

string (Duration format)

A hard limit constraining the duration to be at most maxDuration.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
softMaxDuration

string (Duration format)

A soft limit not enforcing a maximum duration limit, but when violated makes the route incur a cost. This cost adds up to other costs defined in the model, with the same unit.

If defined, softMaxDuration must be nonnegative. If maxDuration is also defined, softMaxDuration must be less than maxDuration.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
quadraticSoftMaxDuration

string (Duration format)

A soft limit not enforcing a maximum duration limit, but when violated makes the route incur a cost, quadratic in the duration. This cost adds up to other costs defined in the model, with the same unit.

If defined, quadraticSoftMaxDuration must be nonnegative. If maxDuration is also defined, quadraticSoftMaxDuration must be less than maxDuration, and the difference must be no larger than one day:

maxDuration - quadraticSoftMaxDuration <= 86400 seconds

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
costPerHourAfterSoftMax

number

Cost per hour incurred if the softMaxDuration threshold is violated. The additional cost is 0 if the duration is under the threshold, otherwise the cost depends on the duration as follows:

  costPerHourAfterSoftMax * (duration - softMaxDuration)

The cost must be nonnegative.
costPerSquareHourAfterQuadraticSoftMax

number

Cost per square hour incurred if the quadraticSoftMaxDuration threshold is violated.

The additional cost is 0 if the duration is under the threshold, otherwise the cost depends on the duration as follows:

  costPerSquareHourAfterQuadraticSoftMax *
  (duration - quadraticSoftMaxDuration)^2

The cost must be nonnegative.

BreakRule

Rules to generate time breaks for a vehicle (e.g. lunch breaks). A break is a contiguous period of time during which the vehicle remains idle at its current position and cannot perform any visit. A break may occur:

  • during the travel between two visits (which includes the time right before or right after a visit, but not in the middle of a visit), in which case it extends the corresponding transit time between the visits,
  • or before the vehicle start (the vehicle may not start in the middle of a break), in which case it does not affect the vehicle start time.
  • or after the vehicle end (ditto, with the vehicle end time).
JSON representation 
{
  "breakRequests": [
    {
      object (BreakRequest)
    }
  ],
  "frequencyConstraints": [
    {
      object (FrequencyConstraint)
    }
  ]
}
Fields
breakRequests[]

object (BreakRequest)

Sequence of breaks. See the BreakRequest message.
frequencyConstraints[]

object (FrequencyConstraint)

Several FrequencyConstraint may apply. They must all be satisfied by the BreakRequests of this BreakRule. See FrequencyConstraint.

BreakRequest

The sequence of breaks (i.e. their number and order) that apply to each vehicle must be known beforehand. The repeated BreakRequests define that sequence, in the order in which they must occur. Their time windows (earliestStartTime / latestStartTime) may overlap, but they must be compatible with the order (this is checked).

JSON representation 
{
  "earliestStartTime": string,
  "latestStartTime": string,
  "minDuration": string
}
Fields
earliestStartTime

string (Timestamp format)

Required. Lower bound (inclusive) on the start of the break.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
latestStartTime

string (Timestamp format)

Required. Upper bound (inclusive) on the start of the break.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
minDuration

string (Duration format)

Required. Minimum duration of the break. Must be positive.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

FrequencyConstraint

One may further constrain the frequency and duration of the breaks specified above, by enforcing a minimum break frequency, such as "There must be a break of at least 1 hour every 12 hours". Assuming that this can be interpreted as "Within any sliding time window of 12h, there must be at least one break of at least one hour", that example would translate to the following FrequencyConstraint:

{
   minBreakDuration { seconds: 3600 }         # 1 hour.
   maxInterBreakDuration { seconds: 39600 }  # 11 hours (12 - 1 = 11).
}

The timing and duration of the breaks in the solution will respect all such constraints, in addition to the time windows and minimum durations already specified in the BreakRequest.

A FrequencyConstraint may in practice apply to non-consecutive breaks. For example, the following schedule honors the "1h every 12h" example:

  04:00 vehicle start
   .. performing travel and visits ..
  09:00 1 hour break
  10:00 end of the break
   .. performing travel and visits ..
  12:00 20-min lunch break
  12:20 end of the break
   .. performing travel and visits ..
  21:00 1 hour break
  22:00 end of the break
   .. performing travel and visits ..
  23:59 vehicle end
JSON representation 
{
  "minBreakDuration": string,
  "maxInterBreakDuration": string
}
Fields
minBreakDuration

string (Duration format)

Required. Minimum break duration for this constraint. Nonnegative. See description of FrequencyConstraint.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
maxInterBreakDuration

string (Duration format)

Required. Maximum allowed span of any interval of time in the route that does not include at least partially a break of duration >= minBreakDuration. Must be positive.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

RouteCommitments

Information about the vehicle's execution of a route to be used in constraining the solution ShipmentRoute obtained from a re-optimization. In particular, specifies route start time (i.e., actual, not planned), actual past visit start times, and committed sequence of future visits.

JSON representation 
{
  "routeStartTime": string,
  "pastVisits": [
    {
      object (Visit)
    }
  ],
  "nextVisits": [
    {
      object (Visit)
    }
  ]
}
Fields
routeStartTime

string (Timestamp format)

The actual time when the vehicle started executing its route. This must only be specified if the vehicle has started its route.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
pastVisits[]

object (Visit)

Visits that the vehicle has actually started (not necessarily completed) in the past, including their startTimes. These visits must have startTime >= routeStartTime and be in order of startTime.
nextVisits[]

object (Visit)

Visits that the vehicle is committed to doing next. These visits must not have startTime specified, but must be listed in the sequence that they are to be performed.

Visit

Specifies a pickup or delivery visit of a particular Shipment and, optionally, its startTime, which should only be set if the visit has actually happened.

JSON representation 
{
  "shipmentName": string,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string
}
Fields
shipmentName

string

The resource name of the shipment.
isPickup

boolean

If true, the visit corresponds to a pickup of a Shipment. Otherwise, it corresponds to a delivery.
visitRequestIndex

integer

Index of VisitRequest in either the pickup or delivery field of the Shipment.
startTime

string (Timestamp format)

Leave unset for nextVisits.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

CapacityQuantityInterval

Deprecated: Use Vehicle.LoadLimit.Interval instead.

JSON representation 
{
  "type": string,
  "minValue": string,
  "maxValue": string
}
Fields
type

string
minValue

string (int64 format)
maxValue

string (int64 format)

Methods

create

 Creates a vehicle.

delete

 Deletes a vehicle.

get

 Gets a vehicle.

list

 Lists the vehicles within a workspace.

patch

 Updates a vehicle.