API Usage

This guide assumes you set up a client and are authenticated to the Ridepooling API. If you haven’t done so, please follow the Basic Client example first.

Offers

Request offers with the RequestTripOffers method.

Go

// define origin and destination location details
primaryAddressOrigin := "Stüberedder 14"
secondaryAddressOrigin := "22337 Hamburg"
primaryPoiNameOrigin := "Point A"
secondaryPoiNameOrigin := "Hamburg, Germany"
primaryAddressDestination := "Eckerkamp 38"
secondaryAddressDestination := "22391 Hamburg"
primaryPoiNameDestination := "Point B"
secondaryPoiNameDestination := "Hamburg, Germany"

tripOfferRequest := &tripv1beta2.RequestTripOffersRequest{
	Origin: &tripv1beta2.NamedLocation{
		Location: &types_v1.LatLon{
			Latitude:  53.6344823,
			Longitude: 10.0555216,
		},
		PrimaryAddress:   &primaryAddressOrigin,
		SecondaryAddress: &secondaryAddressOrigin,
		PrimaryPoiName:   &primaryPoiNameOrigin,
		SecondaryPoiName: &secondaryPoiNameOrigin,
	},
	Destination: &tripv1beta2.NamedLocation{
		Location: &types_v1.LatLon{
			Latitude:  53.6342303,
			Longitude: 10.0741517,
		},
		PrimaryAddress:   &primaryAddressDestination,
		SecondaryAddress: &secondaryAddressDestination,
		PrimaryPoiName:   &primaryPoiNameDestination,
		SecondaryPoiName: &secondaryPoiNameDestination,
	},
	Load: []*tripv1beta2.Load{
		{
			LoadType: &tripv1beta2.Load_Adult{
				Adult: &tripv1beta2.Adult{
					Wheelchair: tripv1beta2.Wheelchair_WHEELCHAIR_NOT_NEEDED,
				},
			},
		},
		{
			LoadType: &tripv1beta2.Load_Child{
				Child: &tripv1beta2.Child{
					Wheelchair: tripv1beta2.Wheelchair_WHEELCHAIR_NOT_NEEDED,
					ChildSeat:  tripv1beta2.ChildSeat_CHILD_SEAT_NOT_NEEDED,
				},
			},
		},
	},
	Time: &tripv1beta2.RequestTripOffersRequest_DepartureTime{
		// departure in 1 minute
		DepartureTime: timestamppb.New(time.Now().Add(time.Minute * 1)),
	},
}
// replace with the ID of the customer who is requesting trip offers
ctxWithCustomer := metadata.AppendToOutgoingContext(ctx, "customer-id", currCustomer)
tripOffersResponse, err := tripClient.RequestTripOffers(
	ctxWithCustomer, tripOfferRequest,
)

if err != nil {
	log.Fatalf("Could not request trip offers %v", err)
}
log.Printf("Received %d Trip Offers", len(tripOffersResponse.Offers))

Typescript

const offers = await client.requestTripOffers(
  {
    origin: {
      location: {
        latitude: 53.6344823,
        longitude: 10.0555216,
      },
      primaryAddress: "Stüberedder 14",
      secondaryAddress: "22337 Hamburg",
      primaryPoiName: "Point A",
      secondaryPoiName: "Hamburg, Germany",
    },
    destination: {
      location: {
        latitude: 53.6342303,
        longitude: 10.0741517,
      },
      primaryAddress: "Eckerkamp 38",
      secondaryAddress: "22391 Hamburg",
      primaryPoiName: "Point B",
      secondaryPoiName: "Hamburg, Germany",
    },
    load: [
      {
        adult: {
          wheelchair: Wheelchair.WHEELCHAIR_NOT_NEEDED,
        },
      },
      {
        child: {
          wheelchair: Wheelchair.WHEELCHAIR_NOT_NEEDED,
          childSeat: ChildSeat.CHILD_SEAT_NOT_NEEDED,
        },
      },
    ],
    departureTime: new Date(),
  },
  {
    metadata: new grpc.Metadata({
      // replace `currCustomerId` with the ID of the customer who is requesting trip offers
      "customer-id": currCustomerId,
    }),
  }
);
console.log(offers); // { offers: [ ... ] }

Order

Order one Offer with the OrderTrip method.

Go

offerToOrder := tripOffersResponse.GetOffers()[0].GetToken()
// replace with the ID of the customer who is ordering the trip
ctxWithCustomer = metadata.AppendToOutgoingContext(ctx, "customer-id", currCustomer)
orderTripResponse, err := tripClient.OrderTrip(
	ctxWithCustomer,
	&tripv1beta2.OrderTripRequest{
		OfferToken: offerToOrder,
	},
)
if err != nil {
	log.Fatalf("Could not order trip %v", err)
}
log.Printf("Successfully ordered trip: %v", jsonMarshalOptions.Format(orderTripResponse)) // { tripId: '7bc0118b-748e-4c13-bc5e-bb2164f04927' }

Typescript

const orderResponse = await client.orderTrip(
  {
    offerToken: offers.offers[0].token,
  },
  {
    metadata: new grpc.Metadata({
      // replace `currCustomerId` with the ID of the customer who is ordering the trip
      "customer-id": currCustomerId,
    }),
  }
);
console.log(orderResponse); // { tripId: '7bc0118b-748e-4c13-bc5e-bb2164f04927' }

Cancel as Customer

Cancel a Trip on behalf a Customer with the CancelTripAsCustomer method.

Go

// replace with the ID of the customer who is canceling the trip
ctxWithCustomer = metadata.AppendToOutgoingContext(ctx, "customer-id", currCustomer)
_, err = tripClient.CancelTripAsCustomer(
	ctxWithCustomer,
	&tripv1beta2.CancelTripAsCustomerRequest{
		TripId: tripId, // replace with tripId to cancel
	},
)
if err != nil {
	log.Fatalf("Could not cancel trip as customer %v", err)
}
log.Print("Successfully canceled trip as customer")

Typescript

const cancelAsCustomerResponse = await client.cancelTripAsCustomer(
  { tripId: orderResponse.tripId },
  {
    metadata: new grpc.Metadata({
      // replace `currCustomerId` with the ID of the customer who is cancelling the trip
      "customer-id": currCustomerId,
    }),
  }
);
console.log(cancelAsCustomerResponse); // {} empty response

Cancel as Integrator

Cancel a Trip as Integrator with the CancelTripAsIntegrator method.

Go

_, err = tripClient.CancelTripAsIntegrator(
	ctx,
	&tripv1beta2.CancelTripAsIntegratorRequest{
		TripId: tripId, // replace with tripId to cancel
	},
)
if err != nil {
	log.Fatalf("Could not cancel trip as integrator %v", err)
}
log.Print("Successfully canceled trip as integrator")

Typescript

const cancelAsIntegratorResponse = await client.cancelTripAsIntegrator({
  tripId: orderResponse.tripId,
});
console.log(cancelAsIntegratorResponse); // {} empty response