Huxley

Huxley

A JSON REST proxy for the UK National Rail
Live Departure Board SOAP API (Darwin)

Huxley is a CORS enabled JSON REST proxy for the UK National Rail Enquires Live Departure Board SOAP API (Darwin). It aims to make the API available to many more tools on multiple platforms. You no longer need to be running .NET on Windows to use Darwin.

If you want to be informed of updates when they are released then watch the project on GitHub and follow me on Twitter. If you are interested in cross-platform .NET then you may enjoy reading my new book, "ASP.NET Core 1.0 High Performance".

Huxley Technical Architecture

Access Tokens

You will need to add your access token to the URL for this to work. You can register to obtain one here (or here for the staff version).

Append the accessToken={Your GUID token} parameter to the query string 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.

You can set DarwinAccessToken to your NRE access token. If you leave ClientAccessToken as an empty GUID then no token is required in the Huxley URL. If you set ClientAccessToken to a random GUID 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. Look in the Web.config file for more details.

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.

API Endpoints

Station Boards

URL Format

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}?accessToken={Your GUID token}&expand=true

Examples:

Departures

/departures/{CRS|StationName}?accessToken={Your GUID token}

Arrivals

/arrivals/{CRS|StationName}?accessToken={Your GUID token}

Departures and Arrivals

/all/{CRS|StationName}?accessToken={Your GUID token}

Next

/next/{CRS|StationName}/{filterType}/{filterCRSs|StationNames}?accessToken={Your GUID token}

Filter stations can be a comma separated list. Filter type and number of rows are ignored.

Fastest

/fastest/{CRS|StationName}/{filterType}/{filterCRSs|StationNames}?accessToken={Your GUID token}

Filter stations can be a comma separated list. Filter type and number of rows are ignored.

Staff Departures

/staffdepartures/{CRS|StationName}?accessToken={Your GUID token}

Staff Arrivals

/staffarrivals/{CRS|StationName}?accessToken={Your GUID token}

Staff Departures and Arrivals

/staffall/{CRS|StationName}?accessToken={Your GUID token}

Staff Next

/staffnext/{CRS|StationName}/{filterType}/{filterCRSs|StationNames}?accessToken={Your GUID token}

Staff Fastest

/stafffastest/{CRS|StationName}/{filterType}/{filterCRSs|StationNames}?accessToken={Your GUID token}

Delays

The delays action performs calculations server side to easily let you know if there are problems on a particular route.

/delays/{CRS|StationName}/{filterType}/{filterCRS|StationName}/{numRows}?accessToken={Your GUID token}

Sample Response:
{
  "generatedAt": "2015-05-08T11:28:33.7187169+01:00",
  "locationName": "Clapham Junction",
  "crs": "CLJ",
  "filterLocationName": "London",
  "filtercrs": "LON",
  "delays": true,
  "totalTrainsDelayed": 1,
  "totalDelayMinutes": 16,
  "totalTrains": 12,
  "delayedTrains": [
    {
      "origin": [
        {
          "locationName": "London Waterloo",
          "crs": "WAT",
          "via": null,
          "futureChangeTo": null,
          "assocIsCancelled": false
        }
      ],
      "destination": [
        {
          "locationName": "London Waterloo",
          "crs": "WAT",
          "via": null,
          "futureChangeTo": null,
          "assocIsCancelled": false
        }
      ],
      "currentOrigins": null,
      "currentDestinations": null,
      "sta": null,
      "eta": null,
      "std": "11:20",
      "etd": "11:28",
      "platform": "3",
      "operator": "South West Trains",
      "operatorCode": "SW",
      "isCircularRoute": false,
      "serviceID": "F4GbTDZuLjb4VlXEYDuakg==",
      "adhocAlerts": null
    }
  ]
}

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/50/0729,0744,0748).

CRS Station Codes

CRS (Computer Reservation System) station codes are available from the following endpoint:

/crs/{query}

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.

Example response for/crs/oswald:

[
  {
    "stationName": "Church & Oswaldtwistle",
    "crsCode": "CTW"
  },
  {
    "stationName": "Lazonby & Kirkoswald",
    "crsCode": "LZB"
  }
]

/crs/london terminals returns all codes in the London station group.

[
  {
    "stationName": "London Blackfriars",
    "crsCode": "BFR"
  },
  {
    "stationName": "London Cannon Street",
    "crsCode": "CST"
  },
  {
    "stationName": "London Charing Cross",
    "crsCode": "CHX"
  },
  {
    "stationName": "City Thameslink",
    "crsCode": "CTX"
  },
  {
    "stationName": "London Euston",
    "crsCode": "EUS"
  },
  {
    "stationName": "London Fenchurch Street",
    "crsCode": "FST"
  },
  {
    "stationName": "London Kings Cross",
    "crsCode": "KGX"
  },
  {
    "stationName": "London Liverpool Street",
    "crsCode": "LST"
  },
  {
    "stationName": "London Bridge",
    "crsCode": "LBG"
  },
  {
    "stationName": "London Marylebone",
    "crsCode": "MYB"
  },
  {
    "stationName": "Moorgate",
    "crsCode": "MOG"
  },
  {
    "stationName": "Old Street",
    "crsCode": "OLD"
  },
  {
    "stationName": "London Paddington",
    "crsCode": "PAD"
  },
  {
    "stationName": "London St Pancras International",
    "crsCode": "STP"
  },
  {
    "stationName": "Vauxhall",
    "crsCode": "VXH"
  },
  {
    "stationName": "London Victoria",
    "crsCode": "VIC"
  },
  {
    "stationName": "London Waterloo",
    "crsCode": "WAT"
  },
  {
    "stationName": "London Waterloo East",
    "crsCode": "WAE"
  }
]

Service

/service/[Service ID]?accessToken=[Your GUID token]

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 as /, + and case sensitivity can cause trouble if you're not careful.

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

All the source code is available on GitHub.

SDKs

Client library SDKs in 9 languages (including Java and Ruby) for this endpoint (generated with Swagger) are available here.
If you use these make sure to change the endpoint for production.


Made by James Singleton

powered by National Rail Enquiries


© 2016 James Singleton

AGPL

This program is licensed under the terms of the GNU Affero General Public License. This means that you need to share any changes (even if only running on a public server).

If you would like another license (such as a commercial license with an invoice) then this can be provided. Please get in touch (send an email to jpsingleton at gmail dot com).

Contains public sector information licensed under the Open Government Licence v3.0.