REST Resource: projects.locations.workspaces.optimizers

Resource: Optimizer

The optimizer that will run optimizations based on all vehicles and shipments within the workspace. Each optimization is triggered by a client call. When the optimizer runs an optimization, it will construct an OptimizeToursRequest behind the scenes with the most up-to-date entity information and other constraints, and generate a solution. The corresponding OptimizeToursRequest for each solution can be retrieved.

JSON representation 
{
  "name": string,
  "displayName": string,
  "modelSpec": {
    object (ModelSpec)
  },
  "optimizeToursSpec": {
    object (OptimizeToursSpec)
  },
  "filters": {
    object (Filters)
  }
}
Fields
name

string

The resource name of the optimizer. Format: projects/{project}/locations/{location}/workspaces/{workspace}/Optimizers/{optimizer}
displayName

string

The display name of the optimizer. It can be up to 63 characters long and use UTF-8 characters.
modelSpec

object (ModelSpec)

The model spec that is used to formulate all ShipmentModels in the optimizations run by this optimizer.
optimizeToursSpec

object (OptimizeToursSpec)

Spec used to configure the OptimizeToursRequest constructed by this optimizer.
filters

object (Filters)

Filters applied to an optimizer which are used as conditions to select a subset of entities to run the optimization.

ModelSpec

Spec that is used for providing global and relational costs and constraints for all optimizations conducted by this optimizer. The fields match their corresponding fields in ShipmentModel.

JSON representation 
{
  "globalStartTime": string,
  "globalEndTime": string,
  "globalDurationCostPerHour": number,
  "transitionAttributes": [
    {
      object (TransitionAttributes)
    }
  ],
  "shipmentTypeIncompatibilities": [
    {
      object (ShipmentTypeIncompatibility)
    }
  ],
  "shipmentTypeRequirements": [
    {
      object (ShipmentTypeRequirement)
    }
  ],
  "precedenceRules": [
    {
      object (PrecedenceRule)
    }
  ],
  "maxActiveVehicles": integer
}
Fields
globalStartTime

string (Timestamp format)

Global start and end time of the model: no times outside of this range can be considered valid.

The model's time span must be less than a year, i.e. the globalEndTime and the globalStartTime must be within 31536000 seconds of each other.

When using cost_per_*hour fields, you might want to set this window to a smaller interval to increase performance (eg. if you model a single day, you should set the global time limits to that day). If unset, 00:00:00 UTC, January 1, 1970 (i.e. seconds: 0, nanos: 0) is used as default.

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".
globalEndTime

string (Timestamp format)

If unset, 00:00:00 UTC, January 1, 1971 (i.e. seconds: 31536000, nanos: 0) is used as default.

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".
globalDurationCostPerHour

number

The "global duration" of the overall plan is the difference between the earliest effective start time and the latest effective end time of all vehicles. Users can assign a cost per hour to be used during the global duration period to try and optimize for earliest job completion, for example. This cost must be in the same unit as Shipment.penalty_cost.
transitionAttributes[]

object (TransitionAttributes)

Transition attributes added to the model.
shipmentTypeIncompatibilities[]

object (ShipmentTypeIncompatibility)

Sets of incompatible shipment_types (see ShipmentTypeIncompatibility).
shipmentTypeRequirements[]

object (ShipmentTypeRequirement)

Sets of shipmentType requirements (see ShipmentTypeRequirement).
precedenceRules[]

object (PrecedenceRule)

Set of precedence rules which must be enforced in the model.
maxActiveVehicles

integer

Constrains the maximum number of active vehicles. A vehicle is active if its route performs at least one shipment. This can be used to limit the number of routes in the case where there are fewer drivers than vehicles and that the fleet of vehicles is heterogeneous. The optimization will then select the best subset of vehicles to use. Must be strictly positive.

TransitionAttributes

Specifies attributes of transitions between two consecutive visits on a route. Several TransitionAttributes may apply to the same transition: in that case, all extra costs add up and the strictest constraint or limit applies (following natural "AND" semantics).

