Jack Barber / Website Design

A Brief Introduction to Transport API

A Brief Introduction to Transport API

Transport API is an online service providing UK-wide travel data across rail, bus and car. It also provides access to tweets within a specific area - which could be helpful for monitoring traffic jams, rail delays and so on.

For this particulary project I wanted to provide users with accurate information for the next buses for Whitby and Scarborough, departing from Robin Hood's Bay.

Here's a quick overview of the steps I took to get this working. It's fairly rudimentary, but should give a helpful starting point if you're looking to do something similar.

Step 1: Sign Up

Head over to www.transportapi.com and sign up for a developer account. It's free. They provide paid accounts for users who exceed the free limit (at time of writing that stands at 30,000 API requests/month - which is quite a lot).

Once you've registered you'll be able to create an app and get hold of your API key along with your app ID. You'll need both of these bits of information to make API requests.

Step 2: Jump into the API Reference

They really have made everything as straight forward as possible. The API reference provides all the information required to get you started making requests and getting JSON data back as a response. And every call can be tested within your developer account - no messing around trying stuff and then spending ages wondering why it failed!

On screen you'll see a long list of different types of API request - the section I was interested in was /uk/bus:

Step 3: Find Your atcocode

You'll see that the request for live bus data requires an {atcocode} element. This is a distinct ID number for each bus stop around the country. Before we can start getting bus times we need to work out what the atcocode is for the stop we're interested in. To do this we need to use the /uk/bus/stops/near.json request - click on the 'GET' button to the right of this call.

Provided you're signed in, the app_id and app_key fields will be pre-populated. All you need to do is enter a lat and lon number for your geographical location (as seen above, these numbers are for Robin Hood's Bay). You can generate a lat and lon number using www.latlong.net.

Once you've entered your lat and lon number go ahead and hit 'GET' and the results will appear in the box below, along with the full request URL for your reference:

Within the Response section, take a look at Body - you'll see a list of the results with a text name and direction indicator along with the atcocode for each stop. The 2 stops I'm interested in are shown above (Thorpe Lane, E-bound and W-bound). Make a note of the atcocode for each stop.

Step 4: Get Bus Times

Using the atcocode for each stop we can now get bus time data using a different API request. Head back up the list a little way until you find/uk/bus/stop/{atcocode}/live.json - click 'GET' next to this one and then paste in your atcodcode in the box, like this:

You'll see a few other options - 'group', 'limit', and 'nextbuses' - use these to amend how the data is returned. For my purposes the default settings were fine. Hit 'GET' to see the results:

Again you'll see the Request URL showing you exactly what query to use to get the desired response, along with the response data in the box below. Clearly at this point it would be sensible to match the data returned to the actual time table for the service. Provided it's accurate you can then complete the process by implementing this API request in your website.

Step 5: Process the Request with PHP

My app is built in PHP so I did the following:

    $bus = file_get_contents('https://transportapi.com/v3/uk/bus/stop/3200YNA90578/live.json?app_id=[YOUR_APP_ID]&app_key=[YOUR_APP_CODE]&group=route&nextbuses=yes');
    $bus = json_decode($bus, true);    
    $dateParts = explode("-",$bus['departures']['X93'][0]['date']);
    $date = "$dateParts[2]/$dateParts[1]/$dateParts[0]";
    $tomorrow = date("d/m/Y", mktime(0, 0, 0, $dateParts[1], $dateParts[2], $dateParts[0]));
    if($date == date('d/m/Y')){
        $date = 'Today';
    }elseif($date == $tomorrow){
        $date = 'Tomorrow';
    echo "<p><strong>Service:</strong> ".$bus['departures']['X93'][0]['line']."</p>";
    echo "<p><strong>Departure Date:</strong> ".$date."</p>";
    echo "<p><strong>Departure Time:</strong> ".$bus['departures']['X93'][0]['aimed_departure_time']."</p>";

Clearly this only works for my specific route - you will need to adapt how PHP parses the JSON response in order to get the required bits of data for your own Transport API service. But given the developer area provides the full response in an easy to digest format, it shouldn't take you too long to work out how to do that!

Also, I implemented a simple date check - so the system will present 'Today' or 'Tomorrow' rather than an actual date - this offers a slight UX improvement to the user.

So, go ahead - sign up at www.transportapi.com and build something - it's easy!