Stay Updated!
As this API is just entering public beta, it is highly advisable that you let me know if you build an application so I can contact you should any of the API details change - it's also great to see what people are building! Alternatively, you can subscribe to the blog on my website or follow me on Twitter for all of the latest updates.
How to call the API
The API is REST-ful and operates over a standard HTTP GET protocol. The base URL is:
http://api.tubeupdates.com/
Parameters are passed via GET. Every method has at least 2 supported parameters of which one is required:
- method (required) - the method that you wish to invoke. A list of available methods is available below.
- format (optional) - the desired output format; either 'json' or 'xml'. Defaults to 'json' if none specified or if entered incorrectly.
- debug (optional) - if set to 'true', then it will suppress the application/x-json header on any returned json stream. This is useful for debugging in a browser as it means the json stream will appear as text in the browser window rather than as a download prompt. Defaults to 'false'.
Available Methods
get.status
This will get the status of a single line or selection of lines either at the moment or at a specified time.
Parameters
- lines (optional) - a comma separated list of line identifiers. Defaults to 'all'.
- time (optional) - unix timestamp for the time you wish to retrieve updates for. All times are specified as GMT. Defaults to current time. (note: you can also submit a string to be interpreted e.g. 1st feb 8:22pm - using a timestamp is more reliable though)
- return (optional) - a comma separated list of items you'd like to return (all, name, id, status, messages, status_starts, status_ends, status_requested). Defaults to 'all'.
Example Usage
Request:
http://api.tubeupdates.com/?method=get.status&lines=central,hammersmithcity,victoria&format=xml
Response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<lines>
<line>
<name>Central</name>
<id>central</id>
<status>part closure</status>
<messages>
<message>CENTRAL LINE: Sunday 1 March, suspended between Liverpool Street and Leytonstone.</message>
<message>MONUMENT AND BANK STATIONS: Please avoid using Monument Station to interchange with services from Bank.</message>
</messages>
<status_starts>Sun, 01 Mar 2009 01:33:01 +0000</status_starts>
<status_ends></status_ends>
<status_requested>Sun, 01 Mar 2009 20:25:05 +0000</status_requested>
</line>
<line>
<name>Hammersmith & City</name>
<id>hammersmithcity</id>
<status>good service</status>
<messages>
</messages>
<status_starts>Sat, 28 Feb 2009 08:21:06 +0000</status_starts>
<status_ends></status_ends>
<status_requested>Sun, 01 Mar 2009 20:25:05 +0000</status_requested>
</line>
<line>
<name>Victoria</name>
<id>victoria</id>
<status>good service</status>
<messages>
</messages>
<status_starts>Sat, 28 Feb 2009 01:32:08 +0000</status_starts>
<status_ends></status_ends>
<status_requested>Sun, 01 Mar 2009 20:25:05 +0000</status_requested>
</line>
</lines>
</response>
Line Identifiers
Each line is represented by a specific identifier which is required for API usage. These are detailed below:
all- Wildcard for all linesbakerloo- Bakerloo Linecentral- Central Linecircle- Circle Linedistrict- District Linedocklands- Docklands (note: DLR will always return a status of 'unknown' as TFL doesn't give it a status)hammersmithcity- Hammersmith & City Linejubilee- Jubilee Linemetropolitan- Metropolitan Linenorthern- Northern Linepiccadilly- Piccadilly Linetube- Wildcard for all tube lines (excludes DLR)victoria- Victoria Linewaterloocity- Waterloo & City Line
Error Handling
When an error is encountered, you will be sent an error response in the format that you made your initial request for (defaults to 'json'). The error output will consist of an error element with a single message:
Example
Request:
http://api.tubeupdates.com/?method=get.status&lines=circle,district,hogwarts
Response:
{"response":{"error":"Unrecognised lines value 'hogwarts'"}}
It is recommended that you always check for the presence of an error element before dealing with other elements. There will never be an error element if the request was successful.
Caching & Throttling
At present, this API is not in any way throttled meaning you can make multiple requests to the service. However, it should be noted that you are recommended to cache any responses from the API in order to save my bandwidth!
It is suggested that you make API calls no more frequently than once a minute - if you are building a large application, either let me know so I can cater for more bandwidth, or do an API request once a minute and cache the results on your server and make your application access the cache.
If I deem that your application is making too many requests, then I reserve the right to throttle your requests. If you set your user-agent to something identifiable (preferably with an email address or URL in it) then I will contact you before throttling.
Please contact me if you have any questions.
Licensing
This API is released for free (although donations are always appreciated) under the Creative Commons Attribution 3.0 Unported license - please include an attribution link to either tubeupdates.com or to bendodson.com in any application you build using this service. You can also let me know what you build as I'm always interested to see how my stuff gets used!