Getting started

Once you have registered for an account, you will be able to generate the API keys that you will need to access the API.

API is located at api.bt-hypercat.com.

API Overview

The Developers' API is REST-based and can be accessed by issuing HTTP GET requests. All usage is measured in hits of the API, including where access is free. The vast majority of API methods correspond to a usage of one hit; methods where this does not apply are clearly marked in the documentation.  You will need to construct a URL appropriate to the dataset you're interested in and the particular information you want to retrieve. In general, there are four URL patterns for GET requests:

Path Returns
1 /sensors/feeds/{feed ID}
/events/feeds/{feed ID}
Metadata about the feed and streams, with current values if available.
/locations/feeds/{feed ID}
/geo/feeds/{feed ID}
Metadata about the feed.
2 /locations/feeds/{feed ID}?near={lat},{lng},{radius}
/locations/feeds/{feed ID}?bbox={west lng},{north lat},{east lng},{south lat}
/geo/feeds/{feed ID}/features?near={lat},{lng},{radius}
/geo/feeds/{feed ID}/features?bbox={west lng},{north lat},{east lng},{south lat}
Search for items in a location feed. Values for near and bbox in the query strings are defined below.
3 /sensors/feeds/{feed ID}/datastreams/{datastream ID}
/events/feeds/{feed ID}/datastreams/{datastream ID}
Metadata about the stream, with the latest value and timestamp if available.
4 /sensors/feeds/{feed ID}/datastreams/{datastream ID}/datapoints
/events/feeds/{feed ID}/datastreams/{datastream ID}/events
The most recent data points or events from the past 24 hours, up to 50 as available.
/sensors/feeds/{feed ID}/datastreams/{datastream ID}/datapoints?{refinement parameters}
/events/feeds/{feed ID}/datastreams/{datastream ID}/events?{refinement parameters}
Data points, selected according to the refinement parameters.

Request

You can make test API requests by using a program such as curl: include the username option -u followed by your key with a : appended to indicate the password is an empty string: curl -u {your API key}: http://api.bt-hypercat.com/{type}/feeds/feed ID
Where {type} is replaced with one of supported types:
  • events
  • locations
  • sensors
  • sensors2
  • journeys

Request Parameters

When requesting data points (as opposed to metadata) you can also add URL parameters if you want to return something other than the last 50 data points. Some parameters are particular to one or more feeds so see the feed page for the detail. The general parameters are outlined below.
Parameter Value Default Example
start ISO8601 date and time None 2015-05-07T12:52:00Z which represents 12:52pm GMT on 7 May 2015
end ISO8601 date and time None 2015-06-17T08:54:00Z which represents 8:54am GMT on 17 June 2015
limit Maximum number of events to return 50 5 i.e. return a maximum of 5 events
near latitude(decimal),longitude(decimal),radius(metres)
None 52.0381382,-0.7576441,5000
bbox
(bounding box)
western_longitude(decimal),northern_latitude(decimal),
eastern_longitude(decimal),southern_latitude(decimal)

NOTE: These are lng-lat but will be changed to lat-lng soon.
None -0.7776441,52.0481382,-0.7376441,52.0281382
When using multiple parameters at the same time, you'll also need to note the following:
end defined end not defined
start defined startend start → now
start not defined (end minus 24 hours) → end (now minus 24 hours) → now
If limit is also set, then at most that many most-recent points will be returned.

Response

Depending on the request, response will be either in XML or JSON format.

Java example

Here's how you might access the API using Java. For clarity, exception handling is omitted.

Making the Connection

First, open a connection to the server.
// Remember: import java.net.HttpURLConnection;
// Note: API_KEY, HOST and FEED_ID are strings

// The username is the API key; there is no password so there's nothing after the colon
final String credentials = API_KEY + ":";

