NRE Logo Documentation for
Live Departure Boards Web Service (LDBWS / OpenLDBWS)
What is it?

LDBWS provides a request-response web service to access real time train information from Darwin. This is the same information that powers the Live Departure Boards, provided in XML format.

Where is it?

The latest WSDL may be found at https://www.livedepartureboards.co.uk/LDBWS/wsdl.aspx?ver=2014-02-20.

The current schema version is 2014-02-20.

The WSDL for any supported previous versions of the service can be found at https://www.livedepartureboards.co.uk/LDBWS/wsdl.aspx?ver=yyyy-mm-dd, where yyyy-mm-dd is replaced by the correct version number (obtained from the targetNamespace of the schema). Clients should always use the current version, but previous versions will continue to be maintained whenever possible. However, this cannot be guaranteed for all future changes, so developers should periodically check this page and the WSDL for new versions and migrate their clients to the latest version as soon as possible.

For the avoidance of doubt, be aware that the web service end-point, as defined in the WSDL interface, expects a SOAP XML message and cannot be accessed from a web browser.

How is it accessed?

LDBWS is provided as a SOAP web service. It is expected that a client will use an automatic proxy generation tool to produce the client proxy objects used to interface to the web service. Such a tool can be simply pointed at the URL given above, or the required WSDL & XSD files can be downloaded and used locally.

All licensed users will be issued with a token to access public web services. This token shall be passed as a SOAP Header value. The service will reject all requests with no token or an incorrect token code.

For those operations requiring a CRS code or codes to function, a list may be obtained at http://nationalrail.co.uk/passenger_services/info_on_the_move/station_codes/.

Supported Operations
Click to expand any of the options below for more details.

» GetDepartureBoard

Description
Returns all public departures for the supplied CRS code within a defined time window.

Parameters
All parameters must be supplied, but may be null. Parameters that may be null are marked optional.

numRows (integer, between 0 and 150 exclusive): The number of services to return in the resulting station board.
crs (string, 3 characters, alphanumeric): The CRS code (see above) of the location for which the request is being made.
filterCrs (string, 3 characters, alphanumeric): The CRS code of either an origin or destination location to filter in. Optional.
filterType (string, either "from" or "to"): The type of filter to apply. Filters services to include only those originating or terminating at the filterCrs location. Defaults to "to". Optional.
timeOffset (integer, between -120 and 120 exclusive): An offset in minutes against the current time to provide the station board for. Defaults to 0. Optional.
timeWindow (integer, between -120 and 120 exclusive): How far into the future in minutes, relative to timeOffset, to return services for. Defaults to 120. Optional.

Response
A StationBoard object containing the requested details.

» GetArrivalBoard

Description
Returns all public arrivals for the supplied CRS code within a defined time window.

Parameters
All parameters must be supplied, but may be null. Parameters that may be null are marked optional.

numRows (integer, between 0 and 150 exclusive): The number of services to return in the resulting station board.
crs (string, 3 characters, alphanumeric): The CRS code (see above) of the location for which the request is being made.
filterCrs (string, 3 characters, alphanumeric): The CRS code of either an origin or destination location to filter in. Optional.
filterType (string, either "from" or "to"): The type of filter to apply. Filters services to include only those originating or terminating at the filterCrs location. Defaults to "to". Optional.
timeOffset (integer, between -120 and 120 exclusive): An offset in minutes against the current time to provide the station board for. Defaults to 0. Optional.
timeWindow (integer, between -120 and 120 exclusive): How far into the future in minutes, relative to timeOffset, to return services for. Defaults to 120. Optional.

Response
A StationBoard object containing the requested details.

» GetArrivalDepartureBoard

Description
Returns all public arrivals and departures for the supplied CRS code within a defined time window.

Parameters
All parameters must be supplied, but may be null. Parameters that may be null are marked optional.

numRows (integer, between 0 and 150 exclusive): The number of services to return in the resulting station board.
crs (string, 3 characters, alphanumeric): The CRS code (see above) of the location for which the request is being made.
filterCrs (string, 3 characters, alphanumeric): The CRS code of either an origin or destination location to filter in. Optional.
filterType (string, either "from" or "to"): The type of filter to apply. Filters services to include only those originating or terminating at the filterCrs location. Defaults to "to". Optional.
timeOffset (integer, between -120 and 120 exclusive): An offset in minutes against the current time to provide the station board for. Defaults to 0. Optional.
timeWindow (integer, between -120 and 120 exclusive): How far into the future in minutes, relative to timeOffset, to return services for. Defaults to 120. Optional.

Response
A StationBoard object containing the requested details.

