Last Mile Fleet Solution is currently available only to select customers. Contact sales to learn more.

REST Resource: providers.tasks

Stay organized with collections Save and categorize content based on your preferences.

Resource: Task

A Task in the Delivery API represents a single action to track. In general, there is a distinction between shipment-related Tasks and break Tasks. A shipment can have multiple Tasks associated with it. For example, there could be one Task for the pickup, and one for the drop-off or transfer. Also, different Tasks for a given shipment can be handled by different vehicles. For example, one vehicle could handle the pickup, driving the shipment to the hub, while another vehicle drives the same shipment from the hub to the drop-off location.

Note: gRPC and REST APIs use different field naming conventions. For example, the Task.journey_sharing_info field in the gRPC API and the DeliveryVehicle.journeySharingInfo field in the REST API refer to the same field.

JSON representation 
{
  "name": string,
  "type": enum (Type),
  "state": enum (State),
  "taskOutcome": enum (TaskOutcome),
  "taskOutcomeTime": string,
  "taskOutcomeLocation": {
    object (LocationInfo)
  },
  "taskOutcomeLocationSource": enum (TaskOutcomeLocationSource),
  "trackingId": string,
  "deliveryVehicleId": string,
  "plannedLocation": {
    object (LocationInfo)
  },
  "taskDuration": string,
  "journeySharingInfo": {
    object (JourneySharingInfo)
  }
}
Fields
name

string

Must be in the format providers/{provider}/tasks/{task}.
type

enum (Type)

Required. Immutable. Defines the type of the Task. For example, a break or shipment.
state

enum (State)

Required. The current execution state of the Task.
taskOutcome

enum (TaskOutcome)

The outcome of the Task.
taskOutcomeTime

string (Timestamp format)

The timestamp that indicates when the Task's outcome was set by the provider.

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

object (LocationInfo)

The location where the Task's outcome was set. This value is updated as part of tasks.patch. If this value isn't explicitly updated by the provider, then Fleet Engine populates it by default with the last known vehicle location (the raw location).
taskOutcomeLocationSource

enum (TaskOutcomeLocationSource)

Indicates where the value of the taskOutcomeLocation came from.
trackingId

string

Immutable. This field facilitates the storing of an ID so you can avoid using a complicated mapping. You cannot set trackingId for Tasks of type UNAVAILABLE and SCHEDULED_STOP. These IDs are subject to the following restrictions:

  • Must be a valid Unicode string.
  • Limited to a maximum length of 64 characters.
  • Normalized according to Unicode Normalization Form C.
  • May not contain any of the following ASCII characters: '/', ':', '?', ',', or '#'.
deliveryVehicleId

string

Output only. The ID of the vehicle that is executing this Task. Delivery Vehicle IDs are subject to the following restrictions:

  • Must be a valid Unicode string.
  • Limited to a maximum length of 64 characters.
  • Normalized according to Unicode Normalization Form C.
  • May not contain any of the following ASCII characters: '/', ':', '?', ',', or '#'.
plannedLocation

object (LocationInfo)

Immutable. The location where the Task will be completed. Optional for UNAVAILABLE Tasks, but required for all other Tasks.
taskDuration

string (Duration format)

Required. Immutable. The time needed to execute a Task at this location.

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

object (JourneySharingInfo)

Output only. Journey sharing-specific fields. Not populated when state is CLOSED.

Type

The type of Task.

Enums
TYPE_UNSPECIFIED Default, the Task type is unknown.
PICKUP A pickup Task is the action taken for picking up a shipment from a customer. Depot or feeder vehicle pickups should use the SCHEDULED_STOP type.
DELIVERY A delivery Task is the action taken for delivering a shipment to an end customer. Depot or feeder vehicle dropoffs should use the SCHEDULED_STOP type.
SCHEDULED_STOP A scheduled stop Task is used for planning purposes. For example, it could represent picking up or dropping off shipments from feeder vehicles or depots. It shouldn't be used for any shipments that are picked up or dropped off from an end customer.
UNAVAILABLE A Task that means the Vehicle is not available for service. For example, this can happen when the driver takes a break, or when the vehicle is being refueled.

State

The state of a Task. This indicates the Tasks's progress.

Enums
STATE_UNSPECIFIED Default. Used for an unspecified or unrecognized Task state.
OPEN Either the Task has not yet been assigned to a delivery vehicle, or the delivery vehicle has not yet passed the Task's assigned vehicle stop.
CLOSED When the vehicle passes the vehicle stop for this Task.

TaskOutcome

The outcome of attempting to execute a Task. When TaskState is closed, TaskOutcome indicates whether it was completed successfully.

Enums
TASK_OUTCOME_UNSPECIFIED The Task outcome before its value is set.
SUCCEEDED The Task completed successfully.
FAILED Either the Task couldn't be completed, or it was cancelled.

TaskOutcomeLocationSource

The identity of the source that populated the taskOutcomeLocation.

Enums
TASK_OUTCOME_LOCATION_SOURCE_UNSPECIFIED The Task outcome before it is set.
PROVIDER The provider-specified the taskOutcomeLocation.
LAST_VEHICLE_LOCATION The provider didn't specify the taskOutcomeLocation, so Fleet Engine used the last known vehicle location.

JourneySharingInfo

Journey sharing specific fields.

JSON representation 
{
  "remainingVehicleJourneySegments": [
    {
      object (VehicleJourneySegment)
    }
  ],
  "lastLocation": {
    object (DeliveryVehicleLocation)
  },
  "lastLocationSnappable": boolean
}
Fields
remainingVehicleJourneySegments[]

object (VehicleJourneySegment)

Tracking information for the stops that the assigned vehicle will make before it completes this Task. Note that this list can contain stops from other tasks.

The first segment, Task.journey_sharing_info.remaining_vehicle_journey_segments[0] (gRPC) or Task.journeySharingInfo.remainingVehicleJourneySegments[0] (REST), contains route information from the driver's last known location to the upcoming VehicleStop. Current route information usually comes from the driver app, except for some cases noted in the documentation for DeliveryVehicle.current_route_segment. The other segments in Task.journey_sharing_info.remaining_vehicle_journey_segments (gRPC) or Task.journeySharingInfo.remainingVehicleJourneySegments (REST) are populated by Fleet Engine. They provide route information between the remaining VehicleStops.
lastLocation

object (DeliveryVehicleLocation)

Indicates the vehicle's last reported location of the assigned vehicle.
lastLocationSnappable

boolean

Indicates whether the vehicle's lastLocation can be snapped to the currentRouteSegment. This value is False if either lastLocation or currentRouteSegment don't exist. This value is computed by Fleet Engine. Updates from clients are ignored.

Methods

batchCreate

 Creates and returns a batch of new Task objects.

create

 Creates and returns a new Task object.

get

 Gets information about a Task.

list

 Gets all Tasks that meet the specified filtering criteria.

patch

 Updates Task data.
Gets all Tasks with a particular tracking_id.