Lifecycle of a Trip

The journey of a Customer starts with the need for a Trip to bring them from the requested origin to the requested destination. Using the Ridepooling API, we can request Offers for Trips based on the Customer’s travel needs and order one for them.

Requesting Offers for a Trip

First, we request Offers for a potential Trip. This Offer request includes the origin and destination ( using NamedLocation), the rider(s) or object(s) that will be part of the Trip (using Load) and finally either the preferred time of departure or the preferred time of arrival ( using google.protobuf.Timestamp).

The following example details a RequestTripOfferRequest for a single adult (no wheelchair needed) wishing to go from Point A to Point B with a departure at 13:30 on the 05.08.2024.

grpcurl \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Customer-Id: ${CUSTOMER_ID}" \
  -import-path ./protos/ \
  -proto "moia/ridepooling/trip/v1beta2/trip.proto" \
  -d "{\"origin\":{\"location\":{\"latitude\":53.6344823,\"longitude\":10.0555216},\"primary_address\":\"Stüberedder14\",\"secondary_address\":\"22337Hamburg\",\"primary_poi_name\":\"PointA\",\"secondary_poi_name\":\"Hamburg,Germany\"},\"destination\":{\"location\":{\"latitude\":53.6342303,\"longitude\":10.0741517},\"primary_address\":\"Eckerkamp38\",\"secondary_address\":\"22391Hamburg,\",\"primary_poi_name\":\"PointB\",\"secondary_poi_name\":\"Hamburg,Germany\"},\"load\":[{\"adult\":{}}],\"departure_time\":\"$(date '+%Y-%m-%dT%H:%M:%SZ')\"}" \
  ridepooling-api.int.eu-central-1.moia-group.io:443 moia.ridepooling.trip.v1beta2.TripService/RequestTripOffers

To receive Offers based on a preferred arrival time, we simply replace the field departure_time in the payload with arrival_time:

{
  ...

  "arrival_time": "2024-08-05T13:30:00Z"
}

To receive Offers for multiple Riders or with physical objects, we add multiple Loads in the payload. Here we are requesting Offers for one adult with a wheelchair and one child with a booster seat:

{
  ...

  "load": [
    {
      "adult":
        {
          "wheelchair": "WHEELCHAIR_NEEDED"
        }
    },
    {
      "child":
        {
          "child_seat": "CHILD_SEAT_BOOSTER"
        }
    }
  ]
}

We receive a response of type RequestTripOffersResponse which contains a list of Offer. The list is not ordered or ranked in any particular way. The list of Offers may include Offers for varying Service Classes and may also contain multiple options per Service Class. Note that an Offer will respect the Customer’s request details unless the Offer’s violation field is populated.

Ordering an Offer

Given the list of Offers, we now select the preferred Offer for the Customer and order it. To do so we need to call the OrderTrip method with a payload of type OrderTripRequest which contains the token of the Offer you want to order.

The token is a simple non-human readable string.

# export OFFER_TOKEN="<replace with token>"

grpcurl \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Customer-Id: ${CUSTOMER_ID}" \
  -import-path ./protos/ \
  -proto "moia/ridepooling/trip/v1beta2/trip.proto" \
  -d "{\"offer_token\":\"$OFFER_TOKEN\"}" \
  ridepooling-api.int.eu-central-1.moia-group.io:443 moia.ridepooling.trip.v1beta2.TripService/OrderTrip

The response of type OrderTripResponse contains a single field trip_id. At this point in time our order has been processed and the status of our trip is set to STATUS_ORDERED. We will use the trip_id from the response to make other calls to the API to get more details on our trip and follow the many state updates it will go through throughout its lifecycle.

{
  "trip_id": "7bc0118b-748e-4c13-bc5e-bb2164f04927"
}

Cancelling a Trip as a Customer

Given an ongoing Trip, the Customer can cancel it if they decide not to take the trip as long they haven’t yet been picked up. To do so we need to call the CancelTripAsCustomer method on behalf of the Customer with a payload of type CancelTripAsCustomerRequest. The payload contains the trip_id of the Trip we want to cancel and the Customer’s ID must be set in the request header.

# export TRIP_ID="<replace with trip id>"

grpcurl \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Customer-Id: ${CUSTOMER_ID}" \
  -import-path ./protos/ \
  -proto "moia/ridepooling/trip/v1beta2/trip.proto" \
  -d "{\"trip_id\":\"$TRIP_ID\"}" \
  ridepooling-api.int.eu-central-1.moia-group.io:443 moia.ridepooling.trip.v1beta2.TripService/CancelTripAsCustomer

The response of type CancelTripAsCustomerResponse is an empty message which acknowledges the successful cancellation.

Cancelling a Trip as an Integrator

Given an ongoing Trip, we can cancel it as long as the Customer hasn’t yet been picked up. This RPC should only be called for technical reasons, such as a payment failure. If the Customer wants to step back from the Trip, we should call the CancelTripAsCustomer RPC instead. To do so we need to call the CancelTripAsIntegrator method with a payload of type CancelTripAsIntegratorRequest. The payload contains the trip_id of the Trip we want to cancel.

# export TRIP_ID="<replace with trip id>"

grpcurl \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -import-path ./protos/ \
  -proto "moia/ridepooling/trip/v1beta2/trip.proto" \
  -d "{\"trip_id\":\"$TRIP_ID\"}" \
  ridepooling-api.int.eu-central-1.moia-group.io:443 moia.ridepooling.trip.v1beta2.TripService/CancelTripAsIntegrator

The response of type CancelTripAsIntegratorResponse is an empty message which acknowledges the successful cancellation.