// Open URL connection
URL url = new URL(HOST + FEED_ID);
HttpURLConnection conn = (HttpURLConnection)url.openConnection();
Next you'll need to authenticate using your API key. If you're using Java 8+ you can use the built-in Base64 class to encode the credentials:
// Don't forget: import java.util.Base64;

// Fill the authorisation request header using Java 8's built-in Base64 class
Base64.Encoder encoder = Base64.getEncoder();
String authToken = encoder.encodeToString(credentials.getBytes());
conn.setRequestProperty("Authorization", "Basic " + authToken);
Otherwise, you can use an external library such as Apache Commons:
// Don't forget: import org.apache.commons.codec.binary.Base64;

// Fill the authorisation request header using the Base64 class from Apache Commons
String authToken = Base64.encodeBase64String(credentials.getBytes());
conn.setRequestProperty("Authorization", "Basic " + authToken);
Alternatively, you can add your credentials using an HTTP header parameter called x-api-key:
conn.setRequestProperty("x-api-key", username);

Getting the Response

Next, you need to specify whether you'd like XML or JSON returned. All methods support either XML or JSON as a response format; many support both. Please check the individual documentation for each method to see which formats are supported and to find the structure of responses. Use an Accept header with the value application/json for JSON and text/xml for XML:
// State that you would like JSON returned
conn.setRequestProperty("Accept", "application/json");
or:
// State that you would like XML returned (this is the default so can be omitted)
conn.setRequestProperty("Accept", "text/xml");
Then you can read the response, e.g. using dom4j if you've requested an XML response:
// Don't forget:
// import java.io.InputStream;
// import org.dom4j.Document;
// import org.dom4j.io.SAXReader;

// Read the response
InputStream is = conn.getInputStream();
SAXReader reader = new SAXReader();
doc = reader.read(is);
reader.close();
is.close();

// Now use the XML document as you require
// ...
The Developers' API is REST-based and can be accessed by issuing HTTP GET requests. All usage is measured in volume of the data returned, including where access is free. You will need to construct a URL appropriate to the dataset you're interested in and the particular information you want to retrieve.

For specific type of feeds, here are the specific URL paths and refinement parameters:



Documentation : Sensor Feeds API Overview

Sensor type feeds can be access following these URL patterns for GET requests:
Path Returns
1 /sensors/feeds/{feed ID} Metadata about the feed and streams, with current values if available.
2 /sensors/feeds/{feed ID}/datastreams/{datastream ID} Metadata about the stream, with the latest value and timestamp if available.
3 /sensors/feeds/{feed ID}/datastreams/{datastream ID}/datapoints The most recent data points or events from the past 24 hours, up to 50 as available.
/sensors/feeds/{feed ID}/datastreams/{datastream ID}/datapoints?{refinement parameters} Data points, selected according to the refinement parameters.


Documentation : Events Feeds API Overview

Event type feeds can be access following these URL patterns for GET requests:
Path Returns
1 /events/feeds/{feed ID} Metadata about the feed and streams, with current values if available.
2 /events/feeds/{feed ID}/datastreams/{datastream ID} Metadata about the stream, with the latest value and timestamp if available.
3 /events/feeds/{feed ID}/datastreams/{datastream ID}/events The most recent data points or events from the past 24 hours, up to 50 as available.
/events/feeds/{feed ID}/datastreams/{datastream ID}/events?{refinement parameters} Data points, selected according to the refinement parameters.


Documentation : Location Feeds API Overview

Location type feeds can be access following these URL patterns for GET requests:
Path Returns
1 /locations/feeds/{feed ID} Metadata about the feed.
2 /locations/feeds/{feed ID}?near={lat},{lng},{radius}
/locations/feeds/{feed ID}?bbox={west lng},{north lat},{east lng},{south lat}
Search for items in a location feed. Values for near and bbox in the query strings are defined below.


Documentation : Geo Feeds API Overview

