A cross-platform JSON proxy for the GB railway Live Departure Boards SOAP API
Huxley 2 is a CORS enabled cross-platform JSON ReST proxy for the GB NRE LDB WCF SOAP XML API (called Darwin). It supports both the Public Version (PV) and the Staff Version (SV). It's built with ASP.NET Core LTS (.NET 6.0), C# 10 and lots of abbreviations!
The primary purpose of Huxley 2 is to allow easy use of the LDB API from browser-based client-side PWAs made with JavaScript or TypeScript. Additionally, it opens up the Windows enterprise API to agile developers on macOS and Linux.
Version 2.0.5
There are some significant changes from version 1:
Follow these steps to get going:
accessToken=TOKEN
to the URL for every request
If you don't want to append the token then read on.
You will need to add your access token to the configuration file or URL. You can register to obtain one here (or here for the staff version).
Append accessToken={Your GUID token}
to the URL for every request.
If using the staff versions then you will need to use your staff token.
There is optional support for configuring the access token server-side. So you don't need to worry about revealing it in URLs or source code.
In the appsettings.json
file you can set tokens and other settings.
You can set DarwinAccessToken
to your NRE access token.
If you leave ClientAccessToken
as an empty string then no token is required in the
Huxley URL.
If you set ClientAccessToken
to a string and it matches the token in the URL then the
DarwinAccessToken
will be used instead in the SOAP call.
Otherwise the URL token is passed straight through.
You can do the same with DarwinStaffAccessToken
if you are using the staff version of
the API.
Both share a ClientAccessToken
so your client only needs one token (or none).
N.B. You should set up these tokens in your deployment platform and not in your source code repository. You'll notice that the values are blank by default.
Most of these endpoints (except delays and crs) map directly to the SOAP API. Refer to the official documentation pages for the public and staff web services for more details, but be aware that these are not entirely accurate.
There are five station boards and their staff equivalents, plus a delays board that Huxley provides.
The URL format is
{board}/{CRS|StationName}/{filterType}/{filterCRS|StationName}/{numRows}
or
{board}/{CRS|StationName}/{numRows}
(arrivals/departures only) where only board and CRS
(or a station name) are required.
The filter type can be either to
or from
(case is not important).
A station name can be used in place of CRS codes if the name matches only one station (or matches one exactly) but case is not important. See the CRS section below for more information.
For all boards (except delays) you can add an expand=true
parameter to embed all
service details into the board response.
The delays board is expanded by default.
/all/{CRS|StationName}?expand=true
You can optionally add timeOffset
(-120 to 119 inclusive) and timeWindow
(-120 to 120 inclusive) parameters in minutes.
For example, to get services for the next hour and last fifteen minutes:
/all/{CRS|StationName}?timeOffset=-15&timeWindow=75
/all/clj
/all/clj/15
/departures/clj/to/wat
/arrivals/clj/from/wat/15
/all/wandsworth common/to/clapham junction
/departures/east croydon/to/london victoria/20
/next/{CRS|StationName}/{filterType}/{filterCRSs|StationNames}
Filter stations can be a comma separated list. Filter type and number of rows are ignored.
/fastest/{CRS|StationName}/{filterType}/{filterCRSs|StationNames}
Filter stations can be a comma separated list. Filter type and number of rows are ignored.
/staffdepartures/{CRS|StationName}
/staffarrivals/{CRS|StationName}
/staffnext/{CRS|StationName}/{filterType}/{filterCRSs|StationNames}
/stafffastest/{CRS|StationName}/{filterType}/{filterCRSs|StationNames}
The delays action performs calculations server side to easily let you know if there are problems on a particular route. Filter is required.
/delays/{CRS|StationName}/{filterType}/{filterCRS|StationName}/{numRows}
Additionally, this action will accept LON
or London
as a filter CRS to
find trains going to or coming from
any of the London
Terminals.
You can also pass in a comma separated list of 24 hour train times to filter on (e.g.
/delays/btn/to/lon/10/0729,0744,0748
).
{ "generatedAt": "2024-10-10T06:52:40.7663307+00:00", "locationName": "Clapham Junction", "crs": "CLJ", "filterLocationName": "London", "filtercrs": "LON", "filterType": 1, "delays": true, "totalTrainsDelayed": 1, "totalDelayMinutes": 0, "totalTrains": 6, "delayedTrains": [ { "origin": [ { "locationName": "London Victoria", "crs": "VIC", "via": null, "futureChangeTo": null, "assocIsCancelled": false } ], "destination": [ { "locationName": "Littlehampton", "crs": "LIT", "via": "via Hove & Worthing", "futureChangeTo": null, "assocIsCancelled": false } ], "currentOrigins": null, "currentDestinations": null, "rsid": "SN382200", "serviceIdPercentEncoded": "Aum4%2FnXk%2B02wKUVqlS7JAQ%3D%3D", "serviceIdGuid": "feb8e902-e475-4dfb-b029-456a952ec901", "serviceIdUrlSafe": "Aum4_nXk-02wKUVqlS7JAQ", "sta": "06:52", "eta": "Delayed", "std": "06:52", "etd": "Delayed", "platform": "13", "operator": "Southern", "operatorCode": "SN", "isCircularRoute": false, "isCancelled": false, "filterLocationCancelled": false, "serviceType": 0, "length": 8, "detachFront": false, "isReverseFormation": false, "cancelReason": null, "delayReason": "This train has been delayed by a fault on this train", "serviceID": "Aum4/nXk+02wKUVqlS7JAQ==", "adhocAlerts": null } ] }
CRS station codes are available from the following endpoint:
If query
is omitted then all CRS codes are returned along with their respective station
names.
If query
is provided then only station names matching it will be returned along with
their CRS codes.
/crs/oswald
[ { "stationName": "Church & Oswaldtwistle", "crsCode": "CTW" }, { "stationName": "Lazonby & Kirkoswald", "crsCode": "LZB" } ]
/crs/london terminals
returns all codes in the London station
group
The service ID can be found for each service inside the departures and arrivals response. Huxley also returns the ID in URL percent encoded, GUID and URL safe Base64 representations (for non-staff boards). Likewise, the service endpoint will accept URL safe Base64 service IDs, from various different encoders.
This endpoint also accepts the GUID representation of the ID
If the ID is a RID (a 15 digit long integer) then the staff API will be used. In this case a staff access token must be used (unless configured server side).
Source code is available on GitHub.
This project is treeware! If you found it useful then please plant a tree for me.
Licensed under the EUPL-1.2-or-later.
The EUPL covers distribution through a network or SaaS (like a compatible and interoperable AGPL).
© 2024 James Singleton