REST Resource: projects.locations.workspaces.shipments

Resource: Shipment

The shipment of a single item, from one of its pickups to one of its deliveries. For the shipment to be considered as performed, a unique vehicle must visit one of its pickup locations (and decrease its spare capacities accordingly), then visit one of its delivery locations later on (and therefore re-increase its spare capacities accordingly).

JSON representation 
{
  "name": string,
  "displayName": string,
  "pickups": [
    {
      object (VisitRequest)
    }
  ],
  "deliveries": [
    {
      object (VisitRequest)
    }
  ],
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "allowedVehicleIndices": [
    integer
  ],
  "allowedVehicleNames": [
    string
  ],
  "costsPerVehicle": [
    number
  ],
  "costsPerVehicleIndices": [
    integer
  ],
  "costsPerVehicleNames": [
    string
  ],
  "pickupToDeliveryAbsoluteDetourLimit": string,
  "pickupToDeliveryTimeLimit": string,
  "shipmentType": string,
  "label": string,
  "ignore": boolean,
  "demands": [
    {
      object (CapacityQuantity)
    }
  ],
  "penaltyCost": number,
  "pickupToDeliveryRelativeDetourLimit": number
}
Fields
name

string

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

string

The user-defined display name of the shipment. It can be up to 63 characters long and may use UTF-8 characters.
pickups[]

object (VisitRequest)

Set of pickup alternatives associated to the shipment. If not specified, the vehicle only needs to visit a location corresponding to the deliveries.
deliveries[]

object (VisitRequest)

Set of delivery alternatives associated to the shipment. If not specified, the vehicle only needs to visit a location corresponding to the pickups.
loadDemands

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

Load demands of the shipment (for example weight, volume, number of pallets etc). The keys in the map should be identifiers describing the type of the corresponding load, ideally also including the units. For example: "weight_kg", "volume_gallons", "pallet_count", etc. If a given key does not appear in the map, the corresponding load is considered as null.
allowedVehicleIndices[]

integer

The set of vehicles that may perform this shipment. If empty, all vehicles may perform it. Vehicles are given by their index in the ShipmentModel's vehicles list.
allowedVehicleNames[]

string

The resource names of vehicles that may perform this shipment. If empty, all vehicles may perform it. This field is used in the stateful service only.
costsPerVehicle[]

number

Specifies the cost that is incurred when this shipment is delivered by each vehicle. If specified, it must have EITHER:

  • the same number of elements as costsPerVehicleIndices. costsPerVehicle[i] corresponds to vehicle costsPerVehicleIndices[i] of the model.
  • the same number of elements as there are vehicles in the model. The i-th element corresponds to vehicle #i of the model.

These costs must be in the same unit as penaltyCost and must not be negative. Leave this field empty, if there are no such costs.
costsPerVehicleIndices[]

integer

Indices of the vehicles to which costsPerVehicle applies. If non-empty, it must have the same number of elements as costsPerVehicle. A vehicle index may not be specified more than once. If a vehicle is excluded from costsPerVehicleIndices, its cost is zero.
costsPerVehicleNames[]

string

Resource names of the vehicles to which costsPerVehicle applies. If non-empty, it must have the same number of elements as costsPerVehicle. A name must not be specified more than once. If a vehicle is excluded from costsPerVehicleNames, its cost is zero.
pickupToDeliveryAbsoluteDetourLimit

string (Duration format)

Specifies the maximum absolute detour time compared to the shortest path from pickup to delivery. If specified, it must be nonnegative, and the shipment must contain at least a pickup and a delivery.

For example, let t be the shortest time taken to go from the selected pickup alternative directly to the selected delivery alternative. Then setting pickupToDeliveryAbsoluteDetourLimit enforces:

startTime(delivery) - startTime(pickup) <=
t + pickupToDeliveryAbsoluteDetourLimit

If both relative and absolute limits are specified on the same shipment, the more constraining limit is used for each possible pickup/delivery pair. As of 2017/10, detours are only supported when travel durations do not depend on vehicles.

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

string (Duration format)

Specifies the maximum duration from start of pickup to start of delivery of a shipment. If specified, it must be nonnegative, and the shipment must contain at least a pickup and a delivery. This does not depend on which alternatives are selected for pickup and delivery, nor on vehicle speed. This can be specified alongside maximum detour constraints: the solution will respect both specifications.

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

string

Non-empty string specifying a "type" for this shipment. This feature can be used to define incompatibilities or requirements between shipment_types (see shipmentTypeIncompatibilities and shipmentTypeRequirements in ShipmentModel).

Differs from visitTypes which is specified for a single visit: All pickup/deliveries belonging to the same shipment share the same shipmentType.
label

string

Specifies a label for this shipment. This label is reported in the response in the shipmentLabel of the corresponding ShipmentRoute.Visit.
ignore

boolean

