In Part 3 of this series, I gave examples of finding the Routes of Things using the Unified API. This article focusses on the “Arrivals of Things” – how to find out when services are going to arrive on those routes.
As before, all of the API examples in this page are live, however they do not include API authentication tokens. This means that if you follow the link as is, you will be using anonymous access, which is throttled for fair use, so you may get a 403 response. We recommend for your own development that you obtain an “app_key” and “app_id” by registering here. The data in these examples will be in JSON format, so installing a JSON formatter plugin in your browser will help you read the data returned.
Ride on time
Let’s start with the most prominent example of arrivals, shown when viewing a nearby stop:
The API used for the arrivals board is the Arrivals detail on the StopPoint entity. So if you know the StopPoint id (which is a NaPTAN code) you can quickly get the arrivals of all services (Dan gave lots of tips on how to find StopPoints and their ids in Part 2 of this series – you’ll also see them in URLs as you navigate stop pages). This API can also be filtered by mode and line, which is useful for busy transport hubs that serve lots of routes.
“stationName”:”Haggerston Station / Downham Road”,
“towards”:”Aldgate or Old Street”,
The response tells us a number of useful pieces of information. We get the Platform-level StopPoint id and platform name, so we know exactly which platform this service will arrive at (for a simple bus stop as above, there is usually only a single “platform”, but at a bigger bus station or tube station, this can be used to retrieve additional information about the platform e.g. accessibility).
Most importantly, we get the time-to-station in seconds, and the expected arrival time in UTC. The API also provides a time-to-live, which indicates how long this prediction is valid for.
Train in vain
Let’s also look at a Tube station, to demonstrate how the unified API uses the same concepts across all modes.
The Unified API uses the same concepts for arrivals across all modes – this is an example for a Tube station.
“destinationName”:”Morden Underground Station”,
“platformName”:”Southbound – Platform 2″,
“stationName”:”Old Street Underground Station”,
“towards”:”Morden via Bank“,
The response is very similar to the bus example – giving the same arrival time, platform and service information. With tube, additional information on the current location of the train is available. Unlike the bus example though, the vehicleId for a tube service is dynamically generated for the service. Developers should note that while train running numbers are usually unique (for each line) it is quite possible to have more than one train with the same timetable number in service during times of disruption. Some will also disappear when they enter depots or sidings as this data only shows trains ‘in passenger service’. (Hat tip: commenter John Murrell).
The API can also be used to get the arrivals for a whole line or service:
- https://api.tfl.gov.uk/line/victoria/arrivals – All the arrival times on the entire Victoria line;
- https://api.tfl.gov.uk/line/243/arrivals – All the arrival times on the 243 bus route.
So if you really want to work out if buses really do travel in groups of threes, this is the API for you!
Time is on my side
I’ve demonstrated how easy it is to get the current departure times, so it should be easy to build a live departure board of the sort seen at bus stops, tube platforms or on our website. To keep the board up-to-date, a naïve approach would be to regularly poll the API to show the user the latest information as their service approaches. But this would waste a lot of bandwidth on mobile devices, especially where the information hasn’t changed since the previous API call. It’s also inefficient for our API to serve: the data is difficult to cache because it’s constantly changing, and each group of users at a stop will want slightly different information. Our usual strategy of Varnish caching with horizontal scaling doesn’t really work.
A more efficient approach is to subscribe to notifications of the arrivals, which we call predictions. The Unified API provides a SignalR hub for predictions, where developers can subscribe to a line or stopPoint. They are then pushed notifications using whichever mechanism the SignalR client determines is the most efficient. Usually this is web sockets, falling back to long-polling on older browsers. The initial subscription and subsequent notifications can be seen if you open the developer tools on your browser.