Trip State

Note

Viewing documentation for the current version v1.

To switch to an older version use the following links:

• v1beta5

The required Protobuf definitions can be downloaded here:

• moia/trip/state/v1/trip_state.proto

• moia/type/v1/latlon.proto

• moia/type/v1/latlon_with_heading.proto

• moia/type/v1/money.proto

• moia/type/v1/time_interval.proto

TripStateService

The TripStateService provides end-to-end trip lifecycle management, including request, retrieval, ordering and cancellation.

RequestTripOffers

rpc RequestTripOffers(RequestTripOffersRequest) returns (RequestTripOffersResponse)

Requests offers for a trip.

This is a customer-scoped endpoint. The ID of the customer on behalf of whom the operation is requested needs to be provided in the request header ("Customer-Id: <your-customer-id>").

Fails with PERMISSION_DENIED with the following reasons:

• CUSTOMER_ID_MISSING if the customer ID is not present in the request header.

• CUSTOMER_UNAUTHENTICATED if the provided customer ID does not exist.

• SERVICE_CLASSES_NOT_ALLOWED if the customer is not allowed to use any of the configured service classes. This error reason usually indicates that the customer is missing a required customer flag.

Fails with FAILED_PRECONDITION with the following reasons:

• FLEET_SATURATED if the fleet is saturated at the requested time and no offer can be proposed.

• NO_STOPS_NEAR_DESTINATION if there are no active stops close to the selected destination.

• NO_STOPS_NEAR_ORIGIN if there are no active stops close to the selected origin.

• NO_STOPS_NEAR_ORIGIN_AND_DESTINATION if there are no active stops close to the selected origin and destination.

• ONGOING_TRIP if the customer has a scheduled or ongoing trip that is conflicting with the selected time.

Fails with INVALID_ARGUMENT with the following reasons:

• INVALID_LOAD if there are no vehicles configured with the necessary capacity to fulfill the requested load.

• OUT_OF_SERVICE_AREA if the requested origin and/or destination for the trip are outside of all configured service areas. You may list available service areas by calling the ServiceAreaService.

• OUT_OF_SERVICE_HOURS if the requested times for the trip would at any point coincide with the service being out of the scheduled service hours. You may list the service hours by calling the ServiceAreaService.

• TIME_TOO_FAR_FROM_NOW if the requested times for the trip are too far into the past or too far into the future.

• TRIP_TOO_SHORT if the requested trip is too short for a ride.

OrderTrip

rpc OrderTrip(OrderTripRequest) returns (OrderTripResponse)

Orders a trip.

This is a customer-scoped endpoint. The ID of the customer on behalf of whom the operation is requested needs to be provided in the request header ("Customer-Id: <your-customer-id>").

This operation is idempotent.

Only order a single offer from a given RequestTripOffersResponse. If you later call OrderTrip with a different offer_token from that same service area and RequestTripOffersResponse, the call will succeed but will return the trip_id of the first created trip and will not modify that trip.

Fails with PERMISSION_DENIED with the following reasons:

• CUSTOMER_ID_MISSING if the customer ID is not present in the request header.

• CUSTOMER_UNAUTHORIZED if the offer was not requested by the provided customer ID (or the customer does not exist).

Fails with INVALID_ARGUMENT with the reason INVALID_OFFER if the requested offer can not be processed.

Fails with FAILED_PRECONDITION with the following reasons:

• OFFER_EXPIRED if the trip is ordered too late after the offer was requested. Re-request offers to order a trip.

• ONGOING_TRIP if there is an ongoing trip for the customer on behalf of whom the offer was requested.

• FLEET_SATURATED if the fleet is saturated at the requested time and no order can be processed.

CancelTripAsCustomer

rpc CancelTripAsCustomer(CancelTripAsCustomerRequest) returns (CancelTripAsCustomerResponse)

Cancels a trip because the customer decided to step back from taking the trip. To further specify the customer’s intent for cancellation, the customer may provide feedback using the FeedbackService.

This is a customer-scoped endpoint. The ID of the customer on behalf of whom the operation is requested needs to be provided in the request header ("Customer-Id: <your-customer-id>").

This operation is idempotent.

Fails with PERMISSION_DENIED with the following reasons:

• CUSTOMER_ID_MISSING if the customer ID is not present in the request header.

• CUSTOMER_UNAUTHENTICATED if the provided customer ID does not exist.

• CUSTOMER_UNAUTHORIZED if the trip does not belong to the provided customer ID.

Fails with NOT_FOUND with the reason TRIP_NOT_FOUND if there is no trip for the requested trip ID.

Fails with FAILED_PRECONDITION with the reason TRIP_NOT_CANCELLABLE if the trip is not in a state where a cancellation is possible.

CancelTripAsIntegrator

rpc CancelTripAsIntegrator(CancelTripAsIntegratorRequest) returns (CancelTripAsIntegratorResponse)

Cancels a trip because of a technical reason (e.g. payment failure). This action is initiated by the integrator and not the customer. In case of the customer canceling the trip, please use the RPC CancelTripAsCustomer.

This operation is idempotent.

Fails with NOT_FOUND with the reason TRIP_NOT_FOUND if there is no trip for the requested trip ID.

Fails with FAILED_PRECONDITION with the reason TRIP_NOT_CANCELLABLE if the trip is not in a state where a cancellation is possible.

GetTrip

rpc GetTrip(GetTripRequest) returns (GetTripResponse)

Gets the details of a trip.

Fails with NOT_FOUND with the reason TRIP_NOT_FOUND if there is no trip for the requested trip ID.

Messages

Adult

An adult.

Field	Type	Description
wheelchair	Wheelchair	The potential wheelchair of the adult.

CancelTripAsCustomerRequest

Cancels a trip on behalf of the customer. Moves the trip to the cancelled status.

Field	Type	Description
trip_id	string	The ID of the trip to request the cancellation for.

CancelTripAsCustomerResponse

Response to a successfully received CancelTripAsCustomerRequest.

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

CancelTripAsIntegratorRequest

Cancels a trip due to technical reasons. Moves the trip to the cancelled status.

Field	Type	Description
trip_id	string	The ID of the trip to request the cancellation for.

CancelTripAsIntegratorResponse

Response to a successfully received CancelTripAsIntegratorRequest.

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

Child

A child.

Field	Type	Description
wheelchair	Wheelchair	The potential wheelchair of the child.
child_seat	ChildSeat	The potentially required child seat for the child.

GetTripRequest

Gets the details of a trip.

Field	Type	Description
trip_id	string	The ID of the trip to get the details of.

GetTripResponse

Returns the details of a trip.

Field	Type	Description
trip	Trip	The details of the trip.

Load

The requested load for the vehicle.

Field	Type	Description
oneof load_type.adult	Adult	An adult.
oneof load_type.child	Child	A child.

NamedLocation

A Location combined with its localized address.

Field	Type	Description
location	moia.type.v1.LatLon	The location.
primary_address	optional string	Street name and number.
secondary_address	optional string	Secondary address line, usually containing zip code and city, might also contain the country.
primary_poi_name	optional string	The name of a point of interest (e.g., “Hamburg Airport”).
secondary_poi_name	optional string	Additional information for a point of interest (e.g., “Hamburg, Germany”).

Offer

An offer for a trip.

Field	Type	Description
token	string	A token that identifies the offer.
service_area_id	string	The service area the offer was created for and in which the trip would be executed if ordered.
service_class_id	string	The ID of the service class of the offer. The service class is used to distinguish different types of offers. Service classes are configured by the service configuration manager.
pickup_stops	repeated Stop	The possible stops for the pickup. If only one stop is provided, the stop is the pickup location. If multiple stops are provided, the pickup location will be chosen after ordering the trip. Must not be empty.
dropoff_stops	repeated Stop	The possible stops for the dropoff. If only one stop is provided, the stop is the dropoff location. If multiple stops are provided, the dropoff location will be chosen later. Must not be empty.
pickup_interval	moia.type.v1.TimeInterval	The time interval in which the customer will be picked up.
dropoff_interval	moia.type.v1.TimeInterval	The time interval in which the customer will be dropped off.
price	Price	The price of the offer.
tags	repeated string	The tags include more information about the offer. Tag strings are expected to be stable but may change. May be empty.

OrderTripRequest

Orders a trip.

Field	Type	Description
offer_token	string	The token of the offer that the customer wants to order, which is part of the RequestTripOffersResponse.

OrderTripResponse

Signals that the order was processed successfully. The trip may still be rejected after ordering.

Field	Type	Description
trip_id	string	The ID of the ordered trip. The trip ID is used to get the trip details and updates.

Price

The price. Must use the same currency for gross amount, net amount and all price parts.

Field	Type	Description
gross_amount	moia.type.v1.Money	The gross amount of the trip. Equal to the sum of all price parts.
net_amount	moia.type.v1.Money	The net amount of the trip.
tax_rate	float	The tax rate (e.g. 0.19 for 19%).
price_parts	repeated PricePart	The price parts. The sum of all price parts equals the gross amount. Must not be empty.

