Introduction

TripGo is a multi-modal trip planner that delivers door-to-door travel options to over 500,000 transport users in 50 countries around the globe. The TripGo booking and payment API enables vendors to integrate transaction points within search results where the user can purchase, book or reserve transport services.

The TripGo booking and payment API enables vendors to interface directly with potential customers of their services through the popular TripGo app offering vendors a powerful automated sales channel.

TripGo suggests to the users several ways of travelling from one place to another, using different means of transport. A Transport Provider offering a specific service or resource, allowing people to travel from one place to another, can grant TripGo access to their services/resources information. Therefore, TripGo will be able to suggest to its users ways of travelling using the Transport Provider services/resources. Also, if the Transport Provider allows online booking or purchasing of tickets, it is possible to connect TripGo to the Transport Provider system and allow TripGo users to book a service or resource, and possibly pay for it, everything within TripGo App, while the user is looking at the suggested trip on the map.

This document will describe what is required for a Transport Provider to allow TripGo App to suggest the users their services and book them within the app. For any type of Provider, TripGo needs a way of:

  • Querying for available services (like shuttle buses) or resources (like cars), depending on parameters required by the provider,
  • Booking them, TripGo will include the required service/resource specific parameters.

For example, for shuttle buses, required parameter for querying available services may include from and to location, and time of departure (/service). In the case of car sharing, required parameters may include a location where the car needs to be near to, and the start/end time of availability (/vehicle). In the case of the booking, for shuttle buses, required parameters may include number of passengers and baggage (/ticket). For car sharing, possible parameters are start/end time of the booking (/booking).

Providers with or without registered users

For providers with registered users, TripGo needs a way to access the provider system/API in behalf of the users. In this scenario, TripGo assumes that the provider will charge the users directly (without TripGo intervention).

For providers without registered users, TripGo needs a way to confirm the booking of tickets (after the user has paid for them). TripGo will book the ticket, charge the user for it, and then confirm the payment with the provider. Therefore, a temporary booking is required to prevent charging a user for a later unavailable service.

Possible Use Cases

Car Share provider A with registered users

TripGo will:

  1. ask for available vehicles (/vehicles) which can be queried on demand or updated at regular intervals (e.g., once a day, every 5 minutes)
  2. when the user choose to book a car, authenticate the user, through OAuth, then
  3. ask for the accounts (/account) that the user has (if the provider A allows multiple accounts for the same user, if not, ignore skip step)
  4. finally, attempt the booking (/booking). Opt) ask for parking spots (/parkingspot), if provided, to let the user know where to park the car, after using it.

Shuttle provider B without registered users

TripGo will:

  1. query for services (/services) given a from,to,start values (to be able to use these services while routing and have a unique id to easily identify them).
  2. if the user decides to buy a ticket, process the payment through a PSP (Payment Service Provider), and then,
  3. book the ticket (/ticket) on external provider B,
  4. finally, return to user a ‘virtual’ ticket with a valid ID or QR code (created by provider B) for the provider to verify on site.

/vehicle

GET

Search for free vehicles ‘near’ to a specific location, available from ‘start’ time to ‘end’ time of a specific ‘type’ and containing these ‘special’ features

Parameters

NAME DESCRIPTION TYPE DEFAULT
near location, may be a ‘name’ or a ‘(lat,lng)’
near location, may be a ‘name’ or a ‘(lat,lng)’ query
start time, accept formats: yyyyMMdd'T'HH:mm, yyyy-MM-dd'T'HH:mm:ss query
end time, accept formats:yyyyMMdd'T'HH:mm, yyyy-MM-dd'T'HH:mm:ss query
type of vehicle (if applies) query
features list of special features required (if applies) query

Response Body

ELEMENT VEHICLELIST
media types: application/json

the list of free vehicles found

/account

GET

Provides all valid accounts of a user. Access to this endpoint is restricted. See OAuth documentation for more details.

