Trip

Trip#

Note

Viewing documentation for the current version v1beta4.

The required Protobuf definitions can be downloaded here:

TripService#

The TripService offers all functionality required to request and order trips.

RequestTripOffers#

rpc RequestTripOffers(RequestTripOffersRequest) 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.

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

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 following reasons:

INVALID_OFFER if the requested offer can not be processed.
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.

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.

CancelTripAsCustomer#

rpc CancelTripAsCustomer(CancelTripAsCustomerRequest) 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>").

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 trip does not belong to the provided customer or the customer does not exist.

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

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

ListBoardingAuthenticationMethods#

rpc ListBoardingAuthenticationMethods(ListBoardingAuthenticationMethodsRequest) ListBoardingAuthenticationMethodsResponse

Lists boarding authentication methods available on the vehicle assigned to the trip. Only relevant for autonomous vehicles. Returns an empty list if the assigned vehicle is not ready for boarding yet.

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 trip does not belong to the provided customer or the customer does not exist.

Fails with INVALID_ARGUMENT with the following reasons:

INVALID_PAGE_SIZE if the page_size is less than zero.
INVALID_PAGE_TOKEN if the page_token does not match previous requests.

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

AuthenticateForBoarding#

rpc AuthenticateForBoarding(AuthenticateForBoardingRequest) AuthenticateForBoardingResponse

Authenticates the customer for boarding the vehicle. Only relevant for autonomous vehicles and if authentication is handled via API.

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 trip does not belong to the provided customer or the customer does not exist.

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_STATE_INVALID if the vehicle has not yet arrived at the pickup stop.

Messages#

Adult#

An adult.

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

ApiBoardingAuthentication#

The boarding authentication method where a token is displayed on the vehicle. The customer authenticates by sending the token via the Ridepooling API using the AuthenticateForBoarding RPC.

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

AuthenticateForBoardingRequest#

Authenticates the customer for boarding an autonomous vehicle.

Field	Type	Description
trip_id	string	The ID of the trip the customer wants to authenticate for.
token	string	The boarding authentication token provided on the vehicle.

AuthenticateForBoardingResponse#

Response to a successful boarding authentication request.

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

BoardingAuthenticationMethod#

A method for authenticating when boarding an autonomous vehicle.

Field	Type	Description
oneof boarding_authentication_method.api_boarding_authentication	ApiBoardingAuthentication	API boarding authentication is always available as a fallback boarding authentication method.

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.

ListBoardingAuthenticationMethodsRequest#

Lists boarding authentication methods available on the vehicle assigned to the trip. Only relevant for autonomous vehicles.

