TfL Unified API Part 1: Introduction

TfL have been a leader amongst Transport and Government departments in the provision of free and open data to the public, and actively encourage the use of data by 3rd party developers across multiple application domains, with a data subscriber database of 5000+ registered application developers and organisations.

With the use and integration of TfL’s Open data, developers have produced a wide and varied selection of mobile and desktop applications, spanning the fields of travel and trip planning to historic city data analysis and mining. As an early adopter of the Open Data initiative (particularly within transport), TfL has provided Open Data since 2007.

What’s the Unified API?

Due to the complex organisational structure and diverse use of technologies across TfL’s technology estate, the previous Open data provision spanned a large spectrum of quality, accuracy and data formats making it complicated for application developers to be multi-transport-mode applications. TfL’s new unified API aims to make accessing the key public information across all modes of transport simpler.

Its aims are:

  1. Unification of the the data for modes of transport into a common format and structure (common (canonical) data model)
  2. Live & Web scale – The Unified API is designed for applications to use in real-time and at high volume
  3. Low latency
  4.  Support common web and data formats – The Unified API supports output in both XML and JSON format.
  5. Supportive of future change whilst minimising end-user (developer) impact.
  6. Metered and managed

Read more about the aims and benefits here.

What data is in the Unified API today?

The API supports all the data requirements of the tfl.gov.uk website. Every data driven aspect (including maps) of the tfl.gov.uk website is powered by the Unified API.  If you can see it on our website it should be in the API.

The following table highlights some of the core datasets included and available to developers now.

Additionally the API supports an extensive places capability for looking up and matching locations by name, postcode etc, It also includes cycle hire data. Other datasets are also available for Cabwise, providing locations of registered taxi firms and Webcat, which includes modelling information on transport, such as travel times between locations.

In Part 2 of this post, I’ll discuss how to use the API, along with more detail on how the API works.

