The Trip Planner API has multiple endpoints that offer different capabilities and simplifies a lot of the functions that are popular in public transport apps. This makes developing your application much easier and faster. One of the most popular function requests and questions that we receive is about the departure board. Now, thanks to the Trip Planner API, building your own departure board is relatively easy, providing you are familiar with some PHP and basic HTML and CSS styling.
What is a Departure Board?
A departure board is a board or display that shows all upcoming services for your stop or a certain stop, i.e. all departures from Circular Quay station. The board may display real-time data, alerts and other information. Using open data from the Open Data Hub, you can develop a departure board similar to what you might see at a station or a bus stop. Customers find departure boards very useful because in their regular commute they’re just interested in two things, their regular stop and what services are coming up next.
The Trip Planner API - Departure Endpoint
Thanks to the Trip Planner API, it is simple to build your own departure board. The Trip Planner API has five different endpoints that you can interact with, one being a departure endpoint. The ‘Departure API’ endpoint provides the capability to get and display NSW public transport departure information from any stop, station or wharf, including real-time data. The other 4 endpoints in the Trip Planner API are: ‘Stop Finder’, ‘Trip Planner’, ‘Service Alert’ and ‘Coordinate Request’.
How to Build Your Own Departure Board
The following guide will be using PHP to interact with the API and produce results on a web page. You should be familiar with HTML, CSS and PHP to complete the tutorial. The following assumptions are taken into consideration before attempting to follow this guide:
- You have registered on the Open Data Hub, created an application and acquired an API key
- You have read the Trip Planner API documentation
- Basic knowledge of HTML, CSS and PHP
- Understanding of the Trip Planner API, how it works and what information the ‘Departure’ endpoint provides
Let’s start coding…
1. You will need to create a new PHP file in your server. It’s also always good practice to set up error reporting for troubleshooting purposes.
<?phperror_reporting(E_ALL); ini_set('display_errors', 1);
2. We will also set the timezone to “Sydney, Australia” to make sure the times given are correct.
date_default_timezone_set("Australia/Sydney");
3. We will now create some variables for the script to use. This includes the API endpoint address, time, stop and other parameters that apply to the API. The URL variable performs the request and builds the JSON response to display the requested information.
$apiEndpoint = 'https://api.transport.nsw.gov.au/v1/tp/';$apiCall = 'departure_mon'; // Set the location and time parameters$when = time(); // Now$stop = '10101331'; // Domestic Airport Station// Build the request parameters$params = array( 'outputFormat' => 'rapidJSON', 'coordOutputFormat' => 'EPSG:4326', 'mode' => 'direct', 'type_dm' => 'stop', 'name_dm' => $stop, 'depArrMacro' => 'dep', 'itdDate' => date('Ymd', $when), 'itdTime' => date('Hi', $when), 'TfNSWDM' => 'true' );$url = $apiEndpoint . $apiCall . '?' . http_build_query($params);
4. We will then create a stream or feed by using a get request and your API key from the Open Data Hub.
// Create a stream$opts = [ "http" => [ "method" => "GET", "header" => "Authorization: apikey XXXXXXXXXXXXXXXXXXXXXXXXXX\r\n" ]];
5. We then need to set some variables for the creation of the stream and to store the response so it’s able to be decoded from JSON into plain text. We also create a JSON object for the script to loop over the stop.
// Perform the request and build the JSON response data$context = stream_context_create($opts);$response = file_get_contents($url, false, $context);$json = json_decode($response, true);$stopEvents = $json['stopEvents']; // Loop over returned stop events
6. This is the script that we loop over the stop to extract the route information and display it in plain text on the web page or app.
foreach ($stopEvents as $stopEvent) { // Extract the route information $transportation = $stopEvent['transportation']; $routeNumber = $transportation['number']; $destination = $transportation['destination']['name']; // In the case of a train, the location includes platform information $location = $stopEvent['location']; // Determine how many minutes until departure $time = strtotime($stopEvent['departureTimePlanned']); $countdown = $time - time(); $minutes = round($countdown / 60); // Output the stop event with a countdown timer echo $minutes . "m from " . $location['name'] . "\n<br />"; echo $routeNumber . " to " . $destination . "\n\n<br /><br />";}
7. If you’ve done everything correctly you should see an output similar to this:
As you can see, it displays all services departing from a stop (in this case Domestic Airport). However, it doesn’t look very good, the output has very basic formatting.
8. After adding some simple CSS styling to it we can make it look more customer friendly:
9. Once you have a basic departure board working, you can move on to more advanced features such as adding an input field for users to select a specific stop, add the ability to select certain transport modes.
This is a great example of one of the many amazing things you can accomplish with our open data. We encourage and challenge you to create the next great transport app.
Click here to view the full code sample
To have a look at all the data that we offer please browse our data catalogue. To join in on discussion threads, ask for assistance or brag about your latest creation make sure to visit our Open Data Forum. Also make sure to follow us on Twitter @DataTfNSW to keep up to date with all things open data.
-The TfNSW Open Data and Innovation Team