Unified API Part 2: LoT – Location of Things

Last week, I gave a brief overview of what’s in the API, and said that if something is on our website then it should be in our API.  Over the next couple of weeks we are going to take a look at some of the data in the API that you can use to build your own applications.

There are a few things to note before I begin going into specific data examples.  Firstly, 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, and anonymous access is throttled for fair use, so you may get a 403 response.

It is recommended for your own development you obtain an “app_key” and “app_id” by registering here.  Access to our API is free to all.  Append you unique “app_id” and “app_key” as querystring parameters to get dedicated, higher rate limits than anonymous.  If you need even high rate limits, send us a message using the portal. The data in these examples will be in JSON format, and it is recommended that you install a JSON formatter plugin in your browser, this will help you read the data returned.

This week we will focus on the “Location of Things”, in particular finding the location and other useful information about transport related things in London. Let’s start with stations and stops – you’ll need to take a look at this web page:

https://tfl.gov.uk/hub/stop/HUBKGX/kings-cross-st-pancras-international/?Input=King%27s+Cross+%26+St+Pancras+International

This example shows a map
This example shows King’s Cross station on a map, including other transport options nearby with bus stops and cycle hire docks also shown.


In particular let’s take a look at the map.  Here you will see that the map has highlighted:

  • King’s Cross Underground Station
  • King’s Cross Rail Station
  • Bus stops around King’s Cross
  • Bikepoints and bike availability near King’s Cross.

So how do we use the API to get the data for this page? There are several ways depending on what information you already know.

Searching for stops

Let’s assume you only know the name or part of the name, you need to look up Kings Cross.  Here is a method that will look up all “Stop Points” that contain the term “Kings.”

https://api.tfl.gov.uk/Stoppoint/Search/Kings

The data returned includes the StopId, the name, the latitude (lat) and longitude (lon) of the matching locations and the modes of transport supported by that location.  As you can see there are quite a lot of locations including “Barkingside Underground Station”.  We can filter this query by mode to narrow it down (note that you can specify a separated list of modes if you want to include more than 1 mode).

https://api.tfl.gov.uk/Stoppoint/Search/Kings?modes=tube

This results in a much shorter list, and you can see how the results could be used in “Autocomplete” functionality, or to present a drop down for a user to choose.

Retrieving stops and stations with facilities 

If the user chooses a station, we can use the “id” to get the data about that stop.

https://api.tfl.gov.uk/Stoppoint/HUBKGX

The data that is returned includes the facilities at the Stop, and the “lines” served by the stop (please note that for buses we still use “line” you can consider it a synonym for “bus route”).  You will also notice that it returns all of the associated stops.  In this example, it includes, the associated bus stops, national rail and underground stops with their lines and facilities and location.

The reasoning for this is that typically people think in terms of “stations”, “Kings Cross Station”, even if they are going to a bus stop just outside, and in this case the bus stop naturally inherits the facilities and services at the station next to it.  So you will see if you pick the id of a bus-stop from the above query, such as https://api.tfl.gov.uk/Stoppoint/490004722M, that the response is the same as the previous example.

Therefore, in summary, the https://api.tfl.gov.uk/Stoppoint/{id} method always returns all the data from the biggest entity associated with the id, and includes all of the ‘children’ of that entity.

Finding stops near a co-ordinate or in a bounding box

How about finding stop points near to a geographical co-ordinate, as demonstrated on the ‘Nearby’ web page:

https://tfl.gov.uk/maps?Input=Bank&InputGeolocation=51.513395%2C-0.089095

The Nearby map
The Nearby page on our site allows you to view stop points close to a specific geographical location on a map.

The Stoppoint method supports geographical queries expressed as a single co-ordinate and a radius or a bounding box.  Here is an example using a lat,lon co-ordinate:

https://api.tfl.gov.uk/Stoppoint?lat=51.513395&lon=-0.089095&stoptypes=NaptanMetroStation,NaptanRailStation,
NaptanBusCoachStation,NaptanFerryPort,NaptanPublicBusCoachTram

The “stoptypes” given in the example are the most common set of stoptypes suitable for most use-cases (NaptanMetroStation is “tube station”), however there are more stoptypes in the system. These are based on the Naptan standard definitions, and the list of stoptypes available is available here:

https://api.tfl.gov.uk/StopPoint/meta/stopTypes

Finding Stoppoint information for all stops on a line or bus route

What if you want to place all the stops on the Piccadilly Line or the 24 bus route on a map? To do this, we use the Line method, and request Stoppoint information, e.g:

