In shaunkhoo/ltaer: R Package for LTA's APIs

knitr::opts_chunk$set(
  collapse = TRUE,
  eval = FALSE
  )

1. Working with LTA Datamall's APIs

API Key

All API calls to the LTA Datamall, and thus all core functions in this package, require an API key. In layman terms, the API key is like a username/password with which you access the API. It helps the API developers to identify who is accessing the API, and to restrict access if they wish. As such, it is really important that you keep your API key private (don't share it with anyone else or post it online!).

As such, in order to use this package, please sign up for an API key here. The process is quick, easy and straightforward.

You will notice that in the examples provided below, my API key is saved as Sys.getenv('LTA_DATAMALL_KEY'). This is one way to keep the API key private, and you can find out more about how to do this here.

API Documentation

Finally, please read this vignette alongside LTA's documentation for their APIs, which you can find here. This will help you understand the outputs you are receiving from the APIs you are calling. By default, all functions in ltaer return all the data that the API returns, so you do not have to worry about missing out on any data from using this package.

Installing this package

This package is not available on CRAN (this is where you typically download R packages from when you run install.package('pkgname')). Due to a lack of time on my end, it is unlikely that ltaer will ever be made available on CRAN either. The only way you can get ltaer working on your RStudio is to use the following code:

install.packages('devtools')
devtools::install_github('shaunkhoo/ltaer')

This will download the ltaer package directly from my Github repository and into your RStudio. Thereafter, you simply load the package in the same way as any other package, by entering library(ltaer).

2. Bus Arrival Timings

Probably the most well-utilised API of the lot, the Bus Arrival API enables users to retrieve bus arrival timings for any bus stop in Singapore. There are some specific things to mention here about the API (you can also find this in the documentation):

• For each bus service serving that bus stop, the bus arrival details (timing, coordinates, type, load etc) are reported for the next three buses. If there are only one or two 'next buses' left (usually around 11pm-1am), then the bus arrival details for those 'next bus' slots will be NA.
• All bus services where the last bus has passed the chosen bus stop will no longer show up on the Bus Arrivals API for that bus stop. This usually happens around 12am-1am, except for NightRider services which end at 3am-4am.
• If there are no bus services at all, then the API will return an empty JSON file.

There are some important differences between this package's wrapper function, getBusTimings, and the API itself:

• getBusTimings automatically calls all the API for all bus services for a given bus stop code. In the API, you can specify which service you want to check for each bus stop. I've dropped this option as R users can simply filter for the bus service number.
• getBusTimings conveniently allows users to call the API for multiple bus stops. This is done by simply repeating the API call for all the bus stops specified. You simply need to pass in a vector of bus codes and getBusTimings will return you a dataframe containing all the data returned. The first column, BusStopCode, will help you distinguish between the various bus stops.
• getBusTimings requires you to pass the bus stop code as a character string, and not as a numeric value. This is to avoid potential issues when the bus stop code has leading zeros, which R truncates automatically for numeric values.

I provide an example below of the output you can expect from getBusTimings.

``` {r message = FALSE, warning = FALSE} library(ltaer)

bus_arrivals <- getBusTimings(c('07531', '09047', '11239'), api_key = Sys.getenv('LTA_DATAMALL_KEY'))

Note that I've transposed the dataframe (the columns are the rows and vice versa) for clarity of presentation.

knitr::kable(t(bus_arrivals[1:3,]))

## 3. Bus Services

This API returns service information for all buses currently in operation in Singapore. The data available here is similar to those you find on the information boards at each bus stop.

`getBusServices` is the wrapper function for this API, and takes in the API key as its only argument.

```r
bus_services <- getBusServices(Sys.getenv('LTA_DATAMALL_KEY'))

# Note that I've transposed the dataframe (the columns are the rows and vice versa) for clarity of presentation.
knitr::kable(t(bus_services[1:9,]))

4. Bus Routes

This API returns route information for all services currently in operation in Singapore. The data here is quite useful as they provide each bus stop code and stop sequence for each bus service, so you can plot out the full route for each bus service. While this is already quite useful, it would have been even better if route polylines were provided as well.

getBusRoutes is the wrapper function for this API, and takes in the API key as its only argument.

bus_routes <- getBusRoutes(Sys.getenv('LTA_DATAMALL_KEY'))

# Note that I've transposed the dataframe (the columns are the rows and vice versa) for clarity of presentation.
knitr::kable(t(bus_routes[1:9,]))

5. Bus Stops

This API returns information for all bus stops currently being serviced by buses in Singapore, such as bus stop codes, coordinates and road names.

getBusStops is the wrapper function for this API, and takes in the API key as its only argument.

bus_stops <- getBusStops(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(bus_stops[1:10,])

6. Passenger Volume (Buses)

There are two APIs here that you can call - the first is for passenger volume for each bus stop, and the second is for passenger volume for each origin-destination bus stop pair. Here are the two wrapper functions for the respective APIs:

• getBusPassengerVol(): Passenger volume for each bus stop
• getBusPassengerVol_od(): Passenger volume for each origin-destination bus stop pair

The wrappers for these two APIs require you to enter a date and your API key, and returns you the link which LTA provides to download the zipped CSV file of the data. Note that the date must be supplied in R's Date format - you can see this from the first example below. If you do not supply any date into the function, it will revert to the default of 60 days prior to the current date, as indicated in the second example.

getBusPassengerVol(as.Date('01-10-2018', format = '%d-%m-%Y'), Sys.getenv('LTA_DATAMALL_KEY'))

getBusPassengerVol_od(Sys.Date()-60, Sys.getenv('LTA_DATAMALL_KEY'))

7. Passenger Volume (Trains)

Similar to the APIs for buses, these APIs provide the same data but for trains instead. Here are the two wrapper functions for the respective APIs:

• getTrainPassengerVol(): Passenger volume for each MRT station
• getTrainPassengerVol_od(): Passenger volume for each origin-destination MRT station pair

getTrainPassengerVol(as.Date('01-10-2018', format = '%d-%m-%Y'), Sys.getenv('LTA_DATAMALL_KEY'))

getTrainPassengerVol_od(Sys.Date()-60, Sys.getenv('LTA_DATAMALL_KEY'))

8. Taxi Availability

This API returns the coordinates for all available taxis that are available for hire in Singapore (excludes hired and 'busy' taxis).

getTaxiAvail is the wrapper function for this API, and takes in the API key as its only argument.

taxi_avail <- getTaxiAvail(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(taxi_avail[1:10,])

9. Train Service Alerts

This API returns information about train service unavailability during scheduled operating hours - which refers to unexpected train service delays or breakdowns. Unfortunately (or otherwise...) I did not get a chance to test this fully since there were no train alerts whenever I called the API, but it should return all the information in a dataframe format.

getTrainAlerts is the wrapper function for this API, and takes in the API key as its only argument.

getTrainAlerts(Sys.getenv('LTA_DATAMALL_KEY'))

10. Carpark Availability

This API returns the number of available parking lots, as obtained from HDB, LTA, and URA carpark data. This covers almost all carparks in housing estates and quite a few carparks in the CBD area. Calling this API returns the coordinates and description for each carpark as well as the number of available parking lots.

getCarparkAvail is the wrapper function for this API, and takes in the API key as its only argument.

carpark_avail <- getCarparkAvail(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(carpark_avail))

11. ERP Rates

This API returns information about the Electronic Road Pricing (ERP) rates for all vehicle types across all timings and for all zones. Calling this API returns information about the ERP rate by vehicle type, timing, and zone ID.

getERPRates is the wrapper function for this API, and takes in the API key as its only argument.

erp_rates <- getERPRates(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(erp_rates))

12. Estimated Travel Times

This API returns the estimated travel times for each segment in the expressway - you will usually find this information displayed on the electronic billboards before entering major expressways in SIngapore.

getEstTravelTime is the wrapper function for this API, and takes in the API key as its only argument.

est_travel_time <- getEstTravelTime(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(est_travel_time))

13. Faulty Traffic Lights

This API returns alerts of traffic lights that are either currently faulty or undergoing scheduled maintenance. Calling the API returns information of the alarm ID, node ID, fault type, time of fault, expected end of maintenance, and message. Note that faulty traffic lights are fairly uncommon so you can expect the API to return nothing occasionally.

getFaultyTrafficLights is the wrapper function for this API, and takes in the API key as its only argument.

faulty_lights <- getFaultyTrafficLights(Sys.getenv('LTA_DATAMALL_KEY'))

14. Road Openings

This API returns information on all planned road openings, and provides data on the start and end dates, the department or company in charge of the road opening, and the name of the new road.

getRoadOpenings is the wrapper function for this API, and takes in the API key as its only argument.

road_openings <- getRoadOpenings(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(road_openings))

15. Road Works

This API returns information on all current or scheduled road works, and returns data on the start and end dates, the department or company in charge of the road opening, and the name of the road where work is being performed.

getRoadWorks is the wrapper function for this API, and takes in the API key as its only argument.

road_openings <- getRoadOpenings(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(road_openings))

16. Traffic Imges

This API returns links to images of live traffic conditions along the major expressways and Woodlands and Tuas checkpoints, as well as the coordinates of the traffic cameras.

getTrafficImages is the wrapper function for this API, and takes in the API key as its only argument.

traffic_images <- getTrafficImages(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(traffic_images))

17. Traffic Incidents

This API returns information about current traffic incidents happening on the roads, such as accidents, vehicle breakdowns, traffic diversions etc. The coordinates of the incident as well as a brief message are also returned from the API for each traffic incident.

getTrafficIncidents is the wrapper function for this API, and takes in the API key as its only argument.

traffic_incidents <- getTrafficIncidents(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(traffic_incidents))

18. Traffic Speed Bands

This API returns information on current traffic speeds on expressways and major arterial roads, and these speeds are expressed in speed bands.

getTrafficSpeedBands is the wrapper function for this API, and takes in the API key as its only argument.

traffic_speed_bands <- getTrafficSpeedBands(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(traffic_speed_bands))

19. VMS / EMAS

This API returns all traffic advisories about current traffic conditions that are displayed on the Electronic Monitoring Advisory System (EMAS) signboards along expressways and major roads, as well as the coordinates of each EMAS signboard.

getVMS is the wrapper function for this API, and takes in the API key as its only argument.

vms <- getVMS(Sys.getenv('LTA_DATAMALL_KEY'))
knitr::kable(head(vms))

shaunkhoo/ltaer documentation built on Sept. 6, 2020, 8:24 p.m.