PricePart

A price part.

Field	Type	Description
name	string	The name of the price part. Price part names are configured by the service configuration manager.
gross_amount	moia.type.v1.Money	The gross amount of the price part. A negative amount may be used to describe a price discount.

RequestTripOffersRequest

Requests offers for a trip.

Field	Type	Description
origin	NamedLocation	The location where the customer wants to be picked up.
destination	NamedLocation	The location where the customer wants to be dropped off.
load	repeated Load	The requested load for the vehicle. Must not be empty.
oneof time.departure_time	google.protobuf.Timestamp	The earliest time when the customer wants to be picked up.
oneof time.arrival_time	google.protobuf.Timestamp	The latest time when the customer wants to arrive at the destination.
approach_speed	ApproachSpeed	The approach speed of the riders. Used to calculate the Stop.Route.approach_duration for pickup and dropoff stops.
visual_impairment_support	bool	Whether the riders need support because of visual impairment.

RequestTripOffersResponse

Returns a list of offers for a trip request. No vehicle is reserved yet. The longer a customer waits before ordering a trip, the lower the chances of finding a vehicle.

Field	Type	Description
offers	repeated Offer	The list of offers in no specific order. Must not be empty. The number of offers is configured by the service configuration manager.

Stop

A stop is a location where a vehicle can pick up or dropoff a customer.

Field	Type	Description
location	moia.type.v1.LatLon	Location of the stop accessible by a human.
name	map Stop.NameEntry	Human-readable name of the stop in all supported languages. The key is an IETF BCP-47 language tag: https://en.wikipedia.org/wiki/IETF_language_tag For example ‘en’ or ‘de’. The value is the localized string.
route	Stop.Route	The route from the selected origin to this stop or from this stop to the selected destination.

Stop.NameEntry

Field	Type	Description
key	string	none
value	string	none

Stop.Route

The route.

Field	Type	Description
path	repeated moia.type.v1.LatLon	The path of the route. Must not be empty.
approach_duration	google.protobuf.Duration	Estimated duration for the customer to approach to or from this stop.
approach_meters	int32	Distance to or from this stop in meters.

Trip

A trip.

Field	Type	Description
id	string	The ID of the trip. The value must not be shown to customers.
name	string	Human-readable resource name of the trip. May be communicated to customers. May be used by customers to contact customer support.
customer_id	string	The ID of the customer who ordered the trip.
service_area_id	string	The ID of the service area in which the trip is executed.
service_class_id	string	The ID of the service class of the trip. Service classes are configured by the service configuration manager.
origin	NamedLocation	The location where the customer wants to be picked up.
destination	NamedLocation	The location where the customer wants to be dropped off.
pickup_stops	repeated Stop	The possible stops where the customer will be picked up. If only one stop is provided, the stop is the pickup location. If multiple stops are provided, the pickup location will be chosen later. May be updated. Must not be empty.
dropoff_stops	repeated Stop	The possible stops where the customer will be dropped off. If only one stop is provided, the stop is the dropoff location. If multiple stops are provided, the dropoff location will be chosen later. May be updated. Must not be empty.
pickup_interval	moia.type.v1.TimeInterval	The time interval in which the customer will be picked up. May be updated.
dropoff_interval	moia.type.v1.TimeInterval	The time interval in which the customer will be dropped off. May be updated.
order_time	google.protobuf.Timestamp	The time when the trip was ordered.
pickup_time	google.protobuf.Timestamp	The pickup time of the trip. Before pickup, this is the estimated pickup time. After the pickup already happened, this is the actual time of the pickup.
dropoff_time	google.protobuf.Timestamp	The dropoff time of the trip. Before dropoff, this is the estimated dropoff time. After the dropoff already happened, this is the actual time of the dropoff.
price	Price	The price of the trip.
load	repeated Load	The requested load of the vehicle. Must not be empty.
vehicle	optional Vehicle	The vehicle that is assigned to the trip. The field is set once a vehicle is assigned to the trip. May change if a different vehicle is assigned to the trip.
approach_speed	ApproachSpeed	The approach speed of the riders. Used to calculate the Stop.Route.approach_duration for pickup and dropoff stops.
visual_impairment_support	bool	Whether the riders need support because of visual impairment. Fields 20-29 are reserved for future additional Trip fields.
oneof state.ordered	Trip.StateOrdered	The trip is ordered.
oneof state.in_fulfillment	Trip.StateInFulfillment	The trip is in fulfillment.
oneof state.fulfilled	Trip.StateFulfilled	The trip was fulfilled successfully.
oneof state.not_fulfilled	Trip.StateNotFulfilled	The trip was not fulfilled successfully.

