In Part 3 of this series, I gave examples of finding the ‘Routes of Things’ using the Unified API. This post will focus on roads – how to find and make use of the traffic, road disruption and planned works information on London’s road network.
We’re really keen for customers to check for disruption before they travel on all forms of transport, including the capital’s roads. Developers working with our Unified API have a really important role to play in developing products that meet road users’ needs. This is particularly important as we implement our Road Modernisation Plan – £4bn of investment in improving London’s roads – so planning ahead during these works is crucial for businesses and drivers across the city.
This means that the apps developers create will be meeting a genuine need, and we’re keen to make this process as easy as possible by explaining what data is available, how it can be used, and by taking feedback so we can make improvements.
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. It is recommended for your own development 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.
Let’s start with the most prominent example of the roads information, shown when viewing the Traffic status board.
The Traffic Status Board gives info on all TfL managed routes on the London road network
The API used for the status board is the /Road endpoint. This is built around the idea of a RoadCorridor entity, which represents a TfL managed route on the London road network. These are the main arterial road corridors in the city.
To retrieve all of the RoadCorridors and their status we use:
The response returns an array of all of the RoadCorridor entities, giving their names, geographical information, and their status (by default from now until midnight). Note also that, the corridor has a group of ‘Central London Red Routes’. We use this to show a single status for the corridors that make up this group. These statuses can then be sorted by their severity to produce the status board as shown above.
Other useful endpoints:
- https://api.tfl.gov.uk/Road/Meta/severities – gets a list of all of the possible ‘statusSeverity’ values, with an ordinal to help with sorting;
- https://api.tfl.gov.uk/Road/All/Status?startDate=2015-11-20T00:00:00&endDate=2015-11-20T23:59:59 – get the corridor status between future dates – for up to 12 months ahead;
- https://api.tfl.gov.uk/Road/A1 – get the status of just a single corridor (the one with id ‘A1’ in this case).
The majority of the information comes from the Traffic Information Management System (TIMS) but we also source planned road works, improvement projects and other upcoming disruptions from a variety of sources within TfL. TIMS is by far the largest and most detailed though, and is the only source that is realtime, has ‘affected area’ polygons, and details of each street affected. However, all sources are modelled as a generic RoadDisruption entity, to simplify the job for developers – they do not need to worry which source the disruption came from, only that the level of detail may vary.
Each RoadDisruption can be linked to a RoadCorridor e.g. the closure shown here on the A406 (North Circular)[/caption]
This is quite a large response, so I’ll summarise the information it brings back rather than show the JSON:
- The name, description and duration of the disruption, along with its unique ID
- An array of the affected street names, including the start and end lat/longs of those streets
- The centre point of the disruption (where the icon is shown above)
- A polygon showing the area of the disruption (the red-shaded area above)
- The severity of the disruption
- The corridors that this disruption affects
This is used to render the disruption on the map and display the summary information to the user. Because the disruption is a closure, it changes the status of the corridor to ‘Closures’. A corridor inherits the worst severity of any disruptions attached to it. If none of those disruptions are any worse than ‘minor’, we give the corridor a status of ‘No exceptional delays’.
Another way to query RoadDisruptions is by area or time – not all of the disruptions will necessarily affect a road corridor.
- https://api.tfl.gov.uk/Road/all/Disruption?lat=51.5&lon=-0.1&radius=500 – gets the disruptions within a 500 metre radius of the lat/long supplied
- https://api.tfl.gov.uk/Road/all/Disruption?startDate=2015-12-01&endDate=2016-12-01 – gets the disruptions between the two dates supplied across all of London
- https://api.tfl.gov.uk/Road/all/Disruption?neLat=52.5&neLon=0&seLat=51.5&seLon=-0.1&startDate=2016-02-01&endDate=2016-03-01 – the date and lat/long filters can also be combined, or used to describe bounding boxes
- You can append &format=geoJson to any query string to return the results in geoJSON format
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.
The positions, names and, in some cases, data-streams from a large amount of on-street infrastructure is available through the Unified API
To get a list of all of the types available, we use the /Places/Meta endpoint, which tells us we need to search for Places of type ‘JamCam’. For example, to request all of the JamCams in a given radius we would use:
Nothing but green lights
Using the roads data in the Unified API, it’s possible to easily navigate real-time data about the surface of the city, and look ahead to future dates for planned works that may cause disruption. This is the same data that TfL Surface Operations use to manage the roads, so we hope that developers can help find innovative ways to make that job even easier. The RoadDisruptions could be used to a build a push-messaging application, for example, to notify customers of upcoming delays to their planned roads.
We are adding new data fields all the time – live JamCam video and tube station car parking availability are coming soon. Please check our legacy data sets too, we have the location and limit on every speed limit sign within the M25, and road disruptions aggregated by postcode area, to name a few. If these prove popular, we’ll add them to the API too.
We’d love to find out what you’re building with this data, what is most useful to you and if you feel that anything important is missing from the Unified API. Please do let us know what you think, or ask any questions you have on roads data in the comments below.
Hello, does the Unified API provide live road traffic data ?
Unfortunately at present we don’t directly provide live traffic data. Our most real-time source, TIMS, indicates where disruptions (road works, planned closures, incidents) are on the road network, so there will be some correlation between those and the traffic in the streets around them (the “affected area” polygon shows this). However, rush-hour traffic, for example, would not be listed as a disruption.
A little glitch – found duringing a browse around the traffic, etc pages:
status pages -> national rail status updates -> plan your journey…
I hit an invalid certificate lurking (evidently long expired) for crwdcntrl.net –
… picked up by Safari
(Perhaps this isn’t part of the live system … in which case apologies…)
Thanks for spotting this Theo – it looks like it’s related to advertising on the page. I’ve raised this with our security team.
I have an idea for a new app for the TfL website making use of several of the data feeds – my idea is that combining the bus location data with geographic data should enable the current speed of buses to be calculated. Bus location from the on board GPS does not appear to be available via the API at present. Having calculated the average speed from preceding buses this can be used to predict what time a bus will arrive at a selected destination. At present one can get some idea from Google Traffic but I don’t think that allows for bus lanes and bus stops. Having this available via an app would enable passengers to make a more informed choice of wether to stay on the bus or get off and use an alternative. It would be of most value in the congested parts of London and at peak times when bus journey times can get very extended. The HMI would have to be designed to be as responsive as possible to changes of traffic speed. Additional speed information can be obtained from other bus routes that share the same roads.
That’s a great idea John, and we have built similar proof-of-concepts internally when working with the raw GPS data. I’ll pass a query on to the data team to see where we are with making the data publicly available.
If you want a route to try it on use the 521 – Journey times are very variable mostly due to chaos in Cannon Street. If you can get accurate destination arrival times for that route particually east bound in the evening peak you will be doing well. The customer information at present both Countdown and Train arriival information is really quite limited – what people want to know is when they will reach their destimnation particually if they are connecting with an infrequent national rail train, worse still if you have booked a particular train or have a flight to catch. Journey Planner has a stab at this but a real time system would be a lot better ! However on the underground we would need connectivity though updates as your reach each station and connect to the wi-fi might work.
I want to consume this feed in Java and need to request the data in XML. Is there any XSD I can use to generate my DTOs?
I see you have DTOs for .NET here (https://api.tfl.gov.uk/), do you have any available for Java?
Hi Franciso, I’m afraid we don’t have anything for Java at this time, although you may be able to generate an XSD from the .NET assembly using xsd.exe or similar. We are working on a proper Swagger specification which will support client generation for multiple languages and platforms – watch this space.
Hi Francisco – we now have a Swagger specification available at https://api.tfl.gov.uk. You should be able to use it to generate a Java client and/or the DTOs.
That’s wonderful news. Thanks Tim.
Hi Tim – the Swagger specification that you provide does not include a definition for DisambiguationResult, which makes it tricky to fully understand the responses from /Journey/JourneyResults. Is this definition available somewhere else?
Hi Tim, some of the responses bring back coordinates for more than one polygon. The first polygon seems to be the red disrupted area, but in some cases there are coordinates for one or more additional polygon shapes – what do these extra shapes represent?