JSON representation 
{
  "srcTag": string,
  "excludedSrcTag": string,
  "dstTag": string,
  "excludedDstTag": string,
  "cost": number,
  "costPerKilometer": number,
  "distanceLimit": {
    object (DistanceLimit)
  },
  "delay": string
}
Fields
srcTag

string

Tags defining the set of (src->dst) transitions these attributes apply to.

A source visit or vehicle start matches iff its VisitRequest.tags or Vehicle.start_tags either contains srcTag or does not contain excludedSrcTag (depending on which of these two fields is non-empty).
excludedSrcTag

string

See srcTag. Exactly one of srcTag and excludedSrcTag must be non-empty.
dstTag

string

A destination visit or vehicle end matches iff its VisitRequest.tags or Vehicle.end_tags either contains dstTag or does not contain excludedDstTag (depending on which of these two fields is non-empty).
excludedDstTag

string

See dstTag. Exactly one of dstTag and excludedDstTag must be non-empty.
cost

number

Specifies a cost for performing this transition. This is in the same unit as all other costs in the model and must not be negative. It is applied on top of all other existing costs.
costPerKilometer

number

Specifies a cost per kilometer applied to the distance traveled while performing this transition. It adds up to any Vehicle.cost_per_kilometer specified on vehicles.
distanceLimit

object (DistanceLimit)

Specifies a limit on the distance traveled while performing this transition.

As of 2021/06, only soft limits are supported.
delay

string (Duration format)

Specifies a delay incurred when performing this transition.

This delay always occurs after finishing the source visit and before starting the destination visit.

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

ShipmentTypeIncompatibility

Specifies incompatibilties between shipments depending on their shipmentType. The appearance of incompatible shipments on the same route is restricted based on the incompatibility mode.

JSON representation 
{
  "types": [
    string
  ],
  "incompatibilityMode": enum (IncompatibilityMode)
}
Fields
types[]

string

List of incompatible types. Two shipments having different shipment_types among those listed are "incompatible".
incompatibilityMode

enum (IncompatibilityMode)

Mode applied to the incompatibility.

IncompatibilityMode

Modes defining how the appearance of incompatible shipments are restricted on the same route.

Enums
INCOMPATIBILITY_MODE_UNSPECIFIED Unspecified incompatibility mode. This value should never be used.
NOT_PERFORMED_BY_SAME_VEHICLE In this mode, two shipments with incompatible types can never share the same vehicle.
NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY

For two shipments with incompatible types with the NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY incompatibility mode:

  • If both are pickups only (no deliveries) or deliveries only (no pickups), they cannot share the same vehicle at all.
  • If one of the shipments has a delivery and the other a pickup, the two shipments can share the same vehicle iff the former shipment is delivered before the latter is picked up.

ShipmentTypeRequirement

Specifies requirements between shipments based on their shipmentType. The specifics of the requirement are defined by the requirement mode.

JSON representation 
{
  "requiredShipmentTypeAlternatives": [
    string
  ],
  "dependentShipmentTypes": [
    string
  ],
  "requirementMode": enum (RequirementMode)
}
Fields
requiredShipmentTypeAlternatives[]

string

List of alternative shipment types required by the dependentShipmentTypes.
dependentShipmentTypes[]

string

All shipments with a type in the dependentShipmentTypes field require at least one shipment of type requiredShipmentTypeAlternatives to be visited on the same route.

NOTE: Chains of requirements such that a shipmentType depends on itself are not allowed.
requirementMode

enum (RequirementMode)

Mode applied to the requirement.

RequirementMode

Modes defining the appearance of dependent shipments on a route.

Enums
REQUIREMENT_MODE_UNSPECIFIED Unspecified requirement mode. This value should never be used.
PERFORMED_BY_SAME_VEHICLE In this mode, all "dependent" shipments must share the same vehicle as at least one of their "required" shipments.
IN_SAME_VEHICLE_AT_PICKUP_TIME

With the IN_SAME_VEHICLE_AT_PICKUP_TIME mode, all "dependent" shipments need to have at least one "required" shipment on their vehicle at the time of their pickup.

A "dependent" shipment pickup must therefore have either:

  • A delivery-only "required" shipment delivered on the route after, or
  • A "required" shipment picked up on the route before it, and if the "required" shipment has a delivery, this delivery must be performed after the "dependent" shipment's pickup.
