national-rail-darwin

Introduction

national-rail-darwin aims to give you json object representations of the SOAP responses from National Rail's Darwin api. Details of the api can be found here

Currently only CRS codes are supported, a future update will allow full station names to be used. You can find a complete list of CRS codes on the National Rail website .

Installation

npm install national-rail-darwin

Usage

All 11 requests exposed by the Darwin api are available in national-rail-darwin

• getDepartureBoard(crsCode, options, callback)
• getArrivalsBoard(crsCode, options, callback)
• getArrivalsBoardWithDetails(crsCode, options, callback)
• getArrivalsDepartureBoard(crsCode, options, callback)
• getArrivalsDepartureBoardWithDetails(crsCode, options, callback)
• getServiceDetails(serviceId, callback)
• getNextDeparture(crsCode, destinationCrsCode, options, callback)
• getNextDepartureWithDetails(crsCode, destinationCrsCode, options, callback)
• getDepartureBoardWithDetails(crsCode, options, callback)
• getFastestDeparture(crsCode, destinationCrsCode, options, callback)
• getFastestDepartureWithDetails(crsCode, destinationCrsCode, options, callback)

Additional functions

• getStationDetails(Station, callback)

Your api token can either be provided when the client is created or picked up from the environment variable DARWIN_TOKEN.

  var Rail = require('national-rail-darwin')
  var rail = new Rail() // or -> new Rail(DARWIN_TOKEN)

Options

Some functions take an options object. See the specific method definitions for details of these.

Methods

All methods return arrays of basic service objects of the form:

{
  sta: '23:57',
  eta: 'On time',
  std: '23:57',
  etd: 'On time',
  platform: '2',
  delayReason: null,
  origin: {
    name:<stationname>,
    crs:<crsCode>
  },
  destination: {
    name:<stationname>,
    crs:<crsCode>
  },
  length: '5',
  serviceId: 'xxxxxxxxxxxxxxxx+xx/xxx=='
}

getDepartureBoard

rail.getDepartureBoard('WAT', {}, function(err,result){
    //do stuff
})

Gets all public departures for the supplied station within 2 hours. Options: 'destination': Only show trains that call at the supplied station. 'rows': Maximum number of services to retrieve (1 - 149).

getArrivalsBoard

rail.getArrivalsBoard('PUT', {}, function(err, result){
    //do stuff
})

Similar to getDepartureBoard but shows arrivals within the next two hours. Options: 'destination': Only show trains that have called at the supplied station. 'rows': Maximum number of services to retrieve.

getArrivalsBoardWithDetails

rail.getArrivalsBoardWithDetails('PUT', {}, function(err, result){
    //do stuff
})

Adds service details including previous calling points to the getArrivalsBoardResult. Options: 'destination': Only show trains that have called at the supplied station. 'rows': Maximum number of services to retrieve.

getArrivalsDepartureBoard

rail.getArrivalsDepartureBoard('PUT', {}, function(err, result){
    //do stuff
})

Returns all public arrivals and departures for the supplied CRS code within 2 hours. Options: 'destination': Only show trains that have called at the supplied station. 'rows': Maximum number of services to retrieve.

getArrivalsDepartureBoardWithDetails

rail.getArrivalsDepartureBoardWithDetails('PUT', {}, function(err, result){
    //do stuff
})

Returns array of train services with both previous and subsequent calling points included for each service. Options: 'destination': Only show trains that have called at the supplied station. 'rows': Maximum number of services to retrieve.

getServiceDetails

rail.getServiceDetails('SERVICE ID', function(err, result){
    //do stuff
})

Gets detailed information about a particular service relative to the station that generated the serviceId. ServiceId is returned from other calls such as getDepartureBoard or getNextDeparture. The object returns includes all calling points of the service requested. The data is only available while the particular service is showing on the station departure board. This is normally for up to two minutes after the service is expected to depart.

getNextDeparture

rail.getNextDeparture(crsCode, destinationCrsCode, {}, function(err, result){
    //do stuff
})

Returns the next train leaving from supplied station calling at the destination CRS Code.

getNextDepartureWithDetails

rail.getNextDepartureWithDetails(crsCode, destinationCrsCode, {}, function(err, result){
    //do stuff
})

Returns the next train leaving from supplied station calling at the destination CRS Code within two hours including subsequent calling points.

getDepartureBoardWithDetails

rail.getDepartureBoardWithDetails('WAT', {}, function(err,result){
    //do stuff
})

Adds a list of future calling points to the standard departure board response. 'destination': Only show trains that call at the supplied station. 'rows': Maximum number of services to retrieve.

getFastestDeparture

rail.getFastestDeparture('from', 'destination crs', {}, function(err,result){
    //do stuff
})

Returns the service with the earliest arrival time at the destination station leaving from the supplied station.

getFastestDepartureWithDetails

rail.getFastestDepartureWithDetails('from', 'destination crs', {}, function(err,result){
    //do stuff
})

Same response as getFastestDeparture but includes service details such as previous and subsequent calling points.

getStationDetails

rail.getStationDetails('Leeds', function(err,result){
    //do stuff
})

Look up station details including CRSCode from the full station name

Command Line

national-rail-darwin now provides a command line tool, darwin, for querying the Darwin API. All Darwin requests are accessible via this tool. Install globally and run

darwin --help

for usage details.

To authenticate using the command line you can either specify your API token using the --token flag or set DARWIN_TOKEN as an environment variable.

You can print the result as raw JSON by using the --json option if you want to manipulate the output with something like jq.

For example:

darwin --json -t XXX arr-board ANZ | jq '.trainServices[]'