Fleet State

Contents

Fleet State#

Note

Viewing documentation for the current version v1beta4.

The required Protobuf definitions can be downloaded here:

FleetStateService#

FleetStateService provides access and management capabilities for fleets and their vehicles. It allows API users to retrieve information about their fleets, including details about the vehicles within those fleets and their current state. Furthermore, it allows issuing updates and commands to the vehicles, such as updating the mission, and operational commands.

ListFleets#

List all the fleets that an API user has access to.

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • NOT_FOUND: if a page token was not found, provides ErrorInfo in error details

  • INTERNAL: internal error occurred

GetFleet#

Get a particular fleet by id.

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • NOT_FOUND: if the requested fleet was not found, provides ResourceInfo in details

  • INTERNAL: internal error occurred

ListVehicles#

List all vehicles which are contained in a fleet.

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • NOT_FOUND: if the page token was not found, provides ErrorInfo in error details

  • INTERNAL: internal error occurred

GetVehicle#

Get a particular vehicle by id.

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • NOT_FOUND: if the requested vehicle was not found, provides ResourceInfo in details

  • INTERNAL: internal error occurred

SubscribeToVehicleTelemetryMovement#

Stream the vehicle’s movement telemetry.

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • INTERNAL: internal error occurred

UpdateVehicleMission#

Update the mission of a vehicle. The call returns the new mission on success. Can take a few seconds to complete, call with a sufficient timeout.

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • INTERNAL: internal error occurred

SubscribeToFleetMissionEvents#

Stream events related to missions of vehicles in a fleet

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • INTERNAL: internal error occurred

PollFleetMissionEvents#

Poll events related to missions of vehicles in a fleet

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • INTERNAL: internal error occurred

SendBoardingPreparationSuccessful#

SendBoardingPreparationSuccessful will signal the vehicle that the passenger is ready to board. This is overriding authentication mechanisms on the vehicle and signals that the authentication for a particular ride can be considered successful. As a result of this the door of the vehicle opens if it is not already open.

Potential Errors:

  • INVALID_ARGUMENT: if the incoming request failed to validate against the buf annotations

  • INTERNAL: internal error occurred

Messages#

Fleet#

A Fleet is a group of vehicles associated with an Operational Area.

Field

Type

Description

id

string

none

description

string

none

operational_area_id

string

The Id of the Operational Area (OA) the Fleet belongs to.

GetFleetRequest#

Field

Type

Description

fleet_id

string

The Id of the fleet to retrieve.

GetFleetResponse#

Field

Type

Description

fleet

Fleet

none

GetVehicleRequest#

Field

Type

Description

vehicle_id

string

The Id of the vehicle to retrieve.

GetVehicleResponse#

Field

Type

Description

vehicle

Vehicle

none

ListFleetsRequest#

Field

Type

Description

page_size

int32

The maximum size of the response list. If the page_size is unset, the API chooses a default.

page_token

string

The next_page_token returned by a previous ListFleets operation to advance to the next page of results. If page_token is unset, the first page of results is returned.

ListFleetsResponse#

Contains a list of fleets accessible to the API user, along with a token for pagination.

Field

Type

Description

fleets

repeated Fleet

none

next_page_token

string

The next_page_token can be used to retrieve the next page of results in a subsequent ListFleets call. An unset next_page_token indicates that the result represents the last page.

ListVehiclesRequest#

Field

Type

Description

fleet_id

string

The Id of the fleet to retrieve.

page_size

int32

The maximum size of the response list. If the page_size is unset, the API chooses a default.

page_token

string

The next_page_token returned by a previous ListVehicles operation to advance to the next page of results. If page_token is unset, the first page of results is returned.

ListVehiclesResponse#

Contains a list of vehicles accessible to the API user, along with a token for pagination.

Field

Type

Description

vehicles

repeated Vehicle

none

next_page_token

string

The next_page_token can be used to retrieve the next page of results in a subsequent ListVehicles call. An unset next_page_token indicates that the result represents the last page.

Location#

Field

Type

Description

latitude

double

none

longitude

double

none

MissionEvent#

A MissionEvent is an event that occurs during the execution of a vehicle mission.

Field

Type

Description

vehicle_id

string

Id of the vehicle associated with the mission event.

timestamp

google.protobuf.Timestamp

Timestamp indicating when the mission event occurred.

oneof type.picked_up

MissionEvent.PickedUp

none

oneof type.dropped_off

MissionEvent.DroppedOff

none

oneof type.not_shown_up

MissionEvent.NotShownUp

none

oneof type.boarding_preparation_started

MissionEvent.BoardingPreparationStarted

none

oneof type.boarding_preparation_completed

MissionEvent.BoardingPreparationCompleted

none

oneof type.waypoint_completed

MissionEvent.WaypointCompleted

none

oneof type.waypoint_reached

MissionEvent.WaypointReached

none

oneof type.route_updated

MissionEvent.VehicleRouteUpdated

none

MissionEvent.BoardingPreparationCompleted#

  • Prerequisite: Passenger and Vehicle are at the pick-up location indicated by a Waypoint Reached event and Boarding Preparation has started indicated by a Boarding Preparation Started event.

  • Cause: Boarding Preparation is completed successfully.

  • Effect: The door opens.