Response Body

ELEMENT: ACCOUNTLIST
media types: application/json

the list of accounts for the user

/parkingspot

GET

Search for free parking spots ‘near’ to a specific location

Parameters

NAME DESCRIPTION TYPE DEFAULT
near location, may be a ‘name’ or a ‘(lat,lng)’ query

Response Body

ELEMENT: PARKINGSPOTLIST
media types: application/json

the list of free vehicles found

/booking

GET

Endpoint to get the current bookings of the user. Access to this endpoint is restricted. See OAuth documentation for more details.

Response Body

ELEMENT: BOOKINGLIST
media types: application/json

a List with the current Bookings

POST

Endpoint to create a booking

Parameters

NAME DESCRIPTION TYPE DEFAULT
vehicle id of the booking query
account of the user (if applies) query
start time, accept formats: yyyyMMdd'T'HH:mm, yyyy-MM-dd'T'HH:mm:ss query
end time, accept formats: yyyyMMdd'T'HH:mm, yyyy-MM-dd'T'HH:mm:system query

Response Body

ELEMENT: BOOKING
media types: application/json

the booking details if successful

/booking/{uuid}

GET

Endpoint to get a speficic booking of the user. Access to this endpoint is restricted. See OAuth documentation for more details.

Parameters

NAME DESCRIPTION TYPE DEFAULT
uuid of the booking to return path

Response Body

ELEMENT:BOOKING MEDIA TYPES:
application/json the booking details

DELETE

Endpoint to cancel a booking

Parameters

NAME DESCRIPTION TYPE DEFAULT
uuid of the booking to cancel path

Response Body

ELEMENT: CANCELBOOKING
media types: application/json

the cancel booking fee information

/service

GET

Search for services going ‘from’ to ‘to’ within 30 minutes after ‘depart’

PARAMETERS NAME DESCRIPTION TYPE DEFAULT
from location, may be a ‘name’, a ‘(lat,lng)’ or a ‘()stop_code’ query
to location, may be a ‘name’, a ‘(lat,lng)’ or a ‘()stop_code’ query
depart time, accept formats:yyyyMMdd'T'HH:mm, yyyy-MM-dd'T'HH:mm:ss query

Response Body

ELEMENT: SERVICELIST
media types: application/json

the list of services found

/ticket

POST

Endpoint to book a ticket

Parameters

NAME DESCRIPTION TYPE DEFAULT
service id of the service you want a ticket for, assuming this id univocally identifies from,to,departure of the service, path
passengers number of passengers for the booked ticket path 1
baggage number of baggages for all the passengers included in this ticket path 1

Response Body

ELEMENT: TICKET
media types: application/json

a FareTicket with a unique id of your ticket

/ticket/{uuid}

GET

Endpoint to validate a ticket

PARAMETERS NAME DESCRIPTION TYPE DEFAULT
uuid unique id of the ticket to validate path

Response Body

ELEMENT: TICKET
media types: application/json

the ticket if it is valid, or a Not Found HTTP status error

/ticket/{uuid}/confirm

POST

Endpoint to confirm the booking of a ticket and process the payment

PARAMETERS NAME DESCRIPTION TYPE DEFAULT
uuid unique id of the booked ticket to confirm path
payment that will be used to validate your payment (throught an external server) path

Response Body

ELEMENT: TICKET
media types: application/json

the FareTicket with a the status updated, if it was possible to confirm payment.

Data Model

All endpoints act on a common set of data. The data can be represented with different media (i.e. “MIME”) types, depending on the endpoint that consumes and/or produces the data. The data can described by JSON, which definitively describes the JSON representation of the data.

Account

Account provides information about the user account

  • id of the account
  • description

it may contain any other extra information required by the specific provider

JSON

PROPERTY TYPE DECRIPTION
id id (string)
description description (string)
{
  "id": "...",
  "description": "..."
}

AccountList

JSON