» GetServiceDetails

Description
Returns service details for a specific service identified by a station board. These details are supplied relative to the station board from which the serviceID field value was generated. Service details are only available while the service appears on the station board from which it was obtained. This is normally for two minutes after it is expected to have departed, or after a terminal arrival. If a request is made for a service that is no longer available then a null value is returned.

Parameters
All parameters must be supplied, but may be null. Parameters that may be null are marked optional.

serviceID (string): The LDBWS service ID of the service to request the details of. The service ID is obtained from a service listed in a StationBoard object returned from any other request.

Response
A ServiceDetails object containing the requested details.

If an error occurs during execution of an operation (including detection of invalid parameter values, or the unavailability of the underlying LDB service), it will be communicated back to the client by means of a SOAP Fault. This will usually be translated by the user's proxy generation tools to an exception in the generated language code.

Data Types
Click to expand any of the options below for more details.

» StationBoard
Object Member Name Object Member Description
generatedAt The time at which the station board was generated.
locationName The name of the location that the station board is for.
crs The CRS code of the location that the station board is for.
filterLocationName If a filter was requested, the location name of the filter location.
filtercrs If a filter was requested, the CRS code of the filter location.
filterType If a filter was requested, the type of filter.
nrccMessages An optional list of textual messages that should be displayed with the station board. The message may include embedded and xml encoded HTML-like hyperlinks and paragraphs. The messages are typically used to display important disruption information that applies to the location that the station board was for. Any embedded <p> tags are used to force a new-line in the output. Embedded <a> tags allow links to external web pages that may provide more information. Output channels that do not support HTML should strip out the <a> tags and just leave the enclosed text.
platformAvailable An optional value that indicates if platform information is available. If this value is present with the value "true" then platform information will be returned in the service lists. If this value is not present, or has the value "false", then the platform "heading" should be suppressed in the user interface for this station board.
areServicesAvailable An optional value that indicates if services are currently available for this station board. If this value is present with the value "false" then no services will be returned in the service lists. This value may be set, for example, if access to a station has been closed to the public at short notice, even though the scheduled services are still running. It would be usual in such cases for one of the nrccMessages to describe why the list of services has been suppressed.
trainServices
busServices
ferryServices
Each of these lists contains a ServiceItem object for each service of the relevant type that is to appear on the station board. Each or all of these lists may contain zero items, or may not be present at all.
» ServiceItem
Object Member Name Object Member Description
origin A list of ServiceLocation objects giving original origins of this service. Note that a service may have more than one original origin, if the service comprises of multiple trains that join at a previous location in the schedule. Original Origins will only be available for Arrival and Arrival & Departure station boards.
destination A list of ServiceLocation objects giving original destinations of this service. Note that a service may have more than one original destination, if the service comprises of multiple trains that divide at a subsequent location in the schedule. Original Destinations will only be available for Departure and Arrival & Departure station boards.
currentOrigins An optional list of ServiceLocation objects giving live/current origins of this service which is not starting at original cancelled origins. Note that a service may have more than one live origin. if the service comprises of multiple trains that join at a previous location in the schedule. Live Origins will only be available for Arrival and Arrival & Departure station boards.
currentDestinations An optional list of ServiceLocation objects giving live/current destinations of this service which is not ending at original cancelled destinations. Note that a service may have more than one live destination, if the service comprises of multiple trains that divide at a subsequent location in the schedule. Live Destinations will only be available for Departure and Arrival & Departure station boards.
sta An optional Scheduled Time of Arrival of the service at the station board location. Arrival times will only be available for Arrival and Arrival & Departure station boards but may also not be present at locations that are not scheduled to arrive at the location (e.g. the origin).
eta An optional Estimated Time of Arrival of the service at the station board location. Arrival times will only be available for Arrival and Arrival & Departure station boards and only where an sta time is present.
std An optional Scheduled Time of Departure of the service at the station board location. Departure times will only be available for Departure and Arrival & Departure station boards but may also not be present at locations that are not scheduled to depart at the location (e.g. the destination).
etd An optional Estimated Time of Departure of the service at the station board location. Departure times will only be available for Departure and Arrival & Departure station boards and only where an std time is present.
platform An optional platform number for the service at this location. This will only be present where available and where the station board platformAvailable value is "true".
operator The name of the Train Operating Company that operates the service.
operatorCode The code of the Train Operating Company that operates the service.
isCircularRoute If this value is present and has the value "true" then the service is operating on a circular route through the network and will call again at this location later on its journey. The user interface should indicate this fact to the user, to help them choose the correct service from a set of similar alternatives.
serviceID The unique service identifier of this service relative to the station board on which it is displayed. This value can be passed to GetServiceDetails to obtain the full details of the individual service.
adhocAlerts A list of Adhoc Alers related to this locationa for this service. This list contains an object called AdhocAlertTextType which contains a string to show the Adhoc Alert Text for the locaiton.
» ServiceLocation
Object Member Name Object Member Description
locationName The name of the location.
crs The CRS code of this location. A CRS code of ??? indicates an error situation where no crs code is known for this location.
via An optional via text that should be displayed after the location, to indicate further information about an ambiguous route. Note that vias are only present for ServiceLocation objects that appear in destination lists.
futureChangeTo A text string contianing service type (Bus/Ferry/Train) to which will be changed in the future.
assocIsCancelled This origin or destination can no longer be reached because the association has been cancelled.
» ServiceDetails
Object Member Name Object Member Description
generatedAt The time at which the service details were generated.
serviceType The type of service (train, bus, ferry) that these details represent. Note that real-time information (e.g. eta, etd, ata, atd, isCancelled, etc.) is only available and present for train services.
locationName The display name of the departure board location that these service details were accessed from.
crs The CRS code of the departure board location that these service details were accessed from.
operator The display name of the Train Operating Company that operates this service.
operatorCode The code of the Train Operating Company that operates this service.
isCancelled Indicates that the service is cancelled at this location.
disruptionReason A disruption reason for this service. If the service is cancelled, this will be a cancellation reason. If the service is running late at this location, this will be a late-running reason.
overdueMessage If an expected movement report has been missed, this will contain a message describing the missed movement.
platform The platform number that the service is expected to use at this location, if known and available.
sta The scheduled time of arrival of this service at this location. If no sta is present then this is the origin of this service or it does not set down passengers at this location.
eta The estimated time of arrival. Will only be present if sta is also present and ata is not present.
ata The actual time of arrival. Will only be present if sta is also present and eta is not present.
std The scheduled time of departure of this service at this location. If no std is present then this is the destination of this service or it does not pick up passengers at this location.
etd The estimated time of departure. Will only be present if std is also present and atd is not present.
atd The actual time of departure. Will only be present if std is also present and etd is not present.
adhocAlerts A list of active Adhoc Alert texts for to this location. This list contains an object called AdhocAlertTextType which contains a string to show the Adhoc Alert Text for the locaiton.
previousCallingPoints A list of lists of CallingPoint objects representing the previous calling points in the journey. A separate calling point list will be present for each origin of the service, relative to the current location.
subsequentCallingPoints A list of lists of CallingPoint objects representing the subsequent calling points in the journey. A separate calling point list will be present for each destination of the service, relative to the current location.

