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

Id of Fleet.

description

string

Description of Fleet.

operational_area_id

string

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

GetFleetRequest#

The request to get a Fleet by Id.

Field

Type

Description

fleet_id

string

The Id of the fleet to retrieve.

GetFleetResponse#

The response containing the requested Fleet.

Field

Type

Description

fleet

Fleet

Fleet with requested Id.

GetVehicleRequest#

The request to get a Vehicle by Id.

Field

Type

Description

vehicle_id

string

The Id of the vehicle to retrieve.

GetVehicleResponse#

Reponse containing requested Vehicle.

Field

Type

Description

vehicle

Vehicle

Requested Vehicle.

ListFleetsRequest#

The request to list Fleets.

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

List of fleets.

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#

The request to list Vehicles of a specific Fleet.

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

List of Vehicles.

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#

A physical location characterized by the geographic coordinates.

Field

Type

Description

latitude

double

Latitude coordinates.

longitude

double

Longitude coordinates.

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

Event indicating that a passenger was picked up.

oneof type.dropped_off

MissionEvent.DroppedOff

Event indicating that a passenger was dropped off.

oneof type.not_shown_up

MissionEvent.NotShownUp

Event indicating that a passenger didn’t show up.

oneof type.boarding_preparation_started

MissionEvent.BoardingPreparationStarted

Event indicating that the boarding preparation has started for a Ride.

oneof type.boarding_preparation_completed

MissionEvent.BoardingPreparationCompleted

Event indicating that the boarding preparation was completed for a Ride.

oneof type.waypoint_completed

MissionEvent.WaypointCompleted

Event indicating that a Vehicle has completed a Waypoint.

oneof type.waypoint_reached

MissionEvent.WaypointReached

Event indicating that a Vehicle has reached a Waypoint.

oneof type.route_updated

MissionEvent.VehicleRouteUpdated

Event indicating that the Route of a Vehicle got updated.

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

Route of vehicle to the next Waypoint.

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

NamedLocation#

Named location represents a physical location with multi-lingual names.

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#

Request to poll mission events for a fleet with given Id. If last_message_id is provided, all events since then are requested. which occurred since last poll ifor a fleet with given Id. occured since last poll indicated by last_message_id``. If last_message_id` is omitted, the request polls any mission events occuring during the request deadline.

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

List of Mission Events which were received since last poll.

message_id

string

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

Route#

Route represents the path a vehicle can take with an ETA and length of route.

Field

Type

Description

eta

google.protobuf.Timestamp

Estimated time of arrival for this route.

length_meters

int32

The physical length of the route in meters.

geometry

repeated Location

A polyline that describes the route.

SendBoardingPreparationSuccessfulRequest#

Request to SendBoardingPreparationSuccessful.

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#

The response to SendBoardingPreparationSuccessful. Empty response indicating that command was perceived.

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

New incoming Mission Event. Event is empty on initial subscribe.

message_id

string

The Id of this message, use this as last_message_id when reconnecting to continue reading.

SubscribeToVehicleTelemetryMovementRequest#

Stream the vehicle movement.

Field

Type

Description

vehicle_id

string

The Id of the vehicle to retrieve.

SubscribeToVehicleTelemetryMovementResponse#

Returns the vehicle movement as a stream. Only sends updates if the vehicle is online.

Field

Type

Description

vehicle_movement

Vehicle.Telemetry.Movement

Updated movement of Vehicle

TimeRange#

TimeRange represents a time interval, encoded as start_time (inclusive) and end_time (exclusive).

The start must be less than the end.

Field

Type

Description

start_time

google.protobuf.Timestamp

Start of the time range

end_time

google.protobuf.Timestamp

End of the time range

UpdateVehicleMissionRequest#

The request to update a Vehicle’s Mission to the given new Mission.

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#

A Waypoint is a particular stopping place that a Vehicle is requested to go to. Waypoints consists of both a location and Waypoint Actions that are requested to occur at the 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#

Waypoint Action represents an activity that is required at a specific Waypoint.

Field

Type

Description

oneof action_type.pickup

Vehicle.Mission.Waypoint.Action.Pickup

Action to pick up a passenger

oneof action_type.dropoff

Vehicle.Mission.Waypoint.Action.Dropoff

Action to drop off a passenger

oneof action_type.rebalancing

Vehicle.Mission.Waypoint.Action.Rebalancing

Action to send vehicle for rebalancing inside the Operational Area.

UpdateVehicleMissionResponse#

The response containing the updated Vehicle’s mission.

Field

Type

Description

new_vehicle_mission

Vehicle.Mission

The updated mission of the Vehicle.

Vehicle#

A Vehicle is a single entity of a Fleet, which is expected to move within the OA completing its current Mission.

Field

Type

Description

id

string

Id of Vehicle.

vin

string

The Vehicle Identification Number of this vehicle.

license_plate

string

License plate of Vehicle.

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

The current status of the Vehicle.

Vehicle.Configuration#

Configuration contains any information regarding the type of a Vehicle.

Field

Type

Description

self_driving

bool

Flag indicating if a vehicle is self driving or not.

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#

A Waypoint is a particular stopping place that a Vehicle is requested to go to. Waypoints consists of both a location and Waypoint Actions that are requested to occur at the Waypoint.

Field

Type

Description

actions

repeated Vehicle.Mission.Waypoint.Action

The actions requested to occur at the waypoint.

location

NamedLocation

The location of the waypoint.

id

string

Id of the waypoint

Vehicle.Mission.Waypoint.Action#

Waypoint Action represents an activity that is required at a specific Waypoint.

Field

Type

Description

oneof action_type.pickup

Vehicle.Mission.Waypoint.Action.Pickup

Pickup Action.

oneof action_type.dropoff

Vehicle.Mission.Waypoint.Action.Dropoff

Dropoff Action.

oneof action_type.rebalancing

Vehicle.Mission.Waypoint.Action.Rebalancing

Rebalancing Action.

oneof action_type.service_break

Vehicle.Mission.Waypoint.Action.ServiceBreak

Service Break Action.

Vehicle.Mission.Waypoint.Action.Dropoff#

Drop off passengers at the waypoint location.

Field

Type

Description

ride_id

string

Id of the Ride for which drop off will be executed.

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

Id of the Ride for which pick up is executed.

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#

Status represents a collection of relevant flags for

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#

Telemetry contains information about a Vehicle’s telemetry data.

Field

Type

Description

movement

Vehicle.Telemetry.Movement

Movement of a vehicle with coordinates

Vehicle.Telemetry.Movement#

Movement represents a Vehicle’s movement with coordinates and movement-related attributes.

Field

Type

Description

location

Location

Location of the movement.

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#

VehicleConfiguration contains information about relevant vehicle configuration.

Field

Type

Description

is_self_driving

bool

Flag indicating if a vehicle is self driving or not.

Enums#

Contents