Documentation for BBC News Labs APIs & #newsHACK events
The Travel service is a HTTP API that allows you to discover real-time travel incidents throughout the UK. The Travel API can be queried by location, post code district, BBC News region or public transport operator.
A travel incident entity is either a road, rail, light rail or ferry event with the potential to disrupt a person's journey. Each travel incident has a set of properties such as id, summary, severity, mode, type, statues (live or planned), locations, start time, stop time and update time.
The summary provides a description of the location, cause and impact of the incident is having on the surrounding area.
The severity provides context to the scale of impact. The severity will have one of the following values:
The mode describes the mode of transport the event is affecting. The mode will have one of the following values:
The type describes the type of event occurring. For example, a road incident can be of type 'roadworks', 'accident', 'congestion' or 'disruption'.
The statuses lists the current state of an event. A planned incident is one that is not currently occurring (e.g. planned engineering works on the rail network). However, a planned incident can become live when the roadworks or engineering works start.
A travel incident can have one or two locations. Each location has a latitude, longitude, qualifier and a set of descriptors. The qualifier helps describe the relationship between the locations (e.g. 'Between', 'And', or 'At') whilst the descriptors provide information such as road name and town name. The descriptors vary based on the type of incidents.
Rail and Light rail incidents have additional properties such as their operator (e.g. TfL).
We provide mechanisms by which you may discover incidents (e.g. location, post code district, BBC News region or public transport operator).
Locations within the Travel API are closely linked to the locations in the Locator API. Querying the Travel API by location will return a summary of location and all travel incidents occuring at this location. The location in the response contains the properties such as id, latitude, longitude, name, container. In addition to these properties some locations have nearby rail stations, light rail stations and ferry ports. Stations and ports have a unique code and name.
If you install the free Postman REST Client you can import the Travel API into using this URL:
This allows you to easily try out the API and explore how it works without writing any code.
You will need to configure an "Environment" within Postman to be able to make calls. You will need to set a host parameter with value http://data.bbc.co.uk/ and an apikey.
Used to discover incidents for a location
The location is passed to the Travel API in the URL. In the sample URL we've denoted named this
location_id. The location_id parameter can either be a Geoname ID or a post code. The Geoname ID can be obtained from the Locator API. We've compiled a list of sample list of locations within the UK but locaations can be dynamically retrieved from the Locator API.
Allows you to ask for incidents occurring within a BBC News region.
The BBC News region is passed to the Travel API in the URL. In the sample URL we've named this
news_region. We've made available a list of BBC News regions in the Travel API. BBC News regions are also available from the Locator API.
Allows you to ask for incidents occurring for a public transport operator
The public transport operator is passed to the Travel API in the URL. In the sample URL we've named this
operator, we've made available the full list of available operators.
All comments are moderated for approval.