Field

Type

Description

ride_id

string

Id of the ride for which boarding preparation has been completed.

MissionEvent.BoardingPreparationStarted#

  • Prerequisite: Vehicle is at the pick-up location as indicated by a Waypoint Reached event.

  • Cause: Vehicle started the boarding preparation process.

  • Effect: Vehicle is waiting for boarding preparation to be completed.

Field

Type

Description

ride_id

string

Id of the ride for which boarding preparation has started.

MissionEvent.DroppedOff#

  • Prerequisite: Vehicle is at the drop-off location indicated by a Waypoint Reached event. The vehicle door is opened.

  • Cause: Passenger has exited the Vehicle.

  • Effect: Dropped Off action is completed. If all actions at the Waypoint are completed, the Vehicle is ready to drive to next Waypoint.

Field

Type

Description

ride_id

string

Id of the ride associated with the drop-off event.

MissionEvent.NotShownUp#

  • Prerequisite: Vehicle is at the pick-up location indicated by a Waypoint Reached event.

  • Cause: Passenger did not show up at the pick-up location.

  • Effect: Actions with the same ride_id are discarded. Vehicle leaves without picking up the passenger.

Field

Type

Description

ride_id

string

Id of the ride associated with the no-show event.

MissionEvent.PickedUp#

  • Prerequisite: Passenger is at the pick-up location and boarding preparation is completed as indicated by a Boarding Preparation Completed event.

  • Cause: Passenger has entered the vehicle and presence is confirmed.

  • Effect: Picked Up action is completed. If all actions at the Waypoint are completed, the Vehicle is ready to drive to next Waypoint with Passenger onboard.

Field

Type

Description

ride_id

string

Id of the ride associated with the pick-up event.

MissionEvent.VehicleRouteUpdated#

  • Prerequisite: Vehicle has completed all Waypoint Actions as indicated by a Waypoint Completed event.

  • Cause: Vehicle route has been updated.

  • Effect: Following this new route, Vehicle continues to the next Waypoint location.

Field

Type

Description

route

Route

none

MissionEvent.WaypointCompleted#

  • Prerequisite: Vehicle is at the Waypoint location indicated by a Waypoint Reached event.

  • Cause: All Waypoint Actions have been completed or cancelled.

  • Effect: Vehicle leaves the Waypoint location.

Field

Type

Description

waypoint_id

string

Id of the waypoint that has been reached.

MissionEvent.WaypointReached#

  • Prerequisite: None

  • Cause: Vehicle is at Waypoint location.

  • Effect: Vehicle can start completing the Waypoint Actions.

Field

Type

Description

waypoint_id

string

Id of the waypoint that has been completed.

NamedLocation#

Field

Type

Description

location

Location

The location of the waypoint.

heading

double

The horizontal direction in degrees, measured clockwise from north.

labels

map NamedLocation.LabelsEntry

Human-readable labels for the location by language code (ISO 639-1 - two-letter language codes).

NamedLocation.LabelsEntry#

Field

Type

Description

key

string

none

value

string

none

PollFleetMissionEventsRequest#

Field

Type

Description

fleet_id

string

Id of fleet for which mission events should be polled

last_message_id

string

The Id of the last message received in the poll, use this to read the events from the last received message.

PollFleetMissionEventsResponse#

If no last_message_id was provided in the PollFleetMissionEventsRequest, the response will not contain any events. Only the message_id of the last message in the stream will be returned, which can be used to continue reading the stream from the last received message.

Field

Type

Description

events

repeated MissionEvent

none

message_id

string

The Id of this message, use this as last_message_id in the next request to continue reading.

Route#

Field

Type

Description

eta

google.protobuf.Timestamp

none

length_meters

int32

The physical length of the route in meters.

geometry

repeated Location

A polyline that describes the route.

SendBoardingPreparationSuccessfulRequest#

Field

Type

Description

vehicle_id

string

The Id of the vehicle to start the boarding preparation for.

ride_id

string

The ride Id associated with the boarding process.

SendBoardingPreparationSuccessfulResponse#

This message is an empty message and has no fields. The JSON representation is {}.

SubscribeToFleetMissionEventsRequest#

Stream the events of missions of vehicles in the fleet. If last_message_id is omitted only new events will be streamed. It is very important that you omit last_message_id only for the first call to StreamVehicleMissionEvents. Later last_message_id should be set to the message_id of the last received item, otherwise you could miss all the entries that are added in between.

Field

Type

Description

fleet_id

string

The Id of fleet for which mission events should be streamed

last_message_id

string

The Id of the last message received in the stream, use this to continue reading the stream from the last received message.

SubscribeToFleetMissionEventsResponse#

If no last_message_id was provided in the StreamVehicleMissionEventsRequest the stream will immediately send out a response after being established with an empty event and the Id of the last message in the stream. In all other cases both an event and a message_id will be provided.

Field

Type

Description

event

optional MissionEvent

none

message_id

string

none

SubscribeToVehicleTelemetryMovementRequest#

