On-Demand Transit API Guidelines

Transit integrates on-demand services for a number of transit agencies. This page outlines Transit’s requirements to build an integration, with a new partner, that connects users to a partner app in which they can request or book the trip. In this model, users can use Transit to discover the on-demand service, plan trips using the service, and receive information about the approximate cost and travel time for an A-to-B trip or multimodal trip connecting to fixed-route service. Transit launches the partner’s app to perform ride requests.

The expected APIs and other guidelines for these integrations are provided below. The list of requirements isn’t meant to be exhaustive, but should help the on-demand transit partner understand the minimum level of commitment needed for an integration.

GOFS-lite feed

The General On-Demand Format Specification lite (GOFS-lite) allows on-demand service providers to define their service in a lightweight format that can be consumed by transport applications in an interoperable way. See GOFS-lite on GitHub for the complete spec.

Wait times can be provided in two different ways: for the whole system at once, using a format similar to GTFS-realtime or via an API that will provide the wait time for a specific pickup point. The latter is the preferred approach as it is less complex to integrate.

Creating the deeplink

There are two methods that allow Transit to request a ride on behalf of the user by launching the app of the on-demand partner: an attribution deeplink (which is preferred) or a URL scheme. Both the attribution deeplink and the URL scheme should accept origin, destination and product ID.

Attribution deeplink (preferred): launches the app store if the user doesn’t have the partner app installed. If the user does have the partner app installed, it opens the partner app instead. This allows the partner to attribute the request to Transit. The partner may look into using Firebase Dynamic Links or branch.io to manage attribution.
Alternatively, a ride request URL scheme directly opens the partner app. Transit must check if the user has the partner app installed or not. If this scenario is chosen, Transit and the partner must discuss a way to attribute the requests to Transit.

With either method, the Bundle ID or URL scheme of the app is required so that Transit can see if the app is currently installed.

Other requirements

The following should also be provided to Transit:

A published link to the partner’s GOFS-lite document
API endpoints and API keys for staging and production environments if using the wait times API
Up-to-date API documentation
If the partner’s app isn’t (yet) publicly available, a test build for both iOS and Android should be provided
Technical contact to whom Transit can ask questions regarding the integration