Field	Type	Description
trip_id	string	The ID of the trip for which to list the boarding authentication methods.
page_size (optional)	int32	The maximum number of boarding authentication methods to return. The service may return fewer than this value. If unspecified or set to zero, at most 50 boarding authentication methods will be returned. The maximum value is 100; values above 100 will be coerced to 100. Negative values won’t be accepted.
page_token (optional)	string	A page token, received from a previous `ListBoardingAuthenticationMethods` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListBoardingAuthenticationMethods` must match the call that provided the page token.

ListBoardingAuthenticationMethodsResponse#

Returns boarding authentication methods available on the vehicle assigned to the trip.

Field	Type	Description
boarding_authentication_methods	repeated BoardingAuthenticationMethod	List of boarding authentication methods from which one needs to be chosen to authenticate for boarding.
next_page_token (optional)	string	A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

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.
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.
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.
service_area_id	string	The service area the offer was created for and in which the trip would be executed if ordered.
violations	repeated Offer.Violation	If the offer violates request parameters, the violations and the reason for each violation are provided. Only existing if we find a good enough alternative offer. If no alternative is found, the API returns an error with the reason. May be empty. The field is deprecated and will not be included in the non-beta v1 release.
tags	string	The tags include more information about the offer. Tag strings are expected to be stable but may change. May be empty.

Offer.Violation#

Explains the violation of the offer from the request parameters.

Field	Type	Description
type	Offer.Violation.Type	The type of the violation.
reason	Offer.Violation.Reason	The reason for the violation.

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.

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. 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 (optional)	google.protobuf.Timestamp	The pickup time of the trip. Before `Trip.State.STATE_PICKED_UP`, this is the estimated pickup time. After the pickup already happened, this is the actual time of the pickup.
dropoff_time (optional)	google.protobuf.Timestamp	The dropoff time of the trip. Before `Trip.State.STATE_DROPPED_OFF`, 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)	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.
state	Trip.State	The state of the trip.
approach_speed	ApproachSpeed	The approach speed of the riders. Used to calculate the `Stop.Route.approach_duration` for pickup and dropoff stops.

Vehicle#

A vehicle.

Field	Type	Description
name	string	The name of the vehicle.
location (optional)	optional moia.type.v1.LatLon	The last known location of the vehicle. Not available after the trip has entered a final state.
heading (optional)	double	The heading the vehicle is facing. 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	An child seat is needed.
CHILD_SEAT_BOOSTER	4	A booster seat is needed.

Offer.Violation.Reason#

The reason for the violation.

Name	Number	Description
REASON_UNSPECIFIED	0	The default reason in case the reason is not set. Should not be used.
REASON_OUT_OF_SERVICE_HOURS	1	The pickup time or dropoff time are outside of the service hours or the service hours end in between. We may ensure some time before service hours start or after service hours end.
REASON_CONFLICTING_TRIP	2	The requested time is conflicting with another trip of the customer. We may ensure some time between trips to avoid conflicts.
REASON_TOO_EARLY	3	The requested time would result in a pickup in the past.
REASON_TOO_LATE	4	The requested time is too far in the future for the system to allow trips.
REASON_FLEET_SATURATED	5	The fleet is saturated at the requested time and possibly no vehicle is available.
REASON_NO_PICKUP_STOPS_NEARBY	6	No pickup stops are nearby the requested origin location.
REASON_NO_DROPOFF_STOPS_NEARBY	7	No dropoff stops are nearby the requested destination location.

Offer.Violation.Type#

The type of violation from the request.

Name	Number	Description
TYPE_UNSPECIFIED	0	The default violation type in case the violation is not set. Should not be used.
TYPE_PICKUP_TIME	1	The pickup time violates the requested time.
TYPE_DROPOFF_TIME	2	The dropoff time violates the requested time.
TYPE_PICKUP_APPROACH	3	The approach distance to the pickup stop violates the approach distance defined by the service configuration manager.
TYPE_DROPOFF_APPROACH	4	The approach distance from the dropoff stop violates the approach distance defined by the service configuration manager.

Trip.State#

The state of a trip.

Name	Number	Description
STATE_UNSPECIFIED	0	The default state in case the state is not set. Should not be used.
STATE_ORDERED	1	The trip is ordered.
STATE_ACCEPTED	2	The trip is accepted.
STATE_REJECTED	3	The trip couldn’t be accepted. A possible reason is insufficient supply.
STATE_CANCELLED	4	The trip is cancelled by the customer or integrator.
STATE_TERMINATED	5	The trip was terminated because of a problem with the service. If the customer still desires to travel to the trip’s destination, another trip has to be ordered.
STATE_NO_SHOW	6	The customer did not show up for pickup.
STATE_PICKED_UP	7	The customer was picked up by the vehicle.
STATE_DROPPED_OFF	8	The customer was dropped off by the vehicle.

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.

Trip

Contents

Trip#

TripService#

RequestTripOffers#

OrderTrip#

CancelTripAsCustomer#

CancelTripAsIntegrator#

GetTrip#

ListBoardingAuthenticationMethods#

AuthenticateForBoarding#

Messages#

Adult#

ApiBoardingAuthentication#

AuthenticateForBoardingRequest#

AuthenticateForBoardingResponse#

BoardingAuthenticationMethod#

CancelTripAsCustomerRequest#

CancelTripAsCustomerResponse#

CancelTripAsIntegratorRequest#

CancelTripAsIntegratorResponse#

Child#

GetTripRequest#

GetTripResponse#

ListBoardingAuthenticationMethodsRequest#

ListBoardingAuthenticationMethodsResponse#

Load#

NamedLocation#

Offer#

Offer.Violation#

OrderTripRequest#

OrderTripResponse#

Price#

PricePart#

RequestTripOffersRequest#

RequestTripOffersResponse#

Stop#

Stop.NameEntry#

Stop.Route#

Trip#

Vehicle#

Enums#

ApproachSpeed#

ChildSeat#

Offer.Violation.Reason#

Offer.Violation.Type#

Trip.State#

Wheelchair#