{ctar}

{ctar} is an R package designed to interface with the Chicago Transit Authority train tracker API. In order to use this R package you will need to apply for a key. Applications for an API key can be found on the CTA website.

CTA train tracker offers three APIs, the arrivals API, the locations API, and the Follow This Train API. This package has functions to interface with each of the three APIs.

Installation

You can install the released version of ctar from Github with:

library(remotes)
install_github("willdebras/ctar")

API keys

The functions for each of the three APIs have a key argument that defaults to an object called ctar_api_key. We can use the function argument to manually include the key, such as:

get_arrivals(route = "red", key = xxxxxxxxxxxxx)

Alternatively, we can assign the key to an object called ctar_api_key and leave the key argument blank, such as:

ctar_api_key <- xxxxxxxxxxxxx

The best method to store this key though is probably to set it to an environment variable and call it later, such as:

Sys.setenv(ctar_api_key="xxxxxxxxxxxxx")

get_arrivals(route = "red", key = Sys.getenv("ctar_api_key"))

You can also use a .Renviron file to have R automatically set the environment variable at startup. The package usethis can be handy for this.

usethis::edit_r_environ()

This will open a .Renviron file for you. Add a line like this, but substitute your API key:

ctar_api_key="xxxxxxxxxxxxx"

Save the file then restart your R session

get_arrivals(route = "red", key = Sys.getenv("ctar_api_key"))

Arrivals API

The arrivals API produces a list of arrival predictions for all platforms at a given train station. The arrivals takes a single argument of either a map id (a station) or a stop id (a station and direction combination).

We can reference these stop and station ids with the stop_ids dataset.

library(ctar)
data("stop_ids")

kable(head(stop_ids[1:6]))

Now we can get some basic data about arrivals with the get_arrivals() function.

arrivals_18th <- get_arrivals(route = "pink", stop = 30162, key = Sys.getenv("ctar_api_key"))

kable(head(arrivals_18th))

The response columns in the returned dataframe correspond with the response fields of the API. Detailed information about the response fields is below or available on the API website.

With this function, the route is optional. For stations with multiple routes, we can request data from all of the routes. For example, let’s use the station argument for the State/Lake stop so we get data from both directions and let’s call it without a route so we get data from all lines.

arrivals_lake <- get_arrivals(station = 40260, key = Sys.getenv("ctar_api_key"))

kable(head(arrivals_lake))

Locations API

The locations API produces a list of trains and their locations on a single L route. This function takes a route argument and a key argument to produce a list of all trains on that line. It acts similarly to the arrivals API without a stop or station id in providing coordinates, geospatial heading, train attributes, and next stop information.

locations_blue <- get_locations(route = "blue", key = Sys.getenv("ctar_api_key"))

kable(head(locations_blue))

Note on routes

The route argument in each function will try to match to the full name of the line. While the API accepts only specific calls for route like “Org” for orange, “Y” for yellow, or “Red” for red, the functions for the arrivals and locations APIs in this package will match “y”, “yellow” or “yell” for yellow. It will always accept the full color spelled out and will try to match abbreviations if they are unique. For example, it will not match “b” to blue or brown, but it will match “br” to brown.

Follow This Train API

The follow This Train API, or the “Follow the Damn Train, CJ” API, produces arrival predictions for a single train at all stations on its route until the end of its trip. This API requires a knowledge of run number associated with a train, which changes daily.

We can use information from the arrivals or locations APIs above to access run number and then get information on the single train. We can call query information about its anticipated arrivals.

run_104 <- get_train(run_number = 104, key = Sys.getenv("ctar_api_key"))

kable(head(run_104))

We can also singularly query information about its position.

run_104_position <- get_train_position(run_number = 104, key = Sys.getenv("ctar_api_key"))

kable(head(run_104_position))

Additional features and info

stop_ids dataset

The {ctar} package features a lot of additional data about individual stops found in the stop_ids dataset. A general explanation of the dataset can be found with the help command ?stop_ids. In addition to the main variables, the dataset contains the zip code, ward, and census track of each stop and station, as well as binary indicators about whether each line stops at these locations and if they are ADA accessible.

Using the Bus Tracker API

There are currently 5 functions implemented for getting data from the CTA Bus Tracker API:

• get_bus_tracker_system_time() - used to make sure your computer and the CTA server are in sync
• get_bus_routes() - returns a dataframe of all the CTA bus routes
• get_bus_route_directions() - returns a dataframe of the directions an individual bus route travels in
• get_bus_route_stops() - returns a dataframe with the locations of stops along an individual bus route with direction
• get_bus_location() - returns a dataframe with the last location of currently operating buses

Bus Tracker examples

Get the difference between my computer’s clock and the CTA Bus Tracker server clock

my_time <- Sys.time()
bus_time <- get_bus_system_time(key=Sys.getenv("ctar_api_key"))

paste("My time: ", my_time, ", Bus server time: ", bus_time)
#> [1] "My time:  2019-10-25 22:31:31 , Bus server time:  2019-10-25 22:31:32"

Get all the CTA Bus Routes and print out a handful

cta_bus_routes <- get_bus_routes()
sample_of_buses <- c(8, 12, 20, 49)

kable(cta_bus_routes[cta_bus_routes$rt %in% sample_of_buses, ])

Find out what directions a bus route travels

route_directions <- get_bus_route_directions(route = 8)

print(route_directions)
#>          dir
#> 1 Northbound
#> 2 Southbound

route_stops <- get_bus_route_stops(route = 8, direction = "n")

most_south <- min(route_stops$lat)
most_north <- max(route_stops$lat)

route_stop_ends <- rbind(
  route_stops[route_stops$lat == most_south, ],
  route_stops[route_stops$lat == most_north, ]
)

kable(route_stop_ends)

Find out where buses on a route actually are

bus_locations <- get_bus_location(routes = 8)

# Transpose just to make it easier to see all the columns
kable(t(bus_locations[1:3, ]))

API documentation

While the {ctar} package has data to reference stop and station ids and intuitively returns API error codes when you run into them, it can be useful to have readable tables explaining and documenting these. The CTA developer page contains reference to all of these tables and includes additional documentation of running individual queries outside of the context of this package.

Future plans

• Potentially adding the bus tracker and customer alerts APIs
• Allowing some fuzzy matching for station and stop calls for ease of use
• Unit tests/CRAN submission :^)

Issues

If you have an issue, feature suggestion, or question regarding use, feel free to open an issue here on github or tweet at me @_willdebras.