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 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 in the example shown, 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.
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.
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:
And in the response, among the metadata associated with this Place, is the imageUrl to the live feed, the value in the key/value pair below:
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.