Geo type feeds can be access following these URL patterns for GET requests:
Path Returns
1 /geo/feeds/{feed ID} Metadata about the feed.
2 /geo/feeds/{feed ID}/features?near={lat},{lng},{radius}
/geo/feeds/{feed ID}/features?bbox={west lng},{north lat},{east lng},{south lat}
Search for items in a location feed. Values for near and bbox in the query strings are defined below.


Documentation : Journeys Feeds API Overview

Journey type feeds include data about journeys - from public transport or private fleets.
BUS Journey type feeds can be access following these URL patterns for GET requests:
Path Returns
1 /journeys/feeds/{feed ID}/station/{stationid} Timetabled service updates at a given bus stop (stationid): might include departures, arrivals and passes.
stationid represents bus stop atco code, for more details please look for NaPTAN in the Data Catalogue. E.g. 1800SB45111 represents "Piccadilly Gardens" in Manchester City Centre.
/journeys/feeds/{feed ID}/station/{stationid}?{refinement parameters} Timetabled service updates at a given stop (stationid) selected according to the (optional) refinement parameters:
Parameter Value Default Example
date date Now 2016-11-01 which represents 1 November 2016
time time Now 09:05 which represents 09:05am 2016 (GMT)
group Option to group the result departures by route ("route"), or return just one 'all' group ("no"). route means results will be grouped by bus route.
limit Number of departures to return within each group (or in total if not grouped). The default value is 3 if you are grouping by route or 10 if you are not grouping. 5 means you will get total of up to 5 results per route (if grouped by route) or total of up to 5 results (if not grouped)
2 /journeys/feeds/{feed ID}/station/{stationid} Live or Timetabled service updates at a given bus stop (stationid): might include departures, arrivals and passes.
/journeys/feeds/{feed ID}/station/{stationid}?{refinement parameters} Live or Timetabled service updates at a given stop (stationid) selected according to the (optional) refinement parameters:
Parameter Value Default Example
group Option to group the result departures by route ("route"), or return just one 'all' group ("no"). route means results will be grouped by bus route.
limit Number of departures to return within each group (or in total if not grouped). The default value is 3 if you are grouping by route or 10 if you are not grouping. 5 means you will get total of up to 5 results per route (if grouped by route) or total of up to 5 results (if not grouped)
nextbuses Set this to 'no' if you want to disable expensive calls to NextBuses. yes no means the NextBuses service won't be called - you will get the data from other available services.
3 /journeys/feeds/{feed ID}/service/{serviceid}?{refinement parameters} Timetabled service updates for a selected bus serviceid (bus line). It requires refinement parameters:
Parameter Value Default Example
stationid bus stop atco code, for more details please look for NaPTAN in the Data Catalogue 1800SB45111 which represents "Piccadilly Gardens" in Manchester City Centre
direction Direction or where service is terminating.
E.g. direction can be 'inbound' or 'outbound'. This may mean the bus is roughly moving inbound towards a city centre or roughly outbound away from it, but mostly the intention is to simply distinguish between the two directions of movement. In addition to 'inbound' and 'outbound' other values such as 'clockwise' can crop up in the data. These are all valid as identifiers here.
Additionally, last stop (where terminating) can be used for some services, depending on the operator.
operator The operator code of the bus you are interested in. WRAY which represents "Arriva Yorkshire"
date (optional) date Now 2016-11-01 which represents 1 November 2016
time (optional) time Now 09:05 which represents 09:05am 2016 (GMT)
TRAIN Journey type feeds can be access following these URL patterns for GET requests:
Path Returns
1 /journeys/feeds/{feed ID}/station/{stationid} Timetabled service updates at a given station (stationid): departures, arrivals or passes.
/journeys/feeds/{feed ID}/station/{stationid}?{refinement parameters} Timetabled service updates at a given station (stationid) selected according to the refinement parameters:
Parameter Value Default Example
date date Now 2016-11-01 which represents 1 November 2016
time time Now 09:05 which represents 09:05am 2016 (GMT)
called_at station code STP which represents "London St Pancras"
calling_at station code STP which represents "London St Pancras"
destination station code where service is terminating STP which represents "London St Pancras"
from_offset Start of the time window PT00:00:00 PT00:25:00 which represents "in 25 minutes"
operator Services that are operated by the given operator. The operator is specified using its ATOC code. VT which represents "Virgin Trains"
origin station code where service is originating STP which represents "London St Pancras"
service Only include services that have the given service code. 24648004
2 /journeys/feeds/{feed ID}/service/{serviceid}?{refinement parameters} Timetabled service updates for a given service. Can be selected according to the refinement parameters:
Parameter Value Default Example
date date Now 2016-11-01 which represents 1 November 2016
time time Now 09:05 which represents 09:05am 2016 (GMT)