https://api.tfl.gov.uk/Line/piccadilly/stoppoints

https://api.tfl.gov.uk/Line/24/stoppoints

These examples should give you a good start point for possible use-cases related to stops and stations, and we’d encourage you to take a look at the Stoppoint documentation on https://api.tfl.gov.uk for more detailed information on these and other methods for selecting and filtering stops.

Finding the locations of other things

What about the locations of other Transport things? The Unified API has a method “Place” for locating other Transport “things” that are not stoppoints, for example Jamcam locations:

https://api.tfl.gov.uk/Place/Type/JamCam

Or the location of Oyster Ticket Shops:

https://api.tfl.gov.uk/Place/Type/OysterTicketShop

Like Stoppoints, the “Place” API method also supports lat, lon and bounding box queries.  You can see a list of the Place Types available here:

https://api.tfl.gov.uk/Place/meta/placeTypes

What about Santander Cycles docking stations?

We have a separate method for “Bike points”, and this is because the bike points include availability information that is updated every 5 minutes so it’s worth refreshing the data regularly.  The following method returns all of the Bike points with locations and additional information including the number of docks and the number of bikes available.

Santander
Bike points data shows Santander Cycles docking stations on a map, including information on the number of bikes and empty spaces at each docking station.

Like the previous methods, Bike Points also support searching by dock name, and using lat,lon and bounding box queries.

 

22 Comments

    1. Hi Paul, are you looking for the arrivals at a particular stop? In which case yes, we do provide a way to minimise what you request. You can get the ids of all the StopPoints on a line (e.g. bus route 47) from https://api.tfl.gov.uk/Line/47/StopPoints and then the arrivals at one of those stops from https://api.tfl.gov.uk/StopPoint/490000021W/Arrivals.

      We will be covering how to subscribe to a push notifications of arrivals at a StopPoint using WebSockets in a future blog post, which can further reduce response sizes and the need for polling. Stay tuned!

      1. Hi Tim,

        Thanks very much for the quick response. The idea is to work out the arrival times of buses at each stop to do some number crunching so I still need to query all stops but was hoping to reduce the size of the overall response. The push notification feature however sounds very promising!

  1. How do I get xml back instead of JSON? I tried adding &format=xml to the examples, but that didn’t help (and I don’t have any control over the Accept header, if that’s the way I’m supposed to specify it).

  2. Hello,

    speaking of rate limit, I was wondering whether these were documented per API request type. On the unified API page (https://api.tfl.gov.uk/), the time shown below the GET label (5mn for /BikePoint for example) corresponds to the time between two refreshes of the dataset, and not the rate limit, if I understand correctly?

    1. @Ben yes the time shown on the API page is the TTL in the cache – so it’s the minimum time between refreshes of data. (You can see more detail about cache hits/misses and age etc. if you examine the HTTP headers in the response). As for quotas, I expected them to be listed on https://api-portal.tfl.gov.uk where you manage your developer account, but I can’t see them. @danmewett any ideas?

  3. I’m looking at the api documentation for /StopPoint/Mode/{modes} : Gets a list of StopPoints filtered by the modes available at that StopPoint.

    For buses, a page number is also needed — so presumably there ought to be a way to know how many pages there are, but I can’t find that specified.

    The whole lot is presumably quite large, and it also seems that we should obtain a fresh copy every day to keep up to date — though realistically, probably 99.9% of it isn’t going to change. For this and other large API data services, wouldn’t it be better to have an optional “changes since” date and use it to retrieve just the new / deleted / moved stops, to be merged with the existing data?

    1. Thanks Harry, I agree that the bus stop pagination could be improved and have added a ticket to our backlog for this. We don’t currently have any plans to support transmitting “deltas” for large data sets. Currently we’re thinking of using Amazon S3 buckets to store versioned data dumps of some of our more popular data sets. This will allow people to get the whole data set more easily and efficiently, allow for tracking of changes over time, and allow consumers to maintain synchronisation using one of the many S3-sync tools out there. We’ll let everyone know via the blog as our plans firm up in this area.

  4. Hi,
    I am new to TFL API and trying to develop a bus app for blind people. I have registered with the TFL and obtained an app_key and ID. I want to use data related to the bus such as bus route for all buses in London, arrival times and stops. According to TFL documentation, we should cache the API response and use our own proxy to connect the users. Can you please explain to me how to get all the data related to the bus?

    Thanks

Leave a Reply to pragin raj Cancel reply

Your email address will not be published. Required fields are marked *