Trip.StateFulfilled

The state of a trip that was fulfilled successfully. A trip has been fulfilled once the rider was dropped off by the vehicle at the dropoff stop location.

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

Trip.StateInFulfillment

The in fulfillment state.

Field	Type	Description
phase	Trip.StateInFulfillment.Phase	The current phase of the trip in fulfillment.

Trip.StateNotFulfilled

The state of a trip that was not fulfilled successfully.

Field	Type	Description
reason	Trip.StateNotFulfilled.Reason	The reason why the trip was not fulfilled successfully.

Trip.StateOrdered

The ordered state.

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

Vehicle

A vehicle.

Field	Type	Description
name	string	The name of the vehicle.
location	optional moia.type.v1.LatLonWithHeading	The last known oriented geographic location of the vehicle. Not available after the trip has entered a final state.

Enums

ApproachSpeed

Defines the approach speed of riders towards a destination.

Name	Number	Description
APPROACH_SPEED_UNSPECIFIED	0	The default in case the approach speed is not set. Should not be used. Will be treated as APPROACH_SPEED_MEDIUM by the server.
APPROACH_SPEED_SLOW	1	The riders are approaching more slowly. More time will be allocated for a given approach distance.
APPROACH_SPEED_MEDIUM	2	The riders are approaching at a medium speed.

ChildSeat

Defines the child seat requirement. Seat specifications according to UN ECE Regulation 44/04. Not all child seats are available in all vehicles.

Name	Number	Description
CHILD_SEAT_UNSPECIFIED	0	The default child seat in case the child seat is not set. Should not be used. Will be treated as CHILD_SEAT_NOT_NEEDED by the server.
CHILD_SEAT_NOT_NEEDED	1	No child seat is needed.
CHILD_SEAT_BACKWARDS	2	A baby seat is needed.
CHILD_SEAT_FORWARDS	3	A child seat is needed.
CHILD_SEAT_BOOSTER	4	A booster seat is needed.

Trip.StateInFulfillment.Phase

The possible phases of a trip in fulfillment. The trip is not guaranteed to transition through all phases.

The trips will transition through the phases in this order: PHASE_ACCEPTED -> PHASE_PICKED_UP.

The trips served by vehicles which require authentication via the BoardingAuthenticationService will transition through the phases in this order: PHASE_ACCEPTED -> PHASE_READY_FOR_BOARDING_AUTHENTICATION -> PHASE_BOARDING_AUTHENTICATION_COMPLETED -> PHASE_PICKED_UP.

Name	Number	Description
PHASE_UNSPECIFIED	0	The default in case the detail is not set. Should not be used.
PHASE_ACCEPTED	1	The trip was accepted by the system.
PHASE_READY_FOR_BOARDING_AUTHENTICATION	2	The vehicle has reached the pickup stop location and is ready for boarding authentication. This phase is only relevant for trips served by vehicles which require authentication via the BoardingAuthenticationService.
PHASE_BOARDING_AUTHENTICATION_COMPLETED	3	Authentication for boarding the vehicle has been completed. This phase is only relevant for trips served by vehicles which require authentication via the BoardingAuthenticationService.
PHASE_PICKED_UP	4	The customer was picked up.

Trip.StateNotFulfilled.Reason

Defines the reason a trip can end with when not fulfilled successfully.

Name	Number	Description
REASON_UNSPECIFIED	0	The default in case the status is not set. Should not be used.
REASON_REJECTED	1	The trip was rejected by the system before being in fulfillment.
REASON_TERMINATED	2	The trip was terminated because of a problem with the service. If the rider still desires to travel to the trip’s destination, another trip has to be ordered.
REASON_NO_SHOW	3	The customer did not show up for pickup.
REASON_CANCELLED_AS_CUSTOMER	4	The trip was cancelled by the customer. This can also happen before the trip is in fulfillment.
REASON_CANCELLED_AS_INTEGRATOR	5	The trip was cancelled by the integrator. This can also happen before the trip is in fulfillment.

Wheelchair

Defines wheelchair usage and space requirement. Not all vehicles have wheelchair spaces.

Name	Number	Description
WHEELCHAIR_UNSPECIFIED	0	The default in case the wheelchair usage is not set. Should not be used. Will be treated as WHEELCHAIR_NOT_NEEDED by the server.
WHEELCHAIR_NOT_NEEDED	1	A wheelchair space is not needed.
WHEELCHAIR_NEEDED	2	A wheelchair space is needed.