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 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:

https://api.tfl.gov.uk/Road/all/Status

  [
    {
       "id": "southern river route",
"displayName": "Southern River Route",
"group": "Central London Red Routes",
"statusSeverity": "Good",
"statusSeverityDescription": "No Exceptional Delays",
"bounds": "[[-0.2211,51.47224],[-0.02438,51.5319]]",
"envelope": "[[-0.2211,51.47224],[-0.2211,51.5319],[-0.02438,51.5319],[-0.02438,51.47224],[-0.2211,51.47224]]",
"statusAggregationStartDate": "2015-11-18T14:28:47.9712196Z",
"statusAggregationEndDate": "2015-11-18T23:59:59Z",
"url": "https://api-prod6.tfl.gov.uk/Road/southern+river+route"
    },
//etc...

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:

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.

Generic RoadDisruption entities can be linked to a RoadCorridor e.g. the Closure shown here on the A406 (North Circular)

Each RoadDisruption can be linked to a RoadCorridor e.g. the closure shown here on the A406 (North Circular)

https://api.tfl.gov.uk/Road/All/Disruption/TIMS-81012

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.

Automatic stop

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

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:

https://api.tfl.gov.uk/Place?lat=51.5&lon=-0.1&radius=500&type=JamCam

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:

"commonName":"London Rd/Thomas Doyle St",
"distance":343.70734925748695,
"id":"JamCams_00001.03611",
"lat":51.497986,
"lon":-0.103761,
"placeType":"JamCam",
"additionalProperties": [
{
 "category":"payload",
 "key":"imageUrl",
 "modified":"2015-11-16T00:34:40.787",
 "sourceSystemKey":"JamCams",
 "value":"/tfl/livetravelnews/trafficcams/cctv/0000103611.jpg"
}
// etc...
 

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.

Posted by Tim Williams

Lead Developer on the Transport for London Unified API

18 Comments

  1. […] the last post on this blog, Tim introduced the roads data available in our unified API, describing its importance as we encourage road users to check before […]

    Like

    Reply

  2. Hello, does the Unified API provide live road traffic data ?

    Like

    Reply

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

      Like

      Reply

  3. 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 –
    https://bcp.crwdcntrl.net/
    … picked up by Safari
    (Perhaps this isn’t part of the live system … in which case apologies…)
    Theo

    Like

    Reply

    1. Thanks for spotting this Theo – it looks like it’s related to advertising on the page. I’ve raised this with our security team.

      Like

      Reply

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

    Like

    Reply

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

      Like

      Reply

      1. Tim,
        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.
        John

        Like

  5. […] Part 4 of the series on the Unified API on this blog, Tim discussed TfL’s roads open data and gave guidance on how to build apps […]

    Like

    Reply

  6. […] Part 4 of the series on the Unified API on this blog, Tim discussed TfL’s roads open data and gave guidance on how to build apps using […]

    Like

    Reply

  7. […] my previous post on Roads Open Data I outlined the importance of providing quality data for London’s roads, particularly at a time […]

    Like

    Reply

  8. […] its real-time network management and open data offering. (You can read about our roads open data in this post on our Unified API as well as in this post, describing recent improvements we’ve made to this […]

    Like

    Reply

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

    Thanks.

    Like

    Reply

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

      Like

      Reply

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

      https://api.tfl.gov.uk/swagger/docs/v1

      Like

      Reply

      1. That’s wonderful news. Thanks Tim.

        Like

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

        Thanks.

        Like

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