RidePilot API

RidePilot Booking API (v1)

1 General API Notes

URLs

REST API base URLs are prefixed with /api

The API version will be prefixed the URL /v1/

Thus actual api calls will follow the pattern: /api/v1/

Authentication

In order to make trip requests, RidePilot will expect an API token to be passed along with each request. Tokens will be unique to each instance of 1-Click, or whichever app is authorized to make calls against the RidePilot API. (e.g., “X-RIDEPILOT-TOKEN=”)

2 API Calls

1 Authenticate Customer

Validate a Customer ID against a token. Used to associate a 1-Click Traveler with a RidePilot Customer.

GET authenticate_customer

Data

• customer_id string
• customer_token string
• provider_id string

Response

• error string

2 Create Trip

Create a new trip.

POST create_trip

Data

• customer_id string
• customer_token string
• provider_id string
• trip_purpose string (RidePilot Trip Purpose)
• leg string (1: first leg, 2: second leg, etc.)
• from_address {address: [Google Places API Format: See Appendix], address_name: [string], note: [string], in_district: [boolean]}
• to_address {address: [Google Places API Format: See Appendix], address_name: [string], note: [string], in_district: [boolean]}
• guests integer
• attendants integer
• mobility_devices integer (How many wheelchairs are in this trip?)
• pickup_time ISO8601
• dropoff_time ISO8601

Response

• error string
• trip_id integer (optional)
• status status_object {code: 'requested', name: 'Requested', message: 'This trip has been requested'}
• pickup_time ISO8601
• dropoff_time ISO8601
• comments string

3 Trip Purposes

Get a list of trip purposes for a provider.

GET trip_purposes

Data

• provider_id string

Response

• error string
• trip_purposes array of trip_purpose objects e.g., [{name: ‘Medical’, code: ‘1’}, {name: ‘Grocery, code: ‘2’}, . . . ]

4 Trip Status

Get the trip status for a given trip.

GET trip_status

Data

• customer_id string
• customer_token string
• trip_id* integer

Response

• error string
• trip_id integer (optional)
• status status_object {code: 'requested', name: 'Requested', message: 'This trip has been requested'}
• pickup_time ISO8601
• dropoff_time ISO8601
• comments string

The possible trip statuses are shown below:

Status	Names	Description
requested	Requested	Trip has been requested but not assigned to a Run or a Cab, or canceled
scheduled	Scheduled	Trip has been assigned to a Run
scheduled_to_cab	Scheduled to Cab	Trip has been assigned to a Cab
unmet	Unmet	Unmet Need
td	Turned Down	Trip request was turned down by Provider
canc	Canceled	Trip was canceled by the Customer
ns	No Show	No Show
comp	Completed	Trip completed

5 Cancel Trip

Cancel a booked trip.

GET trip_status

Data

• customer_id string
• customer_token string
• trip_id* integer

Response

• error string

6 Authenticate Provider

Confirm that a provider has correctly configured a booking profile.

GET authenticate_provider

Data

• provider_id string

Response

• error string

Appendix: Google Places

The following is an example of using a Google Place to represent an address in RidePilot.

RidePilot Value	Google Place Details Value
Building Name	name	Optional
Street Address	address_components ↠ [street_address]	Required
City	address_components ↠ [locality, political]	Required
State	address_components ↠ [administrative_area_level_1, political]	Required
Zipcode	address_components ↠ [postal_code]	Optional
Phone Number	formatted_phone_number	Optional
Longitude	geometry ↠ location ↠ lat	Required
Latitude	geometry ↠ location ↠ lng	Required

Example of Google Place Details format can be found HERE.

Example

Cambridge Systematics

100 Cambridge Park Drive

Cambridge, MA 02140

(617) 354-0167

The address above is represented with the Google Places API as the JSON below.

{ 
    “address_components” : [
    {
        “long_name”: “100 Cambridge Park Drive”,
        “short_name”: “100 Cambridge Park Drive”,
        “types” : [ “street_address”]
    },
    {
        “long_name”: “Cambridge”,
        “short_name”: “Cambridge”,
        “types” : [ “locality”, “political”]
    },
    {
        “long_name”: “Massachusetts”,
        “short_name”: “MA”,
         “types” : [“administrative_area_level_1”, “political”]
    },
    {
        “long_name”: “02140”,
        “short_name”: “02140”,
	        “types” : [ “postal_code”]
        }
    ],
    “formatted_phone_number”: “(617) 354-0167”, 
    “geometry” : {
        “location” : {
        “lat” : 42.394307,
            “lng” :  -71.144707
        }
    },
    “name” : “Cambridge Systematics”
}

The items below are not well-represented with the Google Places API, although they are used by RidePilot. These fields can be passed in addition to the Google Place as shown in Section 2.2: Create Trip.

• address_name string (This field is used to label an address as Home, Work, Doctor, etc.)
• notes string (Additional comments related to the address)
• in_district boolean (Is the address within the Provider district?)