29 Comments

    1. Hi Briantist,

      Yes, London Overground is included, here are some examples:

      Stops with name, location and facilities:
      https://api.tfl.gov.uk/Line/london-overground/stoppoints

      Route Sequence and geometry line string:
      https://api.tfl.gov.uk/Line/london-overground/route/sequence/outbound

      Service arrival predictions:
      https://api.tfl.gov.uk/london-overground/arrivals

      There is full set of station data which includes lat/lon and facilities:
      https://api.tfl.gov.uk/Stoppoint/mode/tube
      https://api.tfl.gov.uk/Stoppoint/mode/dlr
      https://api.tfl.gov.uk/Stoppoint/mode/tflrail
      https://api.tfl.gov.uk/Stoppoint/mode/overground
      https://api.tfl.gov.uk/Stoppoint/mode/river-bus

      (mode/bus isn’t working at the moment, we are fixing that, but you can get stops on a any bus route using the line syntax, e.g. 24 bus is http://api.tfl.gov.uk/line/24/Stoppoints use https://api.tfl.gov.uk/line/mode/bus to get a list of bus routes)

      You can also do a free text style search e.g. for stops , e.g. “Bank”

      https://api.tfl.gov.uk/Stoppoint/search/bank

      Or limit the search by mode, e.g tube and bus

      https://api.tfl.gov.uk/Stoppoint/search/bank?modes=tube,bus

      I hope this helps.

    1. Hi Richard,

      There have been discussions on this, but at the moment I am not aware of any concrete plans to do this in the near future. If we have any news on this in the future, it will be posted here.

    1. Our Open Data is provided free of charge to anyone who wants to use it.
      We generally provide data that originates from within TfL’s operational systems.

      We do have collaborative discussions with other data providers about how their systems can use our data. Our goal is to deliver accurate real time travel and public transport information through as many channels and applications as possible.

  1. We were pointed to the API via an FOI request for historic and current origin/destination information for our part of London.

    There doesn’t seem to be any information available on how we might access this data in a useful format or if it exists at all.

    Can you speak to the availability of origin/destination information through the API?

  2. One problem I have consuming the API is that it’s very hard to find example outputs of it in different states. For example, to test the /StopPoint/Mode/{}/Disruption endpoint you need to wait until there is a disruption. It would be great if you could add a property that allows us to generate random but valid (perhaps historic) outputs to test our apps.

    1. Hi Rob, yes that is a problem, and is something we have a test instance internally for – a system where we mostly have the data feeds set up for catastrophic disruption across the whole network, which we then use for strike/snow-day load testing. If there’s sufficient developer appetite we could look at making that available externally. I’ll pass this idea on to our lead Architect.

      1. I can think of 2 low-effort alternatives to publishing a whole new set of end points:
        1. publish sample JSON responses for options e.g. lines, modes, routes etc.
        2. publish the full model “schema” for all JSON responses.

        a third option might be to add a dummy line with stops and have it always have disruption.

        any of these would really help.

  3. Hi there,

    I have noted that sometimes when we fetch data to build the XML files from TfL for our journey planner, we miss some routes (tube / bus) and we patched it by using previous days’ XML files where the data is still relevant (eg. timetables for a week out and the week has not passed). However we noted some real bugs in the data which we have no way of fixing as they happen all the time — what do we do in such case? We have go over all data errors we found with you over the phone or email in detail but a persisting error is having Circle Line trains going via Hammersmith Westbound onto the stations and routes of District Line. This is clearly a bug… why would there be circle line data in Hammersmith and other District Line stations?

    Can you help!?

    Thanks so much…

    1. Caroline,

      Regarding the Circle line train issues, are you referring to timetable data or real-time data?

      Some Circle and/or H&C trains stable (park up) at depots that are reached via the District line (Ealing Common and Upminster come to mind). If they show on timetable data, then it’s because the timetable shows that train as going there. If it’s real-time data, I think it’s down to how the driver sets the train up (they may leave it as ‘Circle Line to Ealing Common’ or may reset it to ‘District Line to Ealing Common’.

      Hope this helps and E&OE,

      Simon
      (Not a TfL bod)

  4. Dan,

    How can I get an ETA of a bus from the unified feed? Unlike the legacy API, there doesn’t seem to be a way to query a particular vehicle unless I’m missing something?

    TIA

    Simon

    1. Hi Simon,

      At the moment the unified API supports getting arrivals (predictions) information for a Stoppoint, line or mode, e.g. For stoppoint it gives the estimated arrival time of buses travelling towards a stop, this is all buses on all routes that service that stop. This information includes the vehicleId (number plate for buses). You can also get arrivals information for all vehicles that are on a particular line (bus route), e.g. this query gives you the arrivals time for the all the buses on route 24 https://api.tfl.gov.uk/line/24/arrivals this also includes the vehicleId. If you wanted to track a particular bus, you have the information in the line query to be able to say when the bus will arrive at each of the stops in front of it for the route it is traversing.

      If you want to understand the sequence of bus stops, you can use this query https://api.tfl.gov.uk/line/24/route/sequence/outbound (there is an inbound version of that too). If thhese endpoints don’t solve your problem, please let me know if another endpoint would be useful, and what you would expect it to have as an input/output?

      Thanks
      Dan

      1. Dan,

        I’m a passenger on a bus, I want to know how long the bus will take to get where I’m going (and I know Countdown has a 30 minute limitation). I open my smartphone and into my bus app I type ‘ETA LG52XYJ’. The app’s backend, using the legacy URL would post something like “http:///interfaces/ura/instant_V1?RegistrationNumber=LG52XYJ&ReturnList=LineName,LineID,VehicleID,RegistrationNumber,StopPointName,StopCode1,StopCode2,DestinationText,DestinationName,EstimatedTime” and get back something like the below which the backend would then sort into either ‘EstimatedTime’ order (with the possibility of stops being slightly out of order) or Stop order (which it already knows & with the possibility of the arrival times being slightly wrong).

        [4,”1.0″,1461777201555]
        [1,”St Donatts Road”,”47876″,”490012652S”,”172″,”172″,”Brockley Rise”,”Brockley Rise”,16150,”LG52XYJ”,1461778771000]
        [1,”Millmark Grove”,”47079″,”490009913S”,”172″,”172″,”Brockley Rise”,”Brockley Rise”,16150,”LG52XYJ”,1461778861000]
        [1,”Peckham Park Road”,”51530″,”490010880EN”,”172″,”172″,”Brockley Rise”,”Brockley Rise”,16150,”LG52XYJ”,1461777740000]
        [1,”New Cross Bus Garage”,”47366″,”490010204G”,”172″,”172″,”Brockley Rise”,”Brockley Rise”,16150,”LG52XYJ”,1461778279000]
        [1,”Malt Street”,”71447″,”490009531E”,”172″,”172″,”Brockley Rise”,”Brockley Rise”,16150,”LG52XYJ”,1461777602000]
        [1,”Old Kent Road / Ilderton Road”,”51870″,”490008461E2″,”172″,”172″,”Brockley Rise”,”Brockley Rise”,16150,”LG52XYJ”,1461778059000]
        [1,”Dunton Road”,”72792″,”490006266EC”,”172″,”172″,”Brockley Rise”,”Brockley Rise”,16150,”LG52XYJ”,1461777429000]
        [1,”Briant Street”,”87898″,”490003246F”,”172″,”172″,”Brockley Rise”,”Brockley Rise”,16150,”LG52XYJ”,1461778146000]

        Now, using the unified API, the app’s backend would post “https://api.tfl.gov.uk/Mode/bus/Arrivals?count=1” (with credentials) and get back far more data (9MB at 19:00 as I type). It would then have to filter that to find only the bus our user is interested in, sort it and then present it back to the user.

        If the unified API could do something like “https://api.tfl.gov.uk/Eta/Bus/vehicleId/LG52XYJ” or maybe “https://api.tfl.gov.uk/Eta/Tram/vehicleId/2550” if we want to check a tram’s ETA. (Are vehicleIDs unique across modes in the unified API? If so, might rule out the need for /tram/ or /bus/.)Alternatively, “https://api.tfl.gov.uk/Mode/bus/Arrivals?vehicleId=LG52XYJ”.
        I did consider searching for vehicleId under ‘Line’ or ‘StopPoint’ but then we’d need to know what route the vehicle was on before we could search for it.
        The output I would hope to see from a query like this would be like the return from “https://api.tfl.gov.uk/line/172/arrivals” or “https://api.tfl.gov.uk/Mode/bus/Arrivals” but restricted to the vehicleId we’ve searched for and maybe slimmed down… do I need to know the bearing of the stop, the ‘towards’ information (e.g. “Towards Waterloo, Trafalgar Square or Holborn”) or the direction (inbound/outbound)?

        BTW, Are there any plans to remove the legacy Countdown feed any time soon? I hope not – It seems far more flexible in what you can ask it and ask it to present on return (i.e. don’t give me the information I don’t need) than what you can do with the unified API.

        Simon

  5. Hi Simon,

    Thanks for providing a very detailed description of your use case and expectations for an arrivals end-point based on vehicleid. I can see that such an interface would provide apps the ability to give customers really useful information on their journey, especially if you are trying to meet someone or catch a transport connection further down the route. On our “Arrivals of things” blog post, other users are also asking for the same functionality, and according to Tim (see the comments section) we have already got a version of this in our development pipeline, so you can expect something to show up in the API for this very soon and we will let you know when that happens.

    Here is a link to the blog article: https://blog.tfl.gov.uk/2015/12/07/unified-api-part-5-aot-arrivals-of-things/

    There are plans to make some changes to the web and mobile interfaces of Countdown in the near future (June) but currently no plans to change access or outputs of the existing Countdown API.

  6. Is there any develoepr support for this API? I have not found any way to contact or have questions answered yet.
    PLUS: your StopPoint sometimes returns Arrays, sometimes returns Dictionaries when asking for JSON parse. Feels inconsistent.

    1. Hi Marcus, the best ways to get help would be to ask questions on relevant posts on this blog and the author will get back to you or alternatively, you can send us a message through the TfL API Portal (https://api-portal.tfl.gov.uk). We are currently investigating ways to make it easier for developers to communicate with us, including the potential for creating a forum. Any developments will be announced on this blog when they are available.

Leave a Reply to Simon Cancel reply

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