Stream the vehicle movement.

Field

Type

Description

vehicle_id

string

The Id of the vehicle to retrieve.

SubscribeToVehicleTelemetryMovementResponse#

Field

Type

Description

vehicle_movement

Vehicle.Telemetry.Movement

none

TimeRange#

Field

Type

Description

start_time

google.protobuf.Timestamp

Start of the time range

end_time

google.protobuf.Timestamp

End of the time range

UpdateVehicleMissionRequest#

Field

Type

Description

vehicle_id

string

The Id of the vehicle to update the mission for.

waypoints

repeated UpdateVehicleMissionRequest.Waypoint

The waypoints for the new mission.

previous_mission_id

string

The Id of the previous mission. This is used to ensure that the mission is only updated if the previous mission is still the current mission. If this vehicle has never received a mission, this can be left empty.

UpdateVehicleMissionRequest.Waypoint#

Field

Type

Description

actions

repeated UpdateVehicleMissionRequest.Waypoint.Action

The actions performed at the waypoint.

location

NamedLocation

The location of the waypoint.

UpdateVehicleMissionRequest.Waypoint.Action#

Field

Type

Description

oneof action_type.pickup

Vehicle.Mission.Waypoint.Action.Pickup

none

oneof action_type.dropoff

Vehicle.Mission.Waypoint.Action.Dropoff

none

oneof action_type.rebalancing

Vehicle.Mission.Waypoint.Action.Rebalancing

none

UpdateVehicleMissionResponse#

Field

Type

Description

new_vehicle_mission

Vehicle.Mission

The new mission of the vehicle.

Vehicle#

Field

Type

Description

id

string

none

vin

string

The Vehicle Identification Number of this vehicle.

license_plate

string

none

label

string

A label which is visible on the outside of the vehicle to help the rider to identify the correct vehicle.

telemetry

Vehicle.Telemetry

The last known location of the vehicle.

configuration

Vehicle.Configuration

Information regarding the type of the vehicle.

mission

Vehicle.Mission

The mission contains the current waypoints assigned to this vehicle. Each waypoint contains a list of actions to perform at the waypoint location.

status

Vehicle.Status

none

Vehicle.Configuration#

Field

Type

Description

self_driving

bool

none

Vehicle.Mission#

A Mission is defined as a set of Waypoints for a specific Vehicle to complete in a predefined order. Each Waypoint has context data (e.g. timestamps / location) and one or more Waypoint Actions (i.e., passenger pickup). Missions can contain anything from zero to tens of ordered Waypoints.

Field

Type

Description

id

string

The Id used for versioning of Mission

waypoints

repeated Vehicle.Mission.Waypoint

The ordered list of waypoints which the vehicle approaches one after another.

Vehicle.Mission.Waypoint#

Field

Type

Description

actions

repeated Vehicle.Mission.Waypoint.Action

The actions performed at the waypoint.

location

NamedLocation

The location of the waypoint.

id

string

Id of the waypoint

Vehicle.Mission.Waypoint.Action#

Field

Type

Description

oneof action_type.pickup

Vehicle.Mission.Waypoint.Action.Pickup

none

oneof action_type.dropoff

Vehicle.Mission.Waypoint.Action.Dropoff

none

oneof action_type.rebalancing

Vehicle.Mission.Waypoint.Action.Rebalancing

none

oneof action_type.service_break

Vehicle.Mission.Waypoint.Action.ServiceBreak

none

Vehicle.Mission.Waypoint.Action.Dropoff#

Drop off passengers at the waypoint location.

Field

Type

Description

ride_id

string

none

promised_arrival_time

TimeRange

The vehicle is requested to arrive at the drop-off location within this time range

Vehicle.Mission.Waypoint.Action.Pickup#

Pick up passengers at the waypoint location.

Field

Type

Description

ride_id

string

none

promised_arrival_time

TimeRange

The vehicle is requested to arrive at the pick-up location within this time range

Vehicle.Mission.Waypoint.Action.Rebalancing#

The vehicle is sent to another destination in the Operational Area e.g. for spatial distribution of the fleet.

This message is an empty message and has no fields. The JSON representation is {}.

Vehicle.Mission.Waypoint.Action.ServiceBreak#

The vehicle is not available for regular service e.g. Driver break

Field

Type

Description

promised_arrival_time

TimeRange

The vehicle is requested to arrive at the break location within this time range

Vehicle.Status#

Field

Type

Description

ready_for_new_rides

bool

Flag indicating if the vehicle is ready to receive and process new rides.

online

bool

Flag indicating if the vehicle is connected and has a recent location.

Vehicle.Telemetry#

Field

Type

Description

movement

Vehicle.Telemetry.Movement

none

Vehicle.Telemetry.Movement#

Field

Type

Description

location

Location

none

heading

double

Direction of the stop (0.0-360.0°, 0.0° = facing north , 180.0° = south)

speed_meters_per_second

double

Speed in m/s

timestamp

google.protobuf.Timestamp

Timestamp of the telemetry (required)

VehicleConfiguration#

Field

Type

Description

is_self_driving

bool

none

Enums#

Contents