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.

 

Posted by danmewett

Dan Mewett is a Solution Architect within TfL Online. Dan works with the Technical teams to design and deliver tfl.gov.uk, api.tfl.gov.uk and the cloud infrastructure on which it runs.

22 Comments

  1. Look very interesting…

    On a related note, where do you report TfL security problems to?

    I’m getting an problem reported (“This site uses a weak secuirty configuration SHA-1 signatures so your connection may not be private) with oyster.tfl.gov.uk as per this screenshot from my Nexus 5:

    Who should I tell?

    Like

    Reply

    1. Thanks Paul, we are aware of this issue and I’ve raised this again with our security team.

      Like

      Reply

  2. I just found out about the new API and would like to replicate the filter I currently use to minimise network traffic (i.e. excluding unnecessary information from the response). For example is it possible to replicate the result I currently get when calling the following: http://countdown.api.tfl.gov.uk/interfaces/ura/instant_V1?LineName=47&DirectionID=1&ReturnList=StopPointName,VehicleID,EstimatedTime,ExpireTime ?

    Many thanks
    Paul

    Like

    Reply

    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!

      Like

      Reply

      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!

        Like

    2. Ah you can get the arrivals for a whole Line too – although I’m not sure whether you’ll find the response to be smaller than the Countdown version: https://api.tfl.gov.uk/Line/47/Arrivals

      You can subscribe to arrival notifications for a whole line too. (Must get that blog written!)

      Like

      Reply

  3. Scot McSweeney-Roberts October 18, 2015 at 7:50 pm

    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).

    Like

    Reply

    1. Hi Scot, I’m afraid the accept header is the only method we support at present.

      Like

      Reply

    2. Hi Scot, my mistake – if you add &formatter=xml to the examples, you will get XML.

      Like

      Reply

  4. […] Part 2 of this series, Dan gave examples of finding the “Locations of Things” using the Unified API. This […]

    Like

    Reply

  5. […] As well as the road corridors themselves, TfL manages a large amount of on-street infrastructure: Red-light cameras, speed cameras, yellow-box junction cameras, variable message signs (VMS), traffic cameras etc. The positions, names and, in some cases, live data-streams of these are available from the API. The traffic cameras – also known as ‘JamCams’ are perhaps the most visually interesting – showing live photos (updated every two minutes) of key traffic intersections. All of these types of asset are available from the /Places API, which Dan described in Part 2. […]

    Like

    Reply

  6. […] 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 […]

    Like

    Reply

  7. 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?

    Like

    Reply

    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?

      Like

      Reply

  8. 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?

    Like

    Reply

    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.

      Like

      Reply

  9. 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

    Like

    Reply

  10. PROBLEM : The collected timestamp from the expected arrival data is one hour off, why is that?

    Like

    Reply

    1. Hi Marcus, the times are in UTC (hence the ‘Z’ suffix).

      Like

      Reply

  11. […] 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 […]

    Like

    Reply

  12. […] You can also use the “tram” line id to retrieve information about the tram routes, their timetables and to plan journeys. In these examples, we are using the StopPoint id for West Croydon, which we can find with a search. […]

    Like

    Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s