On-Demand Transit API Guidelines

Transit integrates on-demand microtransit services for a number of transit agencies. This page outlines the varying levels of integration possible for a microtransit partner. Each of the following levels of integration builds upon the previous one:

  • Level 1: Deep Linking. Users can plan trips in Transit using the microtransit 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.
  • Level 2: Native Requests. Existing users of the microtransit service can use the service without having the partner’s app installed. The user can plan microtransit trips and request a ride entirely within Transit.
  • Level 3: Account Creation. New users can sign up, view and use the partner’s service completely within Transit.

The expected APIs and other guidelines for each level are provided below. The list of requirements given for each level isn’t meant to be exhaustive, but should help the microtransit partner identify the minimum level of commitment needed for each type of integration. The partner’s endpoints may vary as long as the general information remains available.

On this page

Level 1: Deep Linking

Trip + Price Estimate API

  • Purpose: Get an estimate for a potential trip. This endpoint will be called every time a Transit user requests a trip plan in the service coverage area.
  • Request: Origin lat/lng, destination lat/lng, whether the user wants a wheelchair accessible vehicle, 
  • Response: ETA; duration (optional) and distance (optional) for ride from start to destination for each product; price estimate.
  • Optionally, pickup and dropoff points if applicable.

Attribution deeplink

  • Attribution deeplink: Allow Transit to request a ride on behalf of the user by launching the app of the on-demand partner.
    • The attribution deeplink (preferred) launches the app store if the user doesn’t have the partner app installed. If they do have the partner app installed, it opens the partner app instead. This allows the partner to attribute the request to Transit. You may look into using Firebase Dynamic Links or branch.io for this.
    • 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.
    • URL scheme or attribution deeplink should accept origin, destination and product ID.
  • Bundle ID or URL scheme of the app so that Transit can see if the app is currently installed

Zone information and rules

  • A simple geoJSON describing zones. Ideally, this geoJSON should be provided via an API.
  • The detailed schedule for every zone (start and end time for each day)
  • Possibility of adding two array fields (transfers_to and transfers_from) describing the link between zones (if applicable). Arrays values must reference other zone IDs.
  • Sample:
{
"type": "FeatureCollection",
"name": string,
"features": [
	{
	"type": "Feature",
		"properties": {
			"name": string,
			"id": `ServiceAreaId`,
			"transfers_to": [`ServiceAreaId`, ...],
			"transfers_from": [`ServiceAreaId`, ...],
		},
		"geometry": {
			"type": "Polygon",
			"coordinates": [[[lng, lat]... ]... ]
		}
	}, ...
		]
}<br>
	

Level 2: Native Requests

Authentication API

  • Purpose: Allow the user to login and logout of the on-demand service. Transit can handle a wide range of implementations such as basic auth, OAuth, or other token based mechanism.

Current Rides API

  • Purpose: Allow the user to get a list of ongoing rides.
  • Response: Ride ID, status, driver details (e.g. name, car make, color, etc), pickup ETA, etc.

Ride Request API

  • Purpose: Request a ride on behalf of the user.
  • Request: Origin lat/lng, destination lat/lng, product ID.
  • Response: Ride ID, status, driver details (e.g. name, car make, color, etc), pickup ETA, etc.

Get Ride Details API

  • Purpose: Provide details about the ride of a user. This endpoint will be polled by Transit every couple of seconds to update the vehicle position in the app.
  • Request: Ride ID.
  • Response: Ride ID, status, driver details (e.g. name, car make, color, etc), pickup ETA, etc.

Update Ride API

  • Purpose: Allow the user to update details of a ride (e.g. destination).
  • Request: Ride ID.
  • Response: Success/failure status.

Cancel Ride API

  • Purpose: Allow the user to cancel an ongoing ride.
  • Request: Ride ID.
  • Response: Success/failure status.

Level 3: Account Creation

Sign-up API

  • Purpose: Allow a new user to sign up to the on-demand service.
  • Request: All information that’s required to sign up to the service (e.g. first name, last name, email, password, credit card, card expiration date, billing address. etc).
  • Response: User ID

Credit Card Management API

  • Purpose: Allow a user to add, remove or edit a credit card.
  • Request: All information required for payment processing (e.g. card holder name, card number, expiration date, billing address, etc).
  • Response: Success/failure status.

Other Requirements

For all three levels, the following should be provided to Transit:

  • API endpoints and API keys for staging and production environments.
  • A staging environment that replicates the exact same conditions as in production (ride availability, zones, etc.)
  • Up to date API documentation
  • For level 1: If the partner’s app isn’t publicly available, a test build for both iOS and Android should be provided
  • Technical contact to whom Transit can ask questions regarding the integration.
  • If Level 2 or 3: Test accounts for the production environment.
  • If Level 3: PCI attestation of compliance (AOC).
  • If Level 3: Results from a recent scan done by an approved scanning vendor (ASV).

Still need help? Contact Us Contact Us