# REST Resource: providers.tasks

- [Resource: Task](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#Task)
  - [JSON representation](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#Task.SCHEMA_REPRESENTATION)
- [Type](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#Type)
- [TaskOutcomeLocationSource](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#TaskOutcomeLocationSource)
- [JourneySharingInfo](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#JourneySharingInfo)
  - [JSON representation](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#JourneySharingInfo.SCHEMA_REPRESENTATION)
- [TaskTrackingViewConfig](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#TaskTrackingViewConfig)
  - [JSON representation](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#TaskTrackingViewConfig.SCHEMA_REPRESENTATION)
- [VisibilityOption](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption)
  - [JSON representation](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption.SCHEMA_REPRESENTATION)
- [Methods](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#METHODS_SUMMARY)

## 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 `Task.journeySharingInfo` field in the REST API refer to the same field.

| JSON representation |
|---|
| ``` { "name": string, "type": enum (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#Type`), "state": enum (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/State`), "taskOutcome": enum (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/TaskOutcome`), "taskOutcomeTime": string, "taskOutcomeLocation": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo`) }, "taskOutcomeLocationSource": enum (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#TaskOutcomeLocationSource`), "trackingId": string, "deliveryVehicleId": string, "plannedLocation": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo`) }, "taskDuration": string, "targetTimeWindow": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/TimeWindow`) }, "journeySharingInfo": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#JourneySharingInfo`) }, "taskTrackingViewConfig": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#TaskTrackingViewConfig`) }, "attributes": [ { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/TaskAttribute`) } ] } ``` |

| Fields ||
|---|---|
| `name` | `string` Must be in the format `providers/{provider}/tasks/{task}`. |
| `type` | ``enum (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#Type`)`` Required. Immutable. Defines the type of the Task. For example, a break or shipment. |
| `state` | ``enum (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/State`)`` Required. The current execution state of the Task. |
| `taskOutcome` | ``enum (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/TaskOutcome`)`` The outcome of the Task. |
| `taskOutcomeTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The timestamp that indicates when the `Task`'s outcome was set by the provider. Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `taskOutcomeLocation` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/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 (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#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](http://www.unicode.org/reports/tr15/). - 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](http://www.unicode.org/reports/tr15/). - May not contain any of the following ASCII characters: '/', ':', '?', ',', or '#'. |
| `plannedLocation` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo`)`` Immutable. The location where the Task will be completed. Optional for `UNAVAILABLE` Tasks, but required for all other Tasks. |
| `taskDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#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"`. |
| `targetTimeWindow` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/TimeWindow`)`` The time window during which the task should be completed. |
| `journeySharingInfo` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#JourneySharingInfo`)`` Output only. Journey sharing-specific fields. Not populated when state is `CLOSED`. |
| `taskTrackingViewConfig` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#TaskTrackingViewConfig`)`` The configuration for task tracking that specifies which data elements are visible to the end users under what circumstances. |
| `attributes[]` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/TaskAttribute`)`` A list of custom Task attributes. Each attribute must have a unique key. |

## 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. |

## 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 (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/VehicleJourneySegment`) } ], "lastLocation": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/DeliveryVehicleLocation`) }, "lastLocationSnappable": boolean } ``` |

| Fields ||
|---|---|
| `remainingVehicleJourneySegments[]` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/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 `https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.deliveryVehicles#DeliveryVehicle.FIELDS.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 (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/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. |

## TaskTrackingViewConfig

The configuration message that defines when a data element of a Task should be visible to the end users.

| JSON representation |
|---|
| ``` { "routePolylinePointsVisibility": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`) }, "estimatedArrivalTimeVisibility": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`) }, "estimatedTaskCompletionTimeVisibility": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`) }, "remainingDrivingDistanceVisibility": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`) }, "remainingStopCountVisibility": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`) }, "vehicleLocationVisibility": { object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`) } } ``` |

| Fields ||
|---|---|
| `routePolylinePointsVisibility` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`)`` The field that specifies when route polyline points can be visible. If this field is not specified, the project level default visibility configuration for this data will be used. |
| `estimatedArrivalTimeVisibility` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`)`` The field that specifies when estimated arrival time can be visible. If this field is not specified, the project level default visibility configuration for this data will be used. |
| `estimatedTaskCompletionTimeVisibility` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`)`` The field that specifies when estimated task completion time can be visible. If this field is not specified, the project level default visibility configuration for this data will be used. |
| `remainingDrivingDistanceVisibility` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`)`` The field that specifies when remaining driving distance can be visible. If this field is not specified, the project level default visibility configuration for this data will be used. |
| `remainingStopCountVisibility` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`)`` The field that specifies when remaining stop count can be visible. If this field is not specified, the project level default visibility configuration for this data will be used. |
| `vehicleLocationVisibility` | ``object (`https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks#VisibilityOption`)`` The field that specifies when vehicle location can be visible. If this field is not specified, the project level default visibility configuration for this data will be used. |

## VisibilityOption

The option message that defines when a data element should be visible to the end users.

| JSON representation |
|---|
| ``` { // Union field `visibility_option` can be only one of the following: "remainingStopCountThreshold": integer, "durationUntilEstimatedArrivalTimeThreshold": string, "remainingDrivingDistanceMetersThreshold": integer, "always": boolean, "never": boolean // End of list of possible types for union field `visibility_option`. } ``` |

| Fields ||
|---|---|
| Union field `visibility_option`. The specific visibility option chosen. `visibility_option` can be only one of the following: ||
| `remainingStopCountThreshold` | `integer` This data element is visible to the end users if the remaining stop count \<= remainingStopCountThreshold. |
| `durationUntilEstimatedArrivalTimeThreshold` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` This data element is visible to the end users if the ETA to the stop \<= durationUntilEstimatedArrivalTimeThreshold. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `remainingDrivingDistanceMetersThreshold` | `integer` This data element is visible to the end users if the remaining driving distance in meters \<= remainingDrivingDistanceMetersThreshold. |
| `always` | `boolean` If set to true, this data element is always visible to the end users with no thresholds. This field cannot be set to false. |
| `never` | `boolean` If set to true, this data element is always hidden from the end users with no thresholds. This field cannot be set to false. |

| ## Methods ||
|---|---|
| ### `https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/batchCreate` | Creates and returns a batch of new `Task` objects. |
| ### `https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/create` | Creates and returns a new `Task` object. |
| ### `https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/delete` | Deletes a single Task. |
| ### `https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/get` | Gets information about a `Task`. |
| ### `https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/list` | Gets all `Task`s that meet the specified filtering criteria. |
| ### `https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/patch` | Updates `Task` data. |