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

NameDescriptionTypeDefault
nearlocation, may be a ‘name’ or a ‘(lat,lng)’
nearlocation, may be a ‘name’ or a ‘(lat,lng)’query
starttime, accept formats: yyyyMMdd'T'HH:mmyyyy-MM-dd'T'HH:mm:ssquery
endtime, accept formats:yyyyMMdd'T'HH:mmyyyy-MM-dd'T'HH:mm:ssquery
typeof vehicle (if applies)query
featureslist of special features required (if applies)query
Parameters

Response Body

ElementVehiclelist
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

ElementAccountlist
media types:application/json
the list of accounts for the user

/parkingspot

GET

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

Parameters

NameDescriptionTypeDefault
nearlocation, maybe a ‘name’ or a ‘(lat, lng)’query

Response Body

ElementParkingspotlist
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

ElementBookinglist
media types:application/json
a List with the current Bookings

POST

Endpoint to create a booking

Parameters

NameDescriptionTypeDefault
vehicleid of the booking
query
accountof the user (if applies)query
starttime, accept formats: yyyyMMdd'T'HH:mmyyyy-MM-dd'T'HH:mm:ssquery
endtime, accept formats: yyyyMMdd'T'HH:mmyyyy-MM-dd'T'HH:mm:systemquery

Response Body

ElementBooking
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

NameDescriptionTypeDefault
uuidof the booking to returnpath

Response Body

Element:bookingMedia types:
application/jsonthe booking details

DELETE

Endpoint to cancel a booking

Parameters

NameDescriptionTypeDefault
uuidof the booking to cancelpath

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’

ParametersNameDescriptionTypeDefault
fromlocation, may be a ‘name’, a ‘(lat,lng)’ or a ‘()stop_code’query
tolocation, may be a ‘name’, a ‘(lat,lng)’ or a ‘()stop_code’query
departtime, accept formats:yyyyMMdd'T'HH:mmyyyy-MM-dd'T'HH:mm:ssquery

Response Body

Element:Servicelist
media types:application/json
the list of services found

/ticket

POST

Endpoint to book a ticket

Parameters

ParametersNameTypeDefault
serviceid of the service you want a ticket for, assuming this id univocally identifies from,to,departure of the service,path
passengersnumber of passengers for the booked ticketpath1
baggagenumber of baggages for all the passengers included in this ticketpath1

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

ParametersNameDescriptionTypeDefault
uuidunique id of the ticket to validatepath

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

ParametersNameDescriptionTypeDefault
uuidunique id of the booked ticket to confirmpath
paymentthat 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

PropertyTypeDescription
idid (string)
descriptiondescription (string)
{
  "id": "...",
  "description": "..."
}

AccountList

JSON

PropertyTypeDescription
accountsArray 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

PropertyTypeDescription
idid (string)
accountaccount (Account)
locationlocation (jsonLocation)
startstart (long)
endend (long)
vehiclevehicle (Vehicle)
{
 "id" : "...",
 "account" : {
   "id" : "...",
   "description" : "..."
 },
 "location" : {
   "lng" : ...,
   "address" : "...",
   "name" : "...",
   "lat" : ...
 },
 "start" : ...,
 "end" : ...,
 "vehicle" : {
   "location" : {
     "lng" : ...,
     "address" : "...",
     "name" : "...",
     "lat" : ...
   },
   "id" : "...",
   "name" : "...",
   "fuel" : ...
 }
}

BookingList

JSON

PropertyTypeDescription
bookingsarray 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

PropertyTypeDescription
existsexists (boolean)
feefee (float)
currencycurrency (string)
{
  "exists" : false,
  "fee" : ...,
  "currency" : "..."
}

ParkingSpot

ParkingSpot provides information about a parking spot:

  • location
  • capacity
  • used places

JSON

PropertyTypeDescription
locationlocation (jsonLocation)
capacitycapacity (int)
usedused (int)
{
  "location" : {
    "lng" : ...,
    "address" : "...",
    "name" : "...",
    "lat" : ...
  },
  "capacity" : ...,
  "used" : ...
}

ParkingSpotList

JSON

PropertyTypeDescription
parkingSpotsarray 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

PropertyTypeDescription
locationlocation (jsonLocation)
idid (string)
namename (string)
fuelfuel (int)
{
  "location" : {
    "lng" : ...,
    "address" : "...",
    "name" : "...",
    "lat" : ...
  },
  "id" : "...",
  "name" : "...",
  "fuel" : ...
}

VehicleList

JSON

PropertyTypeDescription
vehiclesarray of vehicles (Vehicle)
{
  "vehicles" : [ {
    "location" : {
      "lng" : ...,
      "address" : "...",
      "name" : "...",
      "lat" : ...
    },
    "id" : "...",
    "name" : "...",
    "fuel" : ...
  }, ... ]
}

jsonLocation

JSON

PropertyTypeDescription
lnglng (double)
namename (string)
latlat (double)
addressaddress (string)