+27 87 310 6400 | products@afrigis.co.za
bclose

Gautrain API

Gautrain - Integrate Gautrain information services into your application.
Gautrain_2

The Gautrain Bus Location Service enables developers to incorporate the Gautrain bus information into their applications.

Please note that this service is subject to Terms and Conditions. It is not available to Trial users. To activate your key for this service, please contact AfriGIS at products@afrigis.co.za.

API DOCUMENTATION

1. Gautrain Bus Location Service

1.1 getBusesByBoundingBoxServlet

1.2 getAllBusStations

2. Fare Calculator Service

2.1 getFareTypes

2.2 getStations

2.3 calculateFare

3. Timetable Service

3.1 getDataVersion

3.2 getAllRoutes

3.3 getAllStations

3.4 getStationsOnRoute

3.5 getTimetable

3.6 getTimetableWithTransfers

4. Alert Services

 

1. Gautrain Bus Location Service

Overview

The Gautrain Bus Location Service is a service that can be called to return near-real time list of Gautrain Buses and their current locations.

Key features:

  • Real time bus locations
  • Easy to integrate

1.1. getBusesByBoundingBoxServlet

You can specify the targeted area by providing a bounding box; a bounding box is an area enclosed between two longitudes (minimum and maximum) and two latitudes (minimum and maximum).

Parameters

north – The maximum latitude of the bounding box.

south – The minimum latitude of the bounding box.

east – The maximum longitude of the bounding box.

west – The minimum longitude of the bounding box.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.getBusesByBoundingBoxServlet/AUTH_PARAMS/?north=-26.034&south=-26.049&east=28.123&west=28.116
For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

 

Response Description:

HostName– Not applicable.
HostAddr– Not applicable.
Host– Not applicable.
Timestamp– Date and time of event.
Result– JSON object that contains the actual data.
busPositions– An array of JSON objects containing the retrieved bus position data.

  • busId– ID provided by the bus tracking data provider.
  • currsegment– Current route segment on which the bus finds itself. Calculated by AfriGIS.
  • formattedLastModified– A formatted timestamp.
  • heading– Compass Heading provided by the bus tracking data provider.
  • lastModified– Unix Epoch time stamp (milliseconds), indicating when last we received an update for this bus.
  • latitude– Latitude of the current location, decimal format.
  • longitude– Longitude of the current location, decimal format.
  • remainonsegment– A value between 0 and 1 (percentage) indicating how far the bus is from the next stop.(e.g. 0.3456).
  • routecode– Route to which bus is snapped. Please note that it might not always be 100% accurate, due to GPS inaccuracies and certain segments of routes that cross.
displayFields– Array of strings that map to the keys in the objects found in the busPositions array. The intention was to have a mechanism to allow server control of which fields to use when displaying bus positions on the map.

1.2. getAllBusStations

This method gets all the available type of fares, including a description.

Parameters

None.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.busStationServlet/AUTH_PARAMS/?cmd=getAllBusStations
For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Note that the response can be compressed with gzip by adding the HTTP request header Accept-Encoding: gzip.

Click to expand Sample Response

 

Response Description:

Note that the HTTP Headers will carry a Cache-Control:max-age= and ETag header, which clients can use to enable good caching strategies.

The meanings of the field names are as follows (the 2 or 3 letter names are an effort to get the JSON as small as possible):

  • bs – Bus Stops. An array of bus stop objects
  • br – Bus Route on which a bus stop is located
  • ct – Cumulative Trip time, in minutes. This is the total drive time from the first stop to THIS bus stop
  • la – the latitude of the stop
  • lo – the longitude of the stop
  • na – the Name of the stop
  • se – the Segment of the stop. Starts at 1 .This is in ascending order in the bus stop array
  • stt – Segment Travel Time. This is the time it takes to complete this segment from the previous stop
  • sc – Station Code. The code of the Station this bus stop is associated with
  • sn – Stop Number. The number of this stop. Starts at 0 (zero). In ascending order in the bus stop array
  • st – Stop Type. Possible values are:
    • RouteEnd
    • Feeder
    • Distribution
    • OD
  • tts – Time To Station. From THIS stop, how many minutes to this route’s Train Station
  • rc – Route Code. The code of the route

2. Fare Calculator Service

Overview

The Gautrain Fare Calculator Service is a service that can be called to get information about the different types of fares as well as do a calculation of a return trip between stations.

Key features:

  • Up to date fare prices
  • Easy to integrate

2.1. getFareTypes

This method gets all the available type of fares, including a description.

Parameters

None.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.fareCalculatorServlet/AUTH_PARAMS/?cmd=getFareTypes
For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

 

Response Description:

Host– Not applicable.
HostName– Not applicable.
HostAddr– Not applicable.
Result– JSON object that contains the actual data.
Description– A text description of the type of trip.
Id– The Id of the trip type
Name– The name of the trip type
Order– The order in which to display this trip
statusCode– 0 for success and 1 for failure
Timestamp– Date and time of event.

2.2. getStations

This method gets all the Stations and their descriptions

Parameters

None.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.fareCalculatorServlet/AUTH_PARAMS/?cmd=getStations
For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description:

Host– Not applicable.
HostName– Not applicable.
HostAddr– Not applicable.
Result– JSON object that contains the actual data.
Description– A text description of the type of trip.
Id– The Id of the trip type
Name– The name of the trip type
Order– The order in which to display this trip
statusCode– 0 for success and 1 for failure
Timestamp– Date and time of event.

2.3. calculateFare

This method gets all the Stations and their descriptions.

Parameters

fareTypeId– The fare type to use for the calculation.

fromId– The origin station.

fromUseParking– Indicates if parking is used at the origin station. Value is true or false.

fromUseBus– Indicates if a bus will be used to the origin station. Value is true or false.

toId– The destination station.

toUseParking– Indicates if parking will be used at the destination station. Value is true or false.

toUseBus– Indicates if a bus will be used at the destination station. Value is true or false.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.fareCalculatorServlet/AUTH_PARAMS/?cmd=calculateFare&fareTypeId=1&fromId=1&fromUseBus=false&fromUseParking=true&toId=8&toUseBus=true&toUseParking=false
For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description:

Host– Not applicable.
HostAddr– Not applicable.
HostName– Not applicable.
Result– JSON object that contains the actual data.
AdditionalFareTotal– A numeric value for the additional fare.
BusFareEach– A numeric value for a single bus trip.
FareCalcNotes– A text description of any additional messages to display to the user regarding the Fare calculation.
FareTotal– The total of all the fares combined.
FullMessageText– A text string with any messages relating to the fare calculation.
GreenFareDiscountRate– A numeric value representing the discount rate applicable for Green Fare.
GreenFareLabel– A text string with the label description for the Green Fare.
GreenFareTotal– A numeric value representing the total discount on the fare.
OffPeakDiscountRate– A numeric value representing the discount rate applicable for Off Peak.
OffPeakLabel– A text string with the label description for Off Peak.
OffPeakTotal– A numeric value representing the total discount on the fare.
OrangeFareLabel– A text string with the label description for the Orange Fare.
ParkingFareEach– A numeric value representing the parking fee charged.
RedFareLabel– A text string with the label description for the Red Fare.
Routes– An array filled specific values relating to a specific fare in the Route.
AdditionalFare– A numeric value representing any additional fares to be added to the route.
Fare– A numeric value representing the fare for the specific value.
FromStation– A text string with the station origin.
ToStation– A text string with the station destination.
StatusCode– 0 for success and 1 for failure
Timestamp– Date and time of event.

3. Timetable Service

3.1. getDataVersion

This method is a way to check that you have the most up to date data.

Parameters

None.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.timetableServlet/AUTH_PARAMS/?cmd=getDataVersion
For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description:

Host– Not applicable.
HostAddr– Not applicable.
HostName– Not applicable.
Result– JSON object that contains the actual data.
ControlFileURL– The URL to the Control File.
DataFileURL– The URL to the DataFile.
Version– A numeric value representing the file version.
StatusCode– 0 for success and 1 for failure
Timestamp– Date and time of event.

3.2. getAllRoutes

This method gets all available routes.

Parameters

None.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.timetableServlet/AUTH_PARAMS/?cmd=getAllRoutes

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description:

Host– Not applicable.
HostAddr– Not applicable.
HostName– Not applicable.
Result– JSON object that contains the actual data.
Routes– An array filled specific values relating to a specific fare in the Route.
Description– A text string of the route.
id– A numeric value representing the id of the specific route.
name– A text string with the route name.
StatusCode– 0 for success and 1 for failure
Timestamp– Date and time of event.

3.3. getAllStations

This method gets all available routes.

Parameters

None.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.timetableServlet/AUTH_PARAMS/?cmd=getAllStations

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description:

Host– Not applicable.
HostAddr– Not applicable.
HostName– Not applicable.
Result– JSON object that contains the actual data.
Stations– An array filled specific values relating to a specific Station.
address– A text string of the address.
fare_calculator_id– A numeric value representing the fare_calculator_id of the specific station.
id– A numeric value representing the id of the station.
name– A text string with the route name.
latitude– A numeric value of the latitude in Decimal format.
longitude– A numeric value of the longitude in Decimal format.
short_name– A text string with the short name for the station.
name– A text string with the full station name.
StatusCode– 0 for success and 1 for failure.
Timestamp– Date and time of event.

3.4. getStationsOnRoute

This method gets all stations on a specific route.

Parameters

routeid– A numeric id of the route you are looking for.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.timetableServlet/AUTH_PARAMS/?cmd=getStationsOnRoute&routeid=1

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description:

Host– Not applicable.
HostAddr– Not applicable.
HostName– Not applicable.
Result– JSON object that contains the actual data.
Stations– An array filled specific values relating to a specific Station.
route_id – A numeric value for the specified route id.
sequence– A numeric value of the sequence in which this station appears in this route.
station_id– A numeric value representing the id of the station.
StatusCode– 0 for success and 1 for failure.
Timestamp– Date and time of event.

3.5. getTimetable

This method gets the timetable for a specific route on a specified weekday.

Parameters

routeid– Indicates the route for which the timetable is required.
stationid– Indicates the station for which the timetable is required.
weekday– 0 = weekend
1 = weekday

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.timetableServlet/AUTH_PARAMS/?cmd=getTimetable&routeid=1&stationid=1&weekday=1

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description:

Host– Not applicable.
HostAddr– Not applicable.
HostName – Not applicable.
Result– JSON object that contains the actual data.
Stations– An array containing information regarding the station stop.
cars– A numeric value containing the number of cars.
id– A number with the specific id of the entry in the timetable for this station
route_id– A number for the specific route id.
schedule_time– A timestamp in 24 hour time of the scheduled time the train would stop at the specified station.
sequence– A sequence of stations along the route.
station_id– A number with the current station id.
weekday – 0 = weekend
1 = weekday
StatusCode– 0 for success and 1 for failure.
Timestamp– Date and time of event.

3.6. getTimetableWithTransfers

This method gets the timetable for a specific route on a specified weekday.

Parameters

from_stationid– Indicates the station origin for this trip.
to_stationid– Indicates the station destination for this trip.
weekday– 0 = weekend
1 = weekday

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.mobileServer.timetableServlet/AUTH_PARAMS/?cmd=getTimetableWithTransfers&from_stationid=1&to_stationid=11&weekday=1

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

Response Description:

Host– Not applicable.
HostAddr– Not applicable.
HostName – Not applicable.
Result– JSON object that contains the actual data.
day_type– JSON object that contains the details of the day_type.
id– day_type id.
name– A description of the day type.
entries – An array containing information regarding the different stops along the route as well as the time and the number of cars in the train.
fromCars– A numeric value containing the number of cars at the origin station.
fromTime– Time of departure at the origin station.
toCars– A numeric value containing the number of cars at the destination station.
toTime– Time of arrival at the destination station.
from_route– JSON object with details regarding the origin route.
description– A text string describing the route.
id– A numeric value identifying the specific route.
name– A text string containing the route name.
short_name– A short text string for the route name.
from_station– JSON object containing more information on the origin station.
address– A text string containing the address of the origin station.
fare_calculator_id – A numeric value used to identify a specific station when calculating the fares.
id– A numeric value identifying the origin station.
latitude– Latitude of the origin station, decimal format.
longitude– Longitude of the origin station, decimal format.
name– A text string containing the origin station name.
short_name– A short text string for the station.
to_route– JSON object with details regarding the destination route.
description – A text string describing the route.
id – A numeric value identifying the specific route.
name – A text string containing the route name.
short_name – A short text string for the route name.
to_station – JSON object containing more information on the destination station.
address – A text string containing the address of the destination station.
fare_calculator_id – A numeric value used to identify a specific station when calculating the fares.
id – A numeric value identifying the destination station.
latitude – Latitude of the destination station, decimal format.
longitude – Longitude of the destination station, decimal format.
name – A text string containing the destination station name.
short_name – A short text string for the destination station.
instructions– A text string giving specific instructions on how to use the route.
transfer– A boolean value indicating whether you would need to transfer from one route to another.
StatusCode– 0 for success and 1 for failure.
Timestamp – Date and time of event.

 

4. Alerts Service

This method is a way to check if there are any active Gautrain alerts that must be displayed to the end user.

Please note: Repeat the process not more than once every 15 minutes.

An Alert is considered active if its expireTime attribute is greater or equal to the current system time.

Results will be sorted in descending order based on createDate – making it easier to show the user the most relevant alerts first.

Parameters

None.

Sample Request:

https://saas.afrigis.co.za/rest/2/gautrain.cms.activeAlerts/AUTH_PARAMS/

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Note that the response can be compressed with gzip by adding the HTTP request header Accept-Encoding: gzip.

Click to expand Sample Response

Response Description:

message – The message text of the body as plain text, mark-up free (i.e. no HTML, XML etc). Max length is 160 chars.
id – The database ID of the alert.
title – A title for the message, max length 30 chars.
signature – Currently not used. Supposed to be digital signature of the message, that clients can use to verify authenticity.
expireTime – The time the message expires. Epoch time (milliseconds).
author – The author’s name.
createDate – The creation date of the message. Epoch time (milliseconds).

Project Details