Developer documentation

Case studies

The Bus Open Data Service (BODS) is an online service that provides access to UK bus company data.

All the data on the service has been published by the bus companies themselves. There are 3 types of data available on the service:

  • Timetables data
  • Bus location data
  • Fares data

This guide has been created to show a simple example of how to use the BODS API. For this case study, we will demonstrate how to download an individual dataset from one of the operator companies on BODS via the API.

Setting up

To start using this guide, you will need:

  1. A Postman account
  2. An API key

Postman account

This guide uses Postman to download the data. Go to Postman and sign up (for free) if you don't already have an account.

API key

Next you need an API key for BODS.

If you don't have an account on BODS, you can create one at Create account .

Sign in to BODS at Sign in .

In the top right, click My account > Account settings

Account settings

Your API key is shown in the settings. Make a note of it.

Download dataset

Find BODS datasets

In order to download the dataset you’re interested in, you need to find its Dataset ID.

The starting point for finding this is the data catalogue.

Here’s how to download it.

Type the URL https://data.bus-data.dft.gov.uk/catalogue/ into the address bar of a web browser such as Google Chrome, hit Return and save the resulting .zip file.

Chrome address bar

Unlock the .zip file. The unzipped folder will contain a file called overall_data_catalogue.csv.

Open this file in Excel (or equivalent) as a comma-separated file; be careful not to specify any other separators, such as semi-colon.

The spreadsheet that opens lists all the datasets for each operator.

The column called Operator lists the name of the bus company that published the data.

The column Dataset Type lists the type of data in each dataset, which will be one of:

  • Timetables
  • Automatic Vehicle Locations (i.e. bus location data)
  • Fares
Data catalogue

First, browse or search these two columns to find the data type from the operator you're interested in.

Then use the Data Set/Feed Name column to find the name of the dataset you want to download.

Get the Dataset ID from the Dataset ID column.

Data catalogue

Download

Now that you have the Dataset ID you can download the dataset in Postman as follows.

Go to Postman and create a new request:

  1. Set the request type to GET
  2. Set the URL according to data type:
    • For timetables data, use https://data.bus-data.dft.gov.uk/api/v1/dataset/{ID}/
    • For bus location data, use https://data.bus-data.dft.gov.uk/api/v1/datafeed/{ID}/
    • For fares data, use https://data.bus-data.dft.gov.uk/api/v1/fares/dataset/{ID}/
    where {ID} is the Dataset ID
  3. Set a param with key api_key and value equal to your API key
  4. Click Send
Postman request

The response is different for each of the three data types. The following section gives a synopsis for each type.

Interpreting the response

Timetables and fares data

For timetables and fares data, the response is a JSON text file that describes properties of the dataset pertinent to BODS.

To get more information, use the url parameter to download the original dataset uploaded by the bus company.

Postman response
  1. Click on the value of url in Postman
    • This creates a new Postman request
  2. Set the request type to GET
  3. Click "Send and Download" from the "Send" dropdown
  4. Save the file to disk
    • The file will either be a .zip or a .xml file
  5. Open the file with an appropriate application

Bus location data

For bus location data, the response from the dataset query comprises a SIRI-VM XML file describing the data feed. It looks like this:

Postman response

Other development resources