{"id":19,"date":"2020-02-24T10:11:56","date_gmt":"2020-02-24T10:11:56","guid":{"rendered":"https:\/\/www.roblsmith.co.uk\/blog\/?p=19"},"modified":"2022-06-20T14:27:20","modified_gmt":"2022-06-20T14:27:20","slug":"building-a-train-departure-board-using-the-openldbws","status":"publish","type":"post","link":"https:\/\/roblsmith.co.uk\/blog\/2020\/02\/building-a-train-departure-board-using-the-openldbws\/","title":{"rendered":"Building a train departure board using the OpenLDBWS"},"content":{"rendered":"

So in my first post of programming stuff, I am going to cover on how to integrate with National Rail’s OpenLDBWS<\/a> to make a departure board.<\/p>\n

What is the OpenLDBWS
\n<\/span>The OpenLDBWS is the\u00a0Live Departure Boards Web Service. It provides a web service (vs an API) that returns real-time train information from Darwin. Darwin is the official train information engine. Since 2014 the open-access licence came into effect, meaning that individuals and organisations are now free to develop websites, apps and other digital tools with the data.<\/p>\n

Pre-Reqs
\n<\/span>1. To gain access to the OpenLDBWS data you need to request an access token here<\/a>
\n2. You’ll also need a way to develop, and host your project. e.g. a webhosting provider or use something like Heroku.<\/p>\n

Let’s Begin.<\/span>
\nAs I am developing a departure\u00a0board I am going to need to use the GetDepBoardWithDetails operation. The list of them is here<\/a>.<\/p>\n

I am using the WithDetails endpoint VS the standard getDepBoard, as I would also like to list out extra information such as calling points to display on my output.<\/p>\n

Firstly, we need to build a handler to make the SOAP connection, my example is here:<\/p>\n

\r\n<?php\r\n\r\nclass train\r\n{\r\n\t\/\/ Params\r\n\tprivate $soap = NULL; \/\/ soap connection\r\n\tprivate $accessKey = NULL; \/\/ api key\r\n\tprivate $wsdl = 'http:\/\/lite.realtime.nationalrail.co.uk\/OpenLDBWS\/wsdl.aspx';\r\n\t\r\n\t\r\n\t\/\/  PHP will automatically call this function when you create an object from a class\r\n\tfunction __construct($accessKey)\r\n\t{\r\n\t\t$this->accessKey = $accessKey; \/\/ Retreive accessKey passed when calls are made\r\n\t\t$soapOptions = array(); \/\/ Any options to pass to Soap connection here\r\n\t\t$this->soapClient = new SoapClient($this->wsdl,$soapOptions); \/\/ create new SoapClient connection\r\n\t\t\r\n\t\t$soapVar = new SoapVar(array("ns2:TokenValue"=>$this->accessKey),SOAP_ENC_OBJECT);\r\n\t\t$soapHeader = new SoapHeader("http:\/\/thalesgroup.com\/RTTI\/2010-11-01\/ldb\/commontypes","AccessToken",$soapVar);\r\n\t\t$this->soapClient->__setSoapHeaders($soapHeader);\r\n\t}\r\n\t\r\n\t\/\/ Make call for train data\r\n\tfunction GetDepBoardWithDetails($numRows, $crs, $filterCrs="", $filterType="", $timeOffset="", $timeWindow="")\r\n\t{\r\n\t\t\/\/ Params for the connection\r\n\t\t$params = array();\r\n\t\t$params["numRows"] = $numRows;\r\n\t\t$params["crs"] = $crs;\r\n\r\n\t\tif ($filterCrs) $params["filterCrs"] = $filterCrs;\r\n\t\tif ($filterType) $params["filterType"] = $filterType;\r\n\t\tif ($timeOffset) $params["timeOffset"] = $timeOffset;\r\n\t\tif ($timeWindow) $params["timeWindow"] = $timeWindow;\r\n\t\t\r\n\t\t\/\/ Make the connection\r\n\t\ttry\r\n\t\t{\r\n\t\t\t$response = $this->soapClient->GetDepBoardWithDetails($params);\r\n\t\t}\r\n\t\tcatch(SoapFault $soapFault)\r\n\t\t{\r\n\t\t\ttrigger_error("Something's wrong", E_USER_ERROR);\r\n\t\t}\r\n\r\n\t\t\/\/ pass data back\r\n\t\treturn (isset($response) ? $response : false);\r\n\t}\r\n}\r\n<\/pre>\n
Once we have this file we can interface with the SOAP service with the applicable WSDL file, and I can begin to handle train data.<\/p>\n
I am going to return all data and all fields to see what we have to play with, to do this I am going to do the below code…<\/p>\n
\r\n<?php\r\n\trequire("soapHandler.php");\r\n\t$train = new train("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa");\r\n\t$response = $train->GetDepBoardWithDetails(1,"MBR");\r\n\theader("Content-Type: text\/plain");\r\n\tprint_r($response->GetStationBoardResult->trainServices->service);\r\n\r\n<\/pre>\n
The script above will be the basis for the trainData.php file, with the first script which I have named soapHandler.php. You will need to provide the token key which you would have already requested when making a request to the soap service.<\/p>\n
For the 2nd parameter, as I live in Middlesbrough, I have provided the CRS (Computer Reservation System) which is the 3 letter station code, as MBR. e.g. for Hull use HUL – for other stations, there are lists everywhere in order to find their 3 letter codes. I have also passed in the 1st parameter as 1, this is so it will return a maximum of 1 result.<\/p>\n
The data I get back includes scheduled times, on-time\/delayed arrival time, platform, calling points, and if there are cancellations and the reason why.<\/p>\n
I did have to change my lookup to use Edinburgh as Middlesbrough had no more departures when I was coding this. I figured this out when I got the below response. As the GetStationBoardResult object was empty.<\/p>\n
\r\nstdClass Object\r\n(\r\n    [generatedAt] => 2020-02-21T23:46:29.3118451+00:00\r\n    [locationName] => Middlesbrough\r\n    [crs] => MBR\r\n    [nrccMessages] => stdClass Object\r\n        (\r\n            [message] => Array\r\n                (\r\n                    [0] => stdClass Object\r\n                        (\r\n                            [_] => The ticket office at this station is currently closed. \r\n                        )\r\n\r\n                    [1] => stdClass Object\r\n                        (\r\n                            [_] => <p>The Ticket Vending Machines are currently out of order at this station.<\/p>\r\n                        )\r\n\r\n                )\r\n\r\n        )\r\n\r\n    [platformAvailable] => 1\r\n)\r\n<\/pre>\n
As the data is returned as an object, if for example I wanted to output a list of calling points I can do this:<\/p>\n
\r\n<?php\r\n\trequire("soapHandler.php");\r\n\t$train = new train("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa");\r\n\t$response = $train->GetDepBoardWithDetails(1,"EDB");\r\n\theader("Content-Type: text\/plain");\r\n\r\n\t$callingPoints = $response->GetStationBoardResult->trainServices->service->subsequentCallingPoints->callingPointList->callingPoint;\r\n\t$callingPoints = json_encode($callingPoints);\r\n\t$callingPoints = json_decode($callingPoints, true);\r\n\r\n\r\n\tforeach ($callingPoints as $callPoint)\r\n\t{\r\n\t\tprint $callPoint['locationName'] . PHP_EOL;\r\n\t}\r\n\r\n<\/pre>\n
This resulted in:<\/p>\n
Haymarket
\nEdinburgh Park
\nUphall
\nLivingston North
\nBathgate<\/p>\n
When it came to checking for nrccMessages messages, interestingly Edinburgh did have a message<\/p>\n
\r\n    [nrccMessages] => stdClass Object\r\n        (\r\n            [message] => stdClass Object\r\n                (\r\n                    [_] => <p><\/p>\r\n<p>Poor weather is affecting journeys in Scotland. More details and the impact to your journey can be found in <A href="http:\/\/nationalrail.co.uk\/service_disruptions\/243304.aspx">Latest Travel News<\/A>.<\/p>\r\n                )\r\n\r\n        )\r\n<\/pre>\n
So we could consider seeing if a value for nrccMessages exists, and capture the message to display elsewhere.<\/p>\n
Next up is a way of displaying the train information. I am not going to go into details on how to design something pretty, I will knock something basic up – based off a generic platform information screen. Essentially we just need to pass in details of the calling points, destination, platforms, and if the training is running on time to this template.<\/p>\n
In order to generate the needed data from the info-overload, we can do something like:<\/p>\n
\r\n<?php\r\n\trequire("soapHandler.php");\r\n\t$train = new train("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa");\r\n\t$response = $train->GetDepBoardWithDetails(10,"MBR");\r\n\theader("Content-Type: text\/plain");\r\n\r\n\t$response = json_encode($response);\t\r\n\t$response = json_decode($response, true);\r\n\r\n\t$trainData = array();\r\n\r\n\tforeach ($response['GetStationBoardResult']['trainServices']['service'] as $train)\r\n\t{\r\n\t\t$temp = array();\r\n\t\t$temp['destination'] = $train['destination']['location']['locationName'];\r\n\t\t\r\n\t\t$temp['platform'] = $train['platform'];\r\n\t\t$temp['toc'] = $train['operator'];\r\n\t\t$temp['carriages'] = $train['length'];\r\n\t\t\r\n\t\t\/\/ Work out times\r\n\t\t$temp['schd'] = $train['std'];\r\n\t\t$temp['etd'] = $train['etd'];\r\n\t\t\r\n\t\tif ($train['etd'] != 'On time')\r\n\t\t{\r\n\t\t\t\/\/ Train is late, lol.\r\n\t\t\t$schd = strtotime($train['std']);\r\n\t\t\t$etd = strtotime($train['etd']);\r\n\t\t\t$delay = ($etd - $schd) \/ 60;\r\n\t\t\t\r\n\t\t\t$temp['delay'] = $delay;\r\n\t\t\t\r\n\t\t\t\/\/ Is a delay reason given?\r\n\t\t\tif (isset($train['delayReason']))\r\n\t\t\t{\r\n\t\t\t\t$temp['delayReason'] = $train['delayReason'];\r\n\t\t\t}\r\n\t\t}\r\n\t\t\r\n\t\t\/\/ is train cancelled\r\n\t\t$trainCancelled = isset($train['cancelReason']);\r\n\t\t\r\n\t\tif ($trainCancelled)\r\n\t\t{\r\n\t\t\tif ($train['cancelReason'] != '')\r\n\t\t\t{\r\n\t\t\t\t$temp['cancelReason'] = $train['cancelReason'];\r\n\t\t\t}\r\n\t\t\t\r\n\t\t\t$temp['cancelled'] = true;\r\n\t\t}\r\n\t\t\r\n\t\t\/\/ Get callpoints and times\r\n\t\t$temp['callingPoints'] = array();\r\n\t\t\r\n\t\tif (!$trainCancelled)\r\n\t\t{\r\n\t\t\t$trainCallingPoints = $train['subsequentCallingPoints']['callingPointList']['callingPoint'];\r\n\r\n\t\t\t\/\/ Direct train or multiple call points?\r\n\t\t\tif (isAssocArray($trainCallingPoints))\r\n\t\t\t{\r\n\t\t\t\t$temp['callingPoints'] = array(\r\n\t\t\t\t\t'location' => $trainCallingPoints['locationName'],\r\n\t\t\t\t\t'st' => $trainCallingPoints['st'],\r\n\t\t\t\t\t'et' => $trainCallingPoints['et']);\r\n\t\t\t}\r\n\t\t\telse\r\n\t\t\t{\r\n\t\t\t\tforeach ($trainCallingPoints as $callingPoints)\r\n\t\t\t\t{\r\n\t\t\t\t\t$callPoint = array(\r\n\t\t\t\t\t\t'location' => $callingPoints['locationName'],\r\n\t\t\t\t\t\t'st' => $callingPoints['st'],\r\n\t\t\t\t\t\t'et' => $callingPoints['et']);\r\n\r\n\t\t\t\t\t$temp['callingPoints'][] = $callPoint;\r\n\t\t\t\t}\r\n\t\t\t}\r\n\t\t}\r\n\t\t\r\n\t\t\/\/ push data to array\r\n\t\t$trainData[] = $temp;\r\n\t}\r\n\r\nprint_r(json_encode($trainData));\r\n\r\nfunction isAssocArray($arr)\r\n{\r\n    if (array() === $arr) return false;\r\n    return array_keys($arr) !== range(0, count($arr) - 1);\r\n}\r\n<\/pre>\n
With the $trainData variable, if I was to do a print_r, I would see meaningful data which can be passed into the template…
\nNow I’ve had to add a “hacky” function because some trains were not returning as an associative array, I assume because it was a direct train, as the only stopping listed was the destination.<\/p>\n
Piecing it together<\/span>
\nNow we have some form of template; and the data we need – we can use AJAX to query the data and update the screen.<\/p>\n
I won’t go into the nitty-gritty of how to do this, essentially we need a basic HTML file and a JavaScript file.
\nThe JavaScript file will have a setTimeout() function which will do an AJAX call to this PHP file – the success handler will then parse the JSON response and loop through it. I am then generating the HTML of the table row, then appending it to the table by doing.<\/p>\n
$(\"#trainTable\").append(html);<\/code><\/p>\n
My setTimeout function works like this, loadData() is called on pageload.<\/p>\n
\r\nfunction loadData() \r\n{\r\n\tsetTimeout(function () {\r\n\t\t\t$.ajax({\r\n\t\t\t\turl: "trainData.php",\r\n\t\t\t\ttype: "GET",\r\n\t\t\t\tsuccess: function(result) {\r\n\t\t\t\t\thandleResponse(result); \r\n\t\t\t\t\ttimeout = 60000;\r\n\t\t\t\t},\r\n\t\t\t\tcomplete: function(){\r\n\t\t\t\t\tloadData();\r\n\t\t\t\t},\r\n\t\t\t\terror : function(){\r\n\t\t\t\talert('something went wrong');\r\n\t\t\t}\r\n\t\t});\r\n\t}, timeout);\r\n}\r\n<\/pre>\n
With my handleResults looking like this<\/p>\n
\r\nfunction handleResponse(result)\r\n{\r\n\tvar data = JSON.parse(result);\r\n\tvar trainData = data['train'];\r\n\t\r\n\t$("#trainTable").html('');\r\n\t\t\r\n\tvar index;\r\n\t\r\n\tfor (index = 0; index < trainData.length; ++index)\r\n\t{\r\n\t\tvar borderStyle = '';\r\n\t\tvar carriageInfo = '';\r\n\t\t\r\n\t\tif (index != (trainData.length-1))\r\n\t\t{\r\n\t\t\tborderStyle = 'border-bottom: 1px solid white;';\r\n\t\t}\r\n\t\t\r\n\t\tif (trainData[index]['carriages'] != '-')\r\n\t\t{\r\n\t\t\tcarriageInfo = ', this train has ' + trainData[index]['carriages'] + ' carriages';\r\n\t\t}\r\n\t\t\r\n\t\tvar html = `\r\n\t\t\t<div class="row">\r\n\t\t\t\t<div class="col-sm-1">` + trainData[index]['schd'] + `<\/div>\r\n\t\t\t\t<div class="col-sm-8 TrainDestination">` + trainData[index]['destination'] +`<\/div>\r\n\t\t\t\t<div class="col-sm-1 text-md-center">` + trainData[index]['platform'] + `<\/div>\r\n\t\t\t\t<div class="col-sm-2 text-md-center">` + trainData[index]['etd'] + `<\/div>\r\n\t\t\t<\/div>\r\n\t\t\t<div  class="row">\r\n\t\t\t<\/div>\r\n\t\t\t<div class="row no-gutters" style="padding-left: 94px;` + borderStyle + `">\r\n\t\t\t\t<div class="col-sm-12 col-md-1 trainfont">Callling at:<\/div>\r\n\t\t\t\t<div class="col-sm-8 col-md-8 trainfont">\r\n\t\t\t\t  <marquee>` + trainData[index]['callingPointsString'] + `<\/marquee>\r\n\t\t\t\t<\/div>\r\n\t\t\t\t<span class="trainfont">Operated by ` + trainData[index]['toc'] + ``+\r\n\t\t\t\tcarriageInfo +` <\/span>\r\n\t\t\t<\/div>`;\r\n\t\t\r\n\t\t\r\n\t\t$("#trainTable").append(html);\r\n\t}\r\n\t\r\n\t$("#nrccMessages").html(data['nrccMessages']);\r\n\t\r\n}\r\n<\/pre>\n
You can see my implementation on github here<\/a>.<\/p>\n
For now that is all, but I have something cool we can do with the JSON train data.<\/p>\n
Something that could be done if you was that way inclined, is hooking it up to a Raspberry Pi and run it off a screen… Pretty nifty if you wanted to sell it as a product to a cafe near a railway station.<\/p>\n
\"\"
Example of the board showing data from Kings Cross.<\/figcaption><\/figure>\n
Anyhoo,<\/p>\n
That covers me creating a basic departures board. Pretty easy to implement, however, the responses back from the OpenLDBWS can be inconsistent so you do need to do a few isset checks. For instance, if no platform information is available it doesn’t return anything vs. returning at least a key with an empty value or; NULL, ‘TBD’, etc..<\/p>\n","protected":false},"excerpt":{"rendered":"
So in my first post of programming stuff, I am going to cover on how to integrate with National Rail’s OpenLDBWS to make a departure board. What is the OpenLDBWS The OpenLDBWS is the\u00a0Live Departure Boards Web Service. It provides a web service (vs an API) that returns real-time train information from Darwin. Darwin is…<\/p>\n","protected":false},"author":3,"featured_media":76,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"spay_email":""},"categories":[8],"tags":[19,21,20],"jetpack_featured_media_url":"https:\/\/roblsmith.co.uk\/blog\/wp-content\/uploads\/2020\/02\/depatureboard1.png","_links":{"self":[{"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/posts\/19"}],"collection":[{"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/comments?post=19"}],"version-history":[{"count":5,"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/posts\/19\/revisions"}],"predecessor-version":[{"id":26,"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/posts\/19\/revisions\/26"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/media\/76"}],"wp:attachment":[{"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/media?parent=19"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/categories?post=19"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/roblsmith.co.uk\/blog\/wp-json\/wp\/v2\/tags?post=19"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}