Note: Enterprise customers-only

Note: Beta-only

The TripGo API allows making bookings for a handful of transport service providers (TSPs).

This enables your users to:

Coming soon:

In order to enable bookings for your TripGo API key, please get in touch with our team. For most TSPs, you will need to provide us with additional information of your API credentials.

API Endpoints

Linking and unlinking accounts

Before you can do any bookings, you will need to provide the relevant authentication details to the server.

If the user has an account (as per the userToken header), then this is only necessary once. If the user does not have an account, this is necessary for each session. Typically, the endpoints which do the bookings will tell you, if the session hasn't been authenticated yet.

Auth Flow

This flow will depend on the TSP and can be started in two separate ways:

This flow will use the Auth Forms to provide the apps the information to show to the user and also the information required to be POSTed to continue the flow.

For a TSP that allows OAuth2, the Auth Form will include the fields with the information for the apps to do OAuth, including clientId, clientSecret, scope, authUrl, tokenUrl; and also the required field to be POSTed, including accessToken, refreshToken and expiration.

For a TSP that provides a different authentication method, the AuthForm will include the required field to be filled by the user and also any extra information that need to be shown to the user in the same field format. This will follow the same flow approach as for Form-based Booking Flow.

The end of this flow will depending on how it was started. If was started to link an account, the flow will end with an empty 204 response, when successfuly linked. If it was started in a booking flow, the flow will automatically continue with it, attempting to do the booking and returning the status, as in step 4 of Form-based Booking Flow.

Getting available TSP for a trip

If there are available TSPs for a trip segment, this will be indicated by the presence of the booking object in the segment.

The booking object in the segment may include:

Booking a segment

To book a segment, either use the Form-based Booking Flow with the bookingURL either directly from the segment reference, or the Quick Booking Flow from the data returned after hitting quickBookingUrl.

Form-based Booking Flow

If form-based booking flow is available for a segment, the bookingUrl will return a Booking Form object with instructions to start the booking flow.
A form-based booking flow will possible include the following steps:

1) return the available TSP products to allow the user choose one of them, 2) check whether we have user credentials to do the booking, if it does, skip 3, 3) start Auth flow, 4) attempt to do the booking and return the Status Form.

Quick Booking Flow

Getting available TSP products for a trip

If quick booking flow is available for a segment, the available TSP products can be browsed for it without providing any authentication details.

As part of the quick booking flow, the quickBookingUrl will then return a list of available TSP products, which notably each come:

Updating trip with booking details

At the end of the booking flow, you will get a refreshURLForSourceObject. Hit this URL with a GET request, to get the updated trip.

Note that these trips can be eligible for real-time updates even if the original trip was not eligible as there might now be additional real-time information based on the booking.

Trips with a confirmed booking will also have extra information about the confirmed booking in a field called confirmation in the booking field of the segment.

This confirmation object may include detailed information about the provider, vehicle and status for the booking, with the following possible fields:

And also a list of possible actions depending on the status of the booking, with the following fields:

Examples of actions with internalUrl fields are cancel booking, which will have the isDestructive field in true, and rate booking.

Examples of actions with externalUrl fields are qrcode values, for showing a ticket to the user, and phone numbers, starting with tel:.

Rating and Tipping

Whenever available, the confirmation information will include the rate booking action, which will include an internalUrl which will return a bookingForm with the following fields:

The booking form will include the action url to POST the data.

Booking Form Specs

Both the booking flow and the auth flow use an ad-hoc format to handle the communication of data between the backend and the apps.

There exists three different forms:

All three share the same structure, while Auth and Status are specialized versions of the Booking Form with some extra data.

A Booking Form may include:

A FormGroup is a lisf of FormFields with a title and an optional footer. A FormField is a structure that represents the data, either to show to the user or required in the backend for the next step. Each FormField will include:

There are several types of FormFields:

Bookings in the TripKit SDKs

The TripKit SDKs implement support for bookings: