KnowledgeBase: Difference between revisions

From Open Rail Data Wiki
m Tidy up formatting and simplify language
Line 1: Line 1:
= About =
= About =
Knowledgebase is RDG’s Content Management System providing customer friendly information on the railways and associated
products. ''It contains a wealth of static and real-time information about traveling by train on the GB rail network, such
as information about station facilities, service disruption, and engineering work.''


Knowledgebase data is available on National Rail Data Portal through 2 subscription types:
Knowledgebase is RDG’s Content Management System providing customer friendly information on the railways and associated products. It contains a wealth of static and real-time information about traveling by train on the GB rail network, such as information about station facilities, service disruption, and engineering work.


Knowledgebase (KB), Real Time incidents – for new, modified and deleted Incidents
Data is available on the National Rail Data Portal through two subscription types:


Knowledgebase (KB), API for requesting the latest information on the following static data
* Real Time incidents - for new, modified and deleted Incidents
* Companies (TOCs)
* Knowledgebase API - for requesting the latest information on the following static data
* Incidents (Service Disruptions and Engineering Works)
** Companies (TOCs)
* National Service Indicator (NSI)
** Incidents (Service Disruptions and Engineering Works)
* Promotions (Public)
** National Service Indicator (NSI)
* Stations
** Promotions (Public)
* Ticket Restrictions
** Stations
* Ticket Types
** Ticket Restrictions
** Ticket Types


= Accessing the Knowledgebase Feeds =
= Accessing the Knowledgebase Feeds =
To access the RDG Knowledgebase feeds, you must have an account on the National Rail Data Portal (NRDP) at
http://opendata.nationalrail.co.uk. By creating an account, you can register for a subscription to the Knowledgebase API
and the Knowledgebase Real Time Feeds.


To receive Knowledgebase Real Time Incidents, select Knowledgebase (KB) Real Time Incidents under the Knowlegebase (KB)
To access the RDG Knowledgebase feeds, you must have an account on the National Rail Data Portal (NRDP) at http://opendata.nationalrail.co.uk. By creating an account, you can register for a subscription to the Knowledgebase API and the Knowledgebase Real Time Feeds.
subscriptions. The connection information required to start receiving Real Time Incidents is located on the My Feeds page.


To receive Knowldegebase static data, select Knowledgebase (KB) API under the Knowledgebase (KB) subscriptions. The My
To receive Knowledgebase Real Time Incidents, select Knowledgebase (KB) Real Time Incidents under the Knowlegebase (KB) subscriptions. The connection information required to start receiving Real Time Incidents is located on the My Feeds page.
Feeds page will then display details about accessing the latest versions of Ticket Restrictions, Companies, Incidents,
National Service Indicator, Promotions (Public), Stations and Ticket Types files from Knowledgebase.


'''Important''' - Please note NRDP accounts expire after an extended period of inactivity. The unused account expiry period is
To receive Knowldegebase static data, select Knowledgebase (KB) API under the Knowledgebase (KB) subscriptions. The My Feeds page will then display details about accessing the latest versions of Ticket Restrictions, Companies, Incidents, National Service Indicator, Promotions (Public), Stations and Ticket Types files from Knowledgebase.
currently set to 30 days. If you create an account and do not consume any of the feeds during this time your account
 
will be deleted. If your account has been deleted, you will receive a notification email, and you will be able to
'''Important''' - Please note NRDP accounts expire after an extended period of inactivity. The unused account expiry period is currently set to 30 days. If you create an account and do not consume any of the feeds during this time your account will be deleted. If your account has been deleted, you will receive a notification email, and you will be able to re-register for a new account.
re-register for a new account.


= RDG Knowledgebase APIs =
= RDG Knowledgebase APIs =


== Knowledgebase API ==
== Knowledgebase API ==
After selecting the Knowledgebase (KB) API checkbox subscription type on NRDP, you can receive the Knowledgebase xml
files in 2 steps via a rest client.


Step 1: Perform HTTP POST call to NRDP via https://opendata.nationalrail.co.uk/authenticate to generate a token.
After selecting the Knowledgebase (KB) API checkbox subscription type on NRDP, you can receive the Knowledgebase xml files in two steps via a REST client.


Step 2: Perform HTTP GET call to individual NRDP Knowledgebase Feeds using the token produced in step 1
=== Generate Authentication Token ===


=== Step 1: Generate Authentication Token ===
Using a REST client, make an HTTP POST call to https://opendata.nationalrail.co.uk/authenticate. This step requires using your email address and password registered on NRDP and will produce a token key.
In this step, using a REST client you perform an HTTP POST call to https://opendata.nationalrail.co.uk/authenticate.
This step requires using your email address and password registered on NRDP and will produce a token key. The following
example shows the HTTP POST request and response with NRDP:


==== Request (Form-Encoded) ====
An example request is as follows:


POST https://opendata.nationalrail.co.uk/authenticate
  POST https://opendata.nationalrail.co.uk/authenticate


     Content-Type: application/x-www-form-urlencoded
     Content-Type: application/x-www-form-urlencoded
     username=jane@doe.com&password=password
     username=jane@doe.com&password=password```
 
==== Request (JSON Body) ====
 
POST https://opendata.nationalrail.co.uk/authenticate
 
    {
      "username": "jane@doe.com",
      "password": "password"
    }


==== Response (Ok) ====
A successful response will produce the following:


     {
     {
Line 76: Line 53:
     }
     }


The generated token is valid for 1 hour.
The token is valid for an hour, and includes the time at which it will expire, in UNIX seconds.


==== Response (Error) ====
An unsuccessful response will produce an HTTP 401 Unauthorized response with an error, such as:
 
If the credentials in the request payload are invalid, you will receive a 401 unauthorized response and JSON error body.
The following http response example is generated after sending invalid credentials with the request.


     {
     {
Line 87: Line 61:
     }
     }


==== Step 2: Perform a HTTP GET call for each Knowledgebase file ====
==== Make a call for each file ====
With an authentication token, performing a GET request will return the XML Knowledgebase data in the response.


Following the previous example, and wishing to consume the Ticket Restrictions feed:
Once you have a valid authentication token, you can make an HTTP GET request.  Supply the authentication token in a header named `X-Auth-Token`:


==== Request ====
  GET https://opendata.nationalrail.co.uk/api/staticfeeds/4.0/ticket-restrictions
 
GET https://opendata.nationalrail.co.uk/api/staticfeeds/4.0/ticket-restrictions


     X-Auth-Token: jane@doe.com:1491312310772:56c56baa3e56d35ff0ede4a6aad1bcfb
     X-Auth-Token: jane@doe.com:1491312310772:56c56baa3e56d35ff0ede4a6aad1bcfb


Using the returned authentication token as an X-Auth-Token header.
A successful response will result in the requested file:
 
==== Response (Ok) ====


     <?xml version="1.0" encoding="utf-8"?>
     <?xml version="1.0" encoding="utf-8"?>
Line 106: Line 75:
     ...
     ...


==== Response (Unauthenticated) ====
If authorization failed, the response will be an HTTP 401 Unauthorized:


     {
     {
Line 116: Line 85:
     }
     }


==== Response (Not Subscribed to Knowledgebase API) ====
If you are not subscribed to the Knowledgebase API,  the response will be an HTTP 403 Forbidden:


     {
     {
Line 127: Line 96:


=== Stations ===
=== Stations ===
In the stations data, London St Pancras and Ashford International both have have ''two'' entries each, intended to correspond to domestic services and facilities (STP and AFK), and those dedicated to international facilities (SPX and ASI). These second entries are not maintained, and these CRS codes, derived from underlying Network Rail data, are not recognised by LDB, or in the Darwin push port reference data, which mantains the National Rail convention of one CRS code per station (here STP and AFK). These entries bear confusingly similar names to the more canonical ones, and may be sorted before them, something to consider if you're allowing a user to search stations.
In the stations data, London St Pancras and Ashford International both have have ''two'' entries each, intended to correspond to domestic services and facilities (STP and AFK), and those dedicated to international facilities (SPX and ASI). These second entries are not maintained, and these CRS codes, derived from underlying Network Rail data, are not recognised by LDB, or in the Darwin push port reference data, which mantains the National Rail convention of one CRS code per station (here STP and AFK). These entries bear confusingly similar names to the more canonical ones, and may be sorted before them, something to consider if you're allowing a user to search stations.



Revision as of 14:50, 27 February 2022

About

Knowledgebase is RDG’s Content Management System providing customer friendly information on the railways and associated products. It contains a wealth of static and real-time information about traveling by train on the GB rail network, such as information about station facilities, service disruption, and engineering work.

Data is available on the National Rail Data Portal through two subscription types:

  • Real Time incidents - for new, modified and deleted Incidents
  • Knowledgebase API - for requesting the latest information on the following static data
    • Companies (TOCs)
    • Incidents (Service Disruptions and Engineering Works)
    • National Service Indicator (NSI)
    • Promotions (Public)
    • Stations
    • Ticket Restrictions
    • Ticket Types

Accessing the Knowledgebase Feeds

To access the RDG Knowledgebase feeds, you must have an account on the National Rail Data Portal (NRDP) at http://opendata.nationalrail.co.uk. By creating an account, you can register for a subscription to the Knowledgebase API and the Knowledgebase Real Time Feeds.

To receive Knowledgebase Real Time Incidents, select Knowledgebase (KB) Real Time Incidents under the Knowlegebase (KB) subscriptions. The connection information required to start receiving Real Time Incidents is located on the My Feeds page.

To receive Knowldegebase static data, select Knowledgebase (KB) API under the Knowledgebase (KB) subscriptions. The My Feeds page will then display details about accessing the latest versions of Ticket Restrictions, Companies, Incidents, National Service Indicator, Promotions (Public), Stations and Ticket Types files from Knowledgebase.

Important - Please note NRDP accounts expire after an extended period of inactivity. The unused account expiry period is currently set to 30 days. If you create an account and do not consume any of the feeds during this time your account will be deleted. If your account has been deleted, you will receive a notification email, and you will be able to re-register for a new account.

RDG Knowledgebase APIs

Knowledgebase API

After selecting the Knowledgebase (KB) API checkbox subscription type on NRDP, you can receive the Knowledgebase xml files in two steps via a REST client.

Generate Authentication Token

Using a REST client, make an HTTP POST call to https://opendata.nationalrail.co.uk/authenticate. This step requires using your email address and password registered on NRDP and will produce a token key.

An example request is as follows:

  POST https://opendata.nationalrail.co.uk/authenticate
   Content-Type: application/x-www-form-urlencoded
   username=jane@doe.com&password=password```

A successful response will produce the following:

   {
    "username": "jane@doe.com",
    "roles": {
      "ROLE_STANDARD": true,
      "ROLE_KB_API": true
    },
    "token": "jane@doe.com:1491312310772:56c56baa3e56d35ff0ede4a6aad1bcfb"
   }

The token is valid for an hour, and includes the time at which it will expire, in UNIX seconds.

An unsuccessful response will produce an HTTP 401 Unauthorized response with an error, such as:

   {
     "error": "Invalid username/password"
   }

Make a call for each file

Once you have a valid authentication token, you can make an HTTP GET request. Supply the authentication token in a header named `X-Auth-Token`:

  GET https://opendata.nationalrail.co.uk/api/staticfeeds/4.0/ticket-restrictions
   X-Auth-Token: jane@doe.com:1491312310772:56c56baa3e56d35ff0ede4a6aad1bcfb

A successful response will result in the requested file:

   <?xml version="1.0" encoding="utf-8"?>
   <TicketRestrictions
   ...

If authorization failed, the response will be an HTTP 401 Unauthorized:

   {
       "timestamp": "2019-02-13T11:50:16.048+0000",
       "status": 401,
       "error": "Unauthorized",
       "message": "Unauthorized",
       "path": "/api/staticfeeds/4.0/ticket-restrictions"
   }

If you are not subscribed to the Knowledgebase API, the response will be an HTTP 403 Forbidden:

   {
       "timestamp": "2019-02-13T11:51:29.992+0000",
       "status": 403,
       "error": "Forbidden",
       "message": "Forbidden",
       "path": "/api/staticfeeds/4.0/ticket-restrictions"
   }

Stations

In the stations data, London St Pancras and Ashford International both have have two entries each, intended to correspond to domestic services and facilities (STP and AFK), and those dedicated to international facilities (SPX and ASI). These second entries are not maintained, and these CRS codes, derived from underlying Network Rail data, are not recognised by LDB, or in the Darwin push port reference data, which mantains the National Rail convention of one CRS code per station (here STP and AFK). These entries bear confusingly similar names to the more canonical ones, and may be sorted before them, something to consider if you're allowing a user to search stations.

Real Time Incident Feed

After selecting the Knowledgebase Real Time incidents checkbox subscription on edit account page, connection details will appear on the My Feeds page. You can receive the Knowledgebase real time incidents via a STOMP or Apache MQ OpenWire client.

The setup of the client is very similar to that needed to subscribe to the Darwin PushPort feed. In particular, your client must support STOMP v1.2. Connect to the Message topic host using the credentials and topic name shown on My Feeds/ Knowledgebase Real Time Incidents Information. Note that unlike Darwin PushPort, the body of the Knowledgebase messages are not compressed.

Please note: topic advisory messages are disabled on the KB Real Time Incidents messaging host, so you must also connect with this facility disabled. E.g. set the connection property watchTopicAdvisories=false.

Upon successfully connecting to the feed, you will start receiving each real time incident message, with its respective incident number and other message information. The feed is relatively low volume with typically only 1-2 messages per hour and often gaps of several hours overnight, so any monitoring of message volumes should be configured appropriately.


Headers

Real time incidents messages contain the following headers:

INCIDENT_MESSAGE_STATUS

Each message will contain a INCIDENT_MESSAGE_STATUS header, with the possible values:

  • NEW: This status represents new incident message information
  • MODIFIED: This status represents modifications to existing incidents message information
  • REMOVED: This status represents deleted message information

KNOWLEDGEBASE_DATA_TYPE

Each message contains a KNOWLEDGEBASE_DATA_TYPE detailing that the message is an INCIDENT_MESSAGE.

INCIDENT_ID

The ID of the Knowledgebase Incident message.

Example Real Time Incidents Bodies

The following are examples of Real Time Incidents which include new, modified and deleted incident messages. Please note that these bodies are unzipped, real messages contain gzipped data.

New Incident message

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<uk.co.nationalrail.xml.incident.PtIncidentStructure xmlns:ns2="http://nationalrail.co.uk/xml/common" xmlns:ns3="http://nationalrail.co.uk/xml/incident">
<ns3:CreationTime>2017-03-21T16:17:00.000Z</ns3:CreationTime>
<ns3:ChangeHistory><ns2:ChangedBy>SPimperton</ns2:ChangedBy>
<ns2:LastChangedDate>2017-03-26T07:01:00.000+01:00</ns2:LastChangedDate></ns3:ChangeHistory>
<ns3:ParticipantRef>73913</ns3:ParticipantRef>
<ns3:IncidentNumber>214453059CDC4017A0E32F3A6ECA0D45</ns3:IncidentNumber>
<ns3:Version>20170326070125</ns3:Version>
<ns3:Source><ns3:TwitterHashtag>#SouthernStrike</ns3:TwitterHashtag></ns3:Source>
<ns3:ValidityPeriod><ns2:StartTime>2017-03-21T16:17:00.000Z</ns2:StartTime></ns3:ValidityPeriod>
<ns3:Planned>false</ns3:Planned>
<ns3:Summary>Possible industrial action to affect Southern services on Saturday 8 April</ns3:Summary>
<ns3:Description>
<p>The RMT Union have announced they are planning to take industrial action on Saturday 8 April.</p>
<p>It is not yet known how Southern services will be affected, if this industrial action goes ahead.</p>
<p><strong>Twitter:</strong><br />
If you would like to follow this incident on Twitter, please use <a href="https://twitter.com/hashtag/SouthernStrike?f=tweets">#SouthernStrike</a></p>
</ns3:Description>
<ns3:InfoLinks>
<ns3:InfoLink><ns3:Uri>http://www.nationalrail.co.uk/service_disruptions/160174.aspx</ns3:Uri>
<ns3:Label>nationalrail.co.uk</ns3:Label></ns3:InfoLink></ns3:InfoLinks>
<ns3:Affects><ns3:Operators><ns3:AffectedOperator><ns3:OperatorRef>SN</ns3:OperatorRef>
<ns3:OperatorName>Southern</ns3:OperatorName></ns3:AffectedOperator></ns3:Operators>
<ns3:RoutesAffected><p>Various Southern routes</p></ns3:RoutesAffected></ns3:Affects>
<ns3:ClearedIncident>false</ns3:ClearedIncident>
<ns3:IncidentPriority>2</ns3:IncidentPriority></uk.co.nationalrail.xml.incident.PtIncidentStructure>
...