PROPERTY TYPE DESCRIPTION
accounts Array of accounts (Account)
{
  "accounts" : [ {
    "id" : "...",
    "description" : "..."
  }, ... ]
}

Booking

Booking provides information about the booking

  • id of the booking
  • account of the booking (if applies)
  • location
  • start time, in seconds since 1970
  • end time, in seconds since 1970
  • vehicle booked

it may contain any other extra information required by the specific provider

JSON

PROPERTY TYPE DESCRIPTION
id id (string)
account account (Account)
location location (jsonLocation)
start start (long)
end end (long)
vehicle vehicle (Vehicle)
{
 "id" : "...",
 "account" : {
   "id" : "...",
   "description" : "..."
 },
 "location" : {
   "lng" : ...,
   "address" : "...",
   "name" : "...",
   "lat" : ...
 },
 "start" : ...,
 "end" : ...,
 "vehicle" : {
   "location" : {
     "lng" : ...,
     "address" : "...",
     "name" : "...",
     "lat" : ...
   },
   "id" : "...",
   "name" : "...",
   "fuel" : ...
 }
}

BookingList

JSON

PROPERTY TYPE DESCRIPTION
bookings array of bookings (Booking)
{
 "bookings" : [ {
   "id" : "...",
   "account" : {
     "id" : "...",
     "description" : "..."
   },
   "location" : {
     "lng" : ...,
     "address" : "...",
     "name" : "...",
     "lat" : ...
   },
   "start" : ...,
   "end" : ...,
   "vehicle" : {
     "location" : {
       "lng" : ...,
       "address" : "...",
       "name" : "...",
       "lat" : ...
     },
     "id" : "...",
     "name" : "...",
     "fuel" : ...
   }
 }, ... ]
}

CancelBooking

CancelBooking provides information about the possible fees after a canceled booking

  • whether a fee exists
  • the amount
  • the currency of the fee

JSON

PROPERTY TYPE DESCRIPTION
exists exists (boolean)
fee fee (float)
currency currency (string)
{
  "exists" : false,
  "fee" : ...,
  "currency" : "..."
}

ParkingSpot

ParkingSpot provides information about a parking spot:

  • location
  • capacity
  • used places

JSON

PROPERTY TYPE DESCRIPTION
location location (jsonLocation)
capacity capacity (int)
used used (int)
{
  "location" : {
    "lng" : ...,
    "address" : "...",
    "name" : "...",
    "lat" : ...
  },
  "capacity" : ...,
  "used" : ...
}

ParkingSpotList

JSON

PROPERTY TYPE DESCRIPTION
parkingSpots array of parkingSpots (ParkingSpot)
{
  "parkingSpots" : [ {
    "location" : {
      "lng" : ...,
      "address" : "...",
      "name" : "...",
      "lat" : ...
    },
    "capacity" : ...,
    "used" : ...
  }, ... ]
}

Vehicle

Vehicle provides information about the vehicle

  • id of the vehicle
  • name
  • fuel, in percentage
  • location

it may contain any other extra information required by the specific provider

JSON

PROPERTY TYPE DESCRIPTION
location location (jsonLocation)
id id (string)
name name (string)
fuel fuel (int)
{
  "location" : {
    "lng" : ...,
    "address" : "...",
    "name" : "...",
    "lat" : ...
  },
  "id" : "...",
  "name" : "...",
  "fuel" : ...
}

VehicleList

JSON

PROPERTY TYPE DESCRIPTION
vehicles array of vehicles (Vehicle)
{
  "vehicles" : [ {
    "location" : {
      "lng" : ...,
      "address" : "...",
      "name" : "...",
      "lat" : ...
    },
    "id" : "...",
    "name" : "...",
    "fuel" : ...
  }, ... ]
}

jsonLocation

JSON

PROPERTY TYPE DESCRIPTION
lng lng (double)
name name (string)
lat lat (double)
address address (string)