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:

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 &amp; 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:

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 second (although bear in mind that the lines only get updated once per 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.

Compression

All responses are compressed using GZIP to maximise transfer speed.

Flash

Whilst I feel that Flash as a programming language is finally coming to the end of its tenure, I know there are still Flash developers out there who want to make cool stuff with this API. Therefore, there is a crossdomain.xml file installed in the API root so that you can make connections from any location.

Stats

We keep a log of all API requests so we can provide statistics to developers of their API usage. If you would like a breakdown of your API requests, then please send me your base user agent and I can give you a list of the number of requests per day broken down by application version. This is particularly useful for mobile developers who want to see if their users have migrated to a new version.

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!