IN_SAME_VEHICLE_AT_DELIVERY_TIME Same as before, except the "dependent" shipments need to have a "required" shipment on their vehicle at the time of their delivery.

PrecedenceRule

A precedence rule between two events (each event is the pickup or the delivery of a shipment): the "second" event has to start at least offsetDuration after "first" has started.

Several precedences can refer to the same (or related) events, e.g., "pickup of B happens after delivery of A" and "pickup of C happens after pickup of B".

Furthermore, precedences only apply when both shipments are performed and are otherwise ignored.

JSON representation 
{
  "firstIsDelivery": boolean,
  "secondIsDelivery": boolean,
  "offsetDuration": string,
  "firstIndex": integer,
  "secondIndex": integer
}
Fields
firstIsDelivery

boolean

Indicates if the "first" event is a delivery.
secondIsDelivery

boolean

Indicates if the "second" event is a delivery.
offsetDuration

string (Duration format)

The offset between the "first" and "second" event. It can be negative.

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

integer

Shipment index of the "first" event. This field must be specified.
secondIndex

integer

Shipment index of the "second" event. This field must be specified.

OptimizeToursSpec

Spec used to configure the OptimizeToursRequest by the optimizer every time it runs an optimization. The fields matches their corresponding fields in OptimizeToursRequest.

JSON representation 
{
  "timeout": string,
  "searchMode": enum (SearchMode),
  "considerRoadTraffic": boolean,
  "populatePolylines": boolean,
  "populateTransitionPolylines": boolean,
  "allowLargeDeadlineDespiteInterruptionRisk": boolean,
  "useGeodesicDistances": boolean,
  "geodesicMetersPerSecond": number
}
Fields
timeout

string (Duration format)

If this timeout is set, the server will generate a solution (if possible) before the timeout has elapsed.

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

enum (SearchMode)

Search mode used to solve the request.
considerRoadTraffic

boolean

Consider traffic estimation in calculating ShipmentRoute fields Transition.travel_duration, Visit.start_time, and vehicleEndTime; in setting the ShipmentRoute.has_traffic_infeasibilities field, and in calculating the OptimizeToursResponse.total_cost field.
populatePolylines

boolean

If true, polylines will be populated in response ShipmentRoutes.
populateTransitionPolylines

boolean

If true, polylines will be populated in response ShipmentRoute.transitions. Note that in this case, the polylines will also be populated in the deprecated travelSteps.
allowLargeDeadlineDespiteInterruptionRisk

boolean

If this is set, then the request can have a deadline (see https://grpc.io/blog/deadlines) of up to 60 minutes. Otherwise, the maximum deadline is only 30 minutes. Note that long-lived requests have a significantly larger (but still small) risk of interruption.
useGeodesicDistances

boolean

If true, travel distances will be computed using geodesic distances instead of Google Maps distances, and travel times will be computed using geodesic distances with a speed defined by geodesicMetersPerSecond.
geodesicMetersPerSecond

number

When useGeodesicDistances is true, this field must be set and defines the speed applied to compute travel times. Its value must be at least 1.0 meters/seconds.

SearchMode

Mode defining the behavior of the search, trading off latency versus solution quality. In all modes, the global request deadline is enforced.

Enums
SEARCH_MODE_UNSPECIFIED Unspecified search mode, equivalent to RETURN_FAST.
RETURN_FAST Stop the search after finding the first good solution.
CONSUME_ALL_AVAILABLE_TIME Spend all the available time to search for better solutions.

Filters

Filter expressions that match a subset of the entities to optimize. For more information about filter syntax, see https://google.aip.dev/160.

JSON representation 
{
  "shipmentFilter": string,
  "vehicleFilter": string
}
Fields
shipmentFilter

string

Filter expression that matches a subset of the shipments to optimize.
vehicleFilter

string

Filter expression that matches a subset of the vehicles to optimize.

Methods

create

 Creates an optimizer .

delete

 Deletes an optimizer.

get

 Gets an optimizer.

list

 Lists the optimizers within a workspace.

patch

 Updates an optimizer.

run

 Run the optimizer to generate a solution based on updated entities (e.g.