The calling point lists in the ServiceDetails object need further explanation. It is possible for certain trains to be formed from multiple separate trains, or to split into multiple trains, at certain points in their schedule. In such circumstances, some trains may have multiple origins or destinations and therefore, there may be multiple lists of calling points in the previousCallingPoints or subsequentCallingPoints properties. The first list of calling points will be for the "through" train and will hold all of the locations from the origin (for previousCallingPoints) or to the destination (for subsequentCallingPoints). The remaining lists will hold the locations of joining/splitting trains from/to their respective origins/destinations. The point at which the association is made is determined by examining the last location in the previousCallingPoints list, or the first location in the subsequentCallingPoints list. To get a better idea of how this works, look at a Train Details page on the LDB web site for a train that has an association. A good station to look for such trains would be Gatwick Airport [GTW].

» CallingPoint
Object Member Name Object Member Description
locationName The display name of this location.
crs The CRS code of this location. A CRS code of ??? indicates an error situation where no crs code is known for this location.
st The scheduled time of the service at this location. The time will be either an arrival or departure time, depending on whether it is in the subsequent or previous calling point list.
et The estimated time of the service at this location. The time will be either an arrival or departure time, depending on whether it is in the subsequent or previous calling point list. Will only be present if an actual time (at) is not present.
at The actual time of the service at this location. The time will be either an arrival or departure time, depending on whether it is in the subsequent or previous calling point list. Will only be present if an estimated time (et) is not present.
adhocAlerts A list of active Adhoc Alert texts for to this location. This list contains an object called AdhocAlertTextType which contains a string to show the Adhoc Alert Text for the locaiton.

In the objects detailed above, certain properties were specified to return time values. These values will either return absolute times, formatted as a HH:MM string, or a text string such as (but not limited to) "On time", "No report" or "Cancelled". These times should be output in the user interface exactly as supplied. In some cases, the time value may have an asterisk ("*") appended to indicate that the value is "uncertain".