Documentation : Snapshot Feeds API Overview

Snapshot type feeds can be access following these URL patterns for GET requests:
Path Returns
1 /snapshot/feeds/{feed ID} Metadata about the feed and streams, with current values if available.
2 /snapshot/feeds/{feed ID}/datapoints?{refinement parameters} Data points, selected according to the refinement parameters:
Parameter Value Default Example
show String. Allowed values are 'all' and 'manchester' (showing the values for the whole network and area of Greater Manchester, respectively). all all snapshot of all IDs
show Array {ID1},{ID2},{ID3}, ...} Link12345,Link23456 snapshot for the selected IDs


Documentation : Paths Feeds API Overview

Paths type feeds contain response that is representing a line(path) with start and end location. Response can be accessed following these URL patterns for GET requests:
Path Returns
1 /paths/feeds/{feed ID} Metadata about the feed and streams, with current values if available.
2 /paths/feeds/{feed ID}/journeys?{refinement parameters} List of journeys (with start and end point and time), selected according to the refinement parameters:
Parameter Value Default Example
start ISO8601 date and time None 2015-05-07T12:52:00Z which represents 12:52pm GMT on 7 May 2015
end ISO8601 date and time None 2015-06-17T08:54:00Z which represents 8:54am GMT on 17 June 2015
limit Maximum number of events to return 50 5 i.e. return a maximum of 5 events
near latitude(decimal),longitude(decimal),radius(metres)
None 52.0381382,-0.7576441,5000
bbox
(bounding box)
western_longitude(decimal),southern_latitude(decimal),
eastern_longitude(decimal),northern_latitude(decimal)

NOTE: whole of the journey needs to be within the bounding box for the journey to be returned within the results.
None -0.7776441,52.0481382,-0.7376441,52.0281382
When using multiple parameters at the same time, you'll also need to note the following:
end defined end not defined
start defined startend start → now
start not defined (end minus 24 hours) → end (now minus 24 hours) → now
If limit is also set, then at most that many most-recent points will be returned.

3 /paths/feeds/{feed ID}/journeys/{journey ID} Detail of one specific journey (with all the points and timestamps within that journey), selected by journey id.


Documentation : Collections API Overview

Collections are designed to contain sensors feeds with SAME datastreams and DIFFERENT geographical location. To acquire the location list for all feeds in the collection, you should look at the top level of the feed (path 1 in the table below) and compare the feed ids with the results from our hypercat catalogue (see more at http://search.bt-hypercat.co.uk or read about it in Using Hypercat section).

Collections Snapshot can be accessed following these URL patterns for GET requests:
Path Returns
1 /collections/{collections ID} Returns metadata about the collection and list of members (feed ids).
2 /collections/{collections ID}/snapshot Returns snapshot of values in collection that are close in time.
3 /collections/{collections ID}/datastreams/{datastream ID}/snapshot For selected datastream, returns snapshot of values in collection that are close in time

Attribution

Please ensure that you mention the BT CityVerve Data Hub Data Hub and/or link to this Data Hub in your application or service, either on a startup screen or an about page. In some circumstances, you may need to attribute the owner of the dataset. Any requirements for this will be provided on the dataset's page.

Terms and Conditions

Please refer to this page.