Trip#
Note
Viewing documentation for the current version v1beta2.
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: PERMISSION_DENIED if the customer ID is not present or the customer does not exist.
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: PERMISSION_DENIED if the customer ID is not present or the offer was not requested by the provided customer.
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: PERMISSION_DENIED if the customer ID is not present or the trip does not belong to the provided customer.
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.
Messages#
Adult#
An adult passenger.
Field |
Type |
Description |
|---|---|---|
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 passenger.
Field |
Type |
Description |
|---|---|---|
wheelchair |
The potential wheelchair of the child. |
|
child_seat |
The potentially required child seat for the child. |
Load#
The requested load for the vehicle.
NamedLocation#
A Location combined with its localized address.
Field |
Type |
Description |
|---|---|---|
location |
The location. |
|
primary_address |
string |
Street name and number. |
secondary_address |
string |
Secondary address line, usually containing zip code and city, might also contain the country. |
primary_poi_name |
string |
The name of a point of interest (e.g. Hamburg Airport). |
secondary_poi_name |
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 |
The possible stops for the pickup. Must not be empty. 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. |
|
dropoff_stops |
The possible stops for the dropoff. Must not be empty. If only one stop is provided, the stop is the dropoff location. If multiple stops are provided, the dropoff location will be chosen later. |
|
pickup_interval |
The time interval in which the customer will be picked up. |
|
dropoff_interval |
The time interval in which the customer will be dropped off. |
|
price |
The price of the offer. |
|
service_class |
string |
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 |
Optional: 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. |
|
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 |
The type of the 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 offered price of a trip.
Field |
Type |
Description |
|---|---|---|
price |
The total price of the trip. Equal to the sum of all price parts. |
|
price_parts |
The price parts that make up the total price. |
PricePart#
One of the price parts that make up the total price of a trip.
Field |
Type |
Description |
|---|---|---|
price |
The price of the part. |
|
name |
string |
The identifier of the part. The identifier is used to distinguish different types of price parts. Part names are configured by the service configuration manager. |
RequestTripOffersRequest#
Requests offers for a trip.
Field |
Type |
Description |
|---|---|---|
origin |
The location where the customer wants to be picked up. |
|
destination |
The location where the customer wants to be dropped off. |
|
load |
The requested load for the vehicle. |
|
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. |
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 |
The number of offers returned 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 |
Location of the stop accessible by a human. |
|
name |
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 |
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 |
The path of the route. |
|
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. |
moia.type.v1.LatLon#
Represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, it must adhere to the WGS84 standard.
Field |
Type |
Description |
|---|---|---|
latitude |
double |
The latitude in degrees. [-90.0, +90.0]. Required |
longitude |
double |
The longitude in degrees. [-180.0, +180.0]. Required |
moia.type.v1.Money#
Represents an amount of money with its currency type.
Field |
Type |
Description |
|---|---|---|
currency_code |
string |
The three-letter currency code defined in ISO 4217. For example US dollars are expressed as “USD”. |
amount |
int64 |
The price amount in the currency’s smallest unit as specified in ISO 4217. For example US dollars are expressed in cents, like 515 for $5.15. |
moia.type.v1.TimeInterval#
Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive).
The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time.
Field |
Type |
Description |
|---|---|---|
start |
google.protobuf.Timestamp |
Optional. Inclusive start of the interval. |
If specified, a Timestamp matching this interval will have to be the same or after the start. | end | google.protobuf.Timestamp | Optional. Exclusive end of the interval.
If specified, a Timestamp matching this interval will have to be before the end.
Enums#
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. |
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. |