If true, skip this shipment, but don't apply a penaltyCost.

Ignoring a shipment results in a validation error when there are any shipmentTypeRequirements in the model.

Ignoring a shipment that is performed in injectedFirstSolutionRoutes or injectedSolutionConstraint is permitted; the solver removes the related pickup/delivery visits from the performing route. precedenceRules that reference ignored shipments will also be ignored.
demands[]
(deprecated)

object (CapacityQuantity)

Deprecated: Use Shipment.load_demands instead.
penaltyCost

number

If the shipment is not completed, this penalty is added to the overall cost of the routes. A shipment is considered completed if one of its pickup and delivery alternatives is visited. The cost may be expressed in the same unit used for all other cost-related fields in the model and must be positive.

IMPORTANT: If this penalty is not specified, it is considered infinite, i.e. the shipment must be completed.
pickupToDeliveryRelativeDetourLimit

number

Specifies the maximum relative detour time compared to the shortest path from pickup to delivery. If specified, it must be nonnegative, and the shipment must contain at least a pickup and a delivery.

For example, let t be the shortest time taken to go from the selected pickup alternative directly to the selected delivery alternative. Then setting pickupToDeliveryRelativeDetourLimit enforces:

startTime(delivery) - startTime(pickup) <=
std::ceil(t * (1.0 + pickupToDeliveryRelativeDetourLimit))

If both relative and absolute limits are specified on the same shipment, the more constraining limit is used for each possible pickup/delivery pair. As of 2017/10, detours are only supported when travel durations do not depend on vehicles.

VisitRequest

Request for a visit which can be done by a vehicle: it has a geo-location (or two, see below), opening and closing times represented by time windows, and a service duration time (time spent by the vehicle once it has arrived to pickup or drop off goods).

JSON representation 
{
  "arrivalLocation": {
    object (LatLng)
  },
  "arrivalWaypoint": {
    object (Waypoint)
  },
  "departureLocation": {
    object (LatLng)
  },
  "departureWaypoint": {
    object (Waypoint)
  },
  "tags": [
    string
  ],
  "timeWindows": [
    {
      object (TimeWindow)
    }
  ],
  "duration": string,
  "cost": number,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "visitTypes": [
    string
  ],
  "label": string,
  "demands": [
    {
      object (CapacityQuantity)
    }
  ]
}
Fields
arrivalLocation

object (LatLng)

The geo-location where the vehicle arrives when performing this VisitRequest. If the shipment model has duration distance matrices, arrivalLocation must not be specified.
arrivalWaypoint

object (Waypoint)

The waypoint where the vehicle arrives when performing this VisitRequest. If the shipment model has duration distance matrices, arrivalWaypoint must not be specified.
departureLocation

object (LatLng)

The geo-location where the vehicle departs after completing this VisitRequest. Can be omitted if it is the same as arrivalLocation. If the shipment model has duration distance matrices, departureLocation must not be specified.
departureWaypoint

object (Waypoint)

The waypoint where the vehicle departs after completing this VisitRequest. Can be omitted if it is the same as arrivalWaypoint. If the shipment model has duration distance matrices, departureWaypoint must not be specified.
tags[]

string

Specifies tags attached to the visit request. Empty or duplicate strings are not allowed.
timeWindows[]

object (TimeWindow)

Time windows which constrain the arrival time at a visit. Note that a vehicle may depart outside of the arrival time window, i.e. arrival time + duration do not need to be inside a time window. This can result in waiting time if the vehicle arrives before TimeWindow.start_time.

The absence of TimeWindow means that the vehicle can perform this visit at any time.

Time windows must be disjoint, i.e. no time window must overlap with or be adjacent to another, and they must be in increasing order.

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

string (Duration format)

Duration of the visit, i.e. time spent by the vehicle between arrival and departure (to be added to the possible waiting time; see timeWindows).

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

number

Cost to service this visit request on a vehicle route. This can be used to pay different costs for each alternative pickup or delivery of a shipment. This cost must be in the same unit as Shipment.penalty_cost and must not be negative.
loadDemands

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

Load demands of this visit request. This is just like Shipment.load_demands field, except that it only applies to this VisitRequest instead of the whole Shipment. The demands listed here are added to the demands listed in Shipment.load_demands.
visitTypes[]

string

Specifies the types of the visit. This may be used to allocate additional time required for a vehicle to complete this visit (see Vehicle.extra_visit_duration_for_visit_type).

A type can only appear once.
label

string

Specifies a label for this VisitRequest. This label is reported in the response as visitLabel in the corresponding ShipmentRoute.Visit.
demands[]
(deprecated)

object (CapacityQuantity)

Deprecated: Use VisitRequest.load_demands instead.

Methods

create

 Creates a shipment.

delete

 Deletes a shipment.

get

 Gets a shipment.

list

 Lists the shipments within a workspace.

patch

 Updates a shipment.