Trip

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#

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: ”). Fails with PERMISSION_DENIED if the customer ID is not present or the customer does not exist.

OrderTrip#

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: ”). Fails with PERMISSION_DENIED if the customer ID is not present or the offer was not requested by the provided customer.

CancelTripAsCustomer#

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: ”). Fails with PERMISSION_DENIED if the customer ID is not present or the trip does not belong to the provided customer.

CancelTripAsIntegrator#

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.

GetTrip#

Gets the details of a trip.

Messages#

Adult#

An adult passenger.

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

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

oneof load_type.child

Child

A child passenger.

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.

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 offered price of a trip.

Field

Type

Description

price

moia.type.v1.Money

The total price of the trip. Equal to the sum of all price parts.

price_parts

repeated PricePart

The price parts that make up the total price. Must not be empty.

PricePart#

One of the price parts that make up the total price of a trip.

Field

Type

Description

price

moia.type.v1.Money

The price of the part. A negative amount may be used to describe a price discount.

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

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.

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

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.

customer_id

string

The ID of the customer who ordered the trip.

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 actual pickup time (ATA) of the trip. It is only set if the pickup already happened.

dropoff_time (optional)

google.protobuf.Timestamp

The actual dropoff time (ATA) of the trip. It is only set if the dropoff already happened.

load

repeated Load

The requested load of the vehicle. Must not be empty.

service_class_id

string

The ID of the service class of the trip. Service classes are configured by the service configuration manager.

vehicle_id (optional)

string

The ID of the vehicle that is assigned to the trip. The ID is set once the trip is assigned to a vehicle and may change if a different vehicle is assigned to the trip. Will not change once the vehicle is fixed, which happens shortly before pickup.

state

Trip.State

The state of the trip.

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.

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.