Modified Incident Message

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<uk.co.nationalrail.xml.incident.PtIncidentStructure xmlns:ns2="http://nationalrail.co.uk/xml/common" xmlns:ns3="http://nationalrail.co.uk/xml/incident">
<ns3:CreationTime>2017-04-24T17:22:00.000+01:00</ns3:CreationTime>
<ns3:ChangeHistory><ns2:ChangedBy>bives</ns2:ChangedBy>
<ns2:LastChangedDate>2017-04-24T17:32:00.000+01:00</ns2:LastChangedDate>
</ns3:ChangeHistory><ns3:IncidentNumber>8B3B4C1F358A45A186F6F95984F52F4F</ns3:IncidentNumber>
<ns3:Version>20170424173219</ns3:Version>
<ns3:Source><ns3:TwitterHashtag>#CrystalPalace</ns3:TwitterHashtag></ns3:Source>
<ns3:ValidityPeriod><ns2:StartTime>2017-04-24T17:22:00.000+01:00</ns2:StartTime></ns3:ValidityPeriod>
<ns3:Planned>false</ns3:Planned><ns3:Summary>Delays in theCrystal Palace area expected until 20:15</ns3:Summary>
<ns3:Description>
<p>Due <span>to trespassers on the railway at Crystal Palace trains have to run at reduced speed on all lines.
<br /><br /><strong>Impact:</strong>
<br />Train services running through this station may be cancelled or delayed by up to20 minutes. Disruption is expected until 20:15 24/04.<br />
<br /><strong>Customer Advice:</strong>
<br />Owing to a passenger forcing the doors open and exiting the train onto the trackin the Crystal Palace area trains are obliged to run at a reduced speed.<br/></span></p>
<p><strong>Twitter:</strong><br />If you would like to follow this incident on Twitter, please use
 <a href="https://twitter.com/hashtag/CrystalPalace?f=tweets">#</a><span><a href="https://twitter.com/hashtag/CrystalPalace?f=tweets">CrystalPalace</a> </span></p>
 <p><strong>Check before you travel:</strong><br />Please use the National Rail Enquiries real-time
 <a href="http://ojp.nationalrail.co.uk/service/planjourney/search">Journey Planner</a> to check your journey before you travel.</p>
 <p><strong>Compensation:</strong><br />You may be entitled to <a href="http://www.nationalrail.co.uk/times_fares/ticket_types/121354.aspx">
 compensation</a> if you experience a delay in completing your journey today.
 Please keep your train ticket and make a note of your journey, as both will be required to support any claim.</p>
 <p><strong>Feedback:</strong><br />We want to make information better - tell us how! Fill out this online
 <a href="http://survey3.accent-mr.com/D4/(S(dtxglkj3ksyum52j0j01qpio))/2908m.aspx?urn=opensurveyNRwebsite">Disruption Survey.</a></p></ns3:Description>
<ns3:InfoLinks><ns3:InfoLink><ns3:Uri>http://www.nationalrail.co.uk/service_disruptions/162083.aspx</ns3:Uri>
<ns3:Label>nationalrail.co.uk</ns3:Label></ns3:InfoLink>
<ns3:InfoLink><ns3:Uri>http://www.nationalrail.co.uk/static/documents/maps/Crystal2404.pdf</ns3:Uri>
<ns3:Label>Additional Maps</ns3:Label></ns3:InfoLink></ns3:InfoLinks>
<ns3:Affects><ns3:Operators><ns3:AffectedOperator><ns3:OperatorRef>SN</ns3:OperatorRef>
<ns3:OperatorName>Southern</ns3:OperatorName></ns3:AffectedOperator></ns3:Operators>
<ns3:RoutesAffected><p>Routes through Crystal Palace</p></ns3:RoutesAffected></ns3:Affects>
<ns3:ClearedIncident>false</ns3:ClearedIncident>
<ns3:IncidentPriority>2</ns3:IncidentPriority></uk.co.nationalrail.xml.incident.PtIncidentStructure>
...

Removed Incident Message

Removed messages contain empty bodies.


Support

KnowledgeBase XML schemas:

Supporting/referenced schemas:

KnowledgeBase specification:


National Rail Enquiries Data Feeds
Data Feeds About the Feeds Darwin Webservice (Public) Darwin Webservice (Staff) Historical Service Performance Push Port KnowledgeBaseDTDLocations (PoC)Real Time Journey Planner
LDB API About
LDB-SV API About
HSP About
DTD About Fares Timetable
Push Port About XML Schemas Schedules Associations Train Status Station Messages Alarms Train Order Train Alerts Formations Formation loading