Difference between revisions of "KnowledgeBase"

From Open Rail Data Wiki
Jump to: navigation, search
(Step 2: Perform a HTTP GET call for each KnowledgeBase file)
 
(41 intermediate revisions by 4 users not shown)
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 is RDG’s Content Management System providing customer friendly information on the railways and associated products.
+
Knowledgebase data is available on National Rail Data Portal through 2 subscription types:
KnowledgeBase data is available on National Rail Data Portal through 2 subscription types
 
* Real Time Data Feeds – for new, modified and deleted Incidents
 
* On Demand Data Feeds – for requesting the latest information on the following
 
** Ticket Restrictions
 
** Companies
 
** Incidents
 
** National Service Indicator
 
** Promotions (Public)
 
** Stations
 
** Ticket Types
 
  
== Accessing the KnowledgeBase Feeds ==
+
Knowledgebase (KB), Real Time incidents – for new, modified and deleted Incidents
  
To access the RDG KnowledgeBase feeds, you must have an account on the National Rail Data Portal (NRDP) at http://datafeeds.nationalrail.co.uk. After logging in, you will see 3 subscription types: Historical Service Performance (HSP), Real Time Data Feeds and On Demand Data Feeds. By selecting the checkbox for each of these subscription types, the respective sections become visible on the My Feeds page.
+
Knowledgebase (KB), 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
  
The previous Darwin Data Feed on the NRDP Account page has been replaced by the Real Time Data Feed which once selected include details about the Darwin push-port feeds and the KnowledgeBase – Real Time Incident feed in the My Feeds page.
+
= 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 Real Time Data Feeds under Subscription Type in the Edit User Details page and then select the Update button to save this change. Go to the My Feeds page and select the KnowledgeBase data type – Real Time Incidents option. You will need the [http://nrodwiki.rockshore.net/index.php/Darwin:Push_Port#Accessing_real-time_data/ Real Time Information /STOMP details] to start receiving real time incident messages via a STOMP client.
+
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.
  
The On Demand Data Feeds section on the My Feeds page contains details about accessing the latest versions of Ticket Restrictions, Companies, Incidents, National Service Indicator, Promotions (Public), Stations and Ticket Types files from KnowledgeBase. To receive these KnowledgeBase files, select the On Demand Data Feeds checkbox under the Subscription type in the Edit User Details page and then select the update button to save this change.
+
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.
  
== RDG KnowledgeBase APIs ==
+
'''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.
  
=== On Demand Data Feeds ===
+
= RDG Knowledgebase APIs =
After selecting the On Demand checkbox subscription type on NRDP, you can receive the KnowlegeBase xml files in 2 steps via a rest client.
 
* Step 1: Perform HTTP POST call to NRDP via https://datafeeds.nationalrail.co.uk/authenticate to generate a token.
 
* Step 2: Perform HTTP GET call to individual NRDP Knowledgebase Feeds using the token produced in step 1
 
==== Step 1: Generate Token ====
 
In this step, using a REST client you perform an HTTP POST call to https://datafeeds.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:
 
: Example HTTP POST Request to NRDP:
 
  <code><pre> POST https://datafeeds.nationalrail.co.uk/authenticate HTTP/1.1
 
  Content-Type: application/x-www-form-urlencoded
 
  Accept: application/json, text/plain, */*
 
  Raw payload: username=user1@gmail.com&password=P@55w0rd1
 
  //Add your registered NRDP email address and NRDP password in the “Raw payload” section above </pre></code>
 
: Corresponding example HTTP Response from NRDP:
 
<code><pre> {
 
"username": " user1@gmail.com ",
 
"roles": {
 
"Role(id=6ab28d46-0e4a-11e7-9339-060a84373309, name='ROLE_KB_USER')": true,
 
"Role(id=47d36dc4-16b9-11e6-9746-060a84373309, name='ROLE_HSP_USER')": true,
 
"Role(id=4e660138-bb39-11e4-9da1-060a84373309, name='ROLE_D3_USER')": true
 
},
 
"token": " user1@gmail.com:1491312310772:56c56baa3e56d35ff0ede4a6aad1bcfb"
 
} </pre></code>
 
  
Each token is valid for 1 hour and you will receive a 401 unauthorized response when the token has expired. The following http response example is generated after sending an http request to a NRDP knowledgebase feed with an expired token.
+
== Knowledgebase API ==
: Example HTTP 401 Response Header: Token Expired:
+
After selecting the Knowledgebase (KB) API checkbox subscription type on NRDP, you can receive the Knowledgebase xml
<code><pre> Cache-Control: no-cache, no-store, max-age=0, must-revalidate
+
files in 2 steps via a rest client.
Content-Language: en
+
 
Content-Length: 1081
+
Step 1: Perform HTTP POST call to NRDP via https://opendata.nationalrail.co.uk/authenticate to generate a token.
Content-Type: text/html;charset=utf-8
+
 
Date: Wed, 05 Apr 2017 09:52:11 GMT
+
Step 2: Perform HTTP GET call to individual NRDP Knowledgebase Feeds using the token produced in step 1
Expires: 0
+
 
Pragma: no-cache
+
=== Step 1: Generate Authentication Token ===
Server: Apache-Coyote/1.1
+
In this step, using a REST client you perform an HTTP POST call to https://opendata.nationalrail.co.uk/authenticate.
X-Content-Type-Options: nosniff
+
This step requires using your email address and password registered on NRDP and will produce a token key. The following
X-Frame-Options: DENY
+
example shows the HTTP POST request and response with NRDP:
X-Xss-Protection: 1; mode=block </pre></code>
+
 
: Corresponding example HTML Response file: Token Expired:
+
==== Request (Form-Encoded) ====
<code><pre> <html>
+
 
<head>
+
POST https://opendata.nationalrail.co.uk/authenticate
<title>Apache Tomcat/7.0.56 - Error report</title>
+
 
<style>
+
    Content-Type: application/x-www-form-urlencoded
<!--H1 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-
+
    username=jane@doe.com&password=password
size:16px;} H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY {font-family:Tahoma,Arial,sans-serif;color:black;background-
+
 
color:white;} B {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P {font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}A
+
==== Request (JSON Body) ====
{color : black;}A.name {color : black;}HR {color : #525D76;}-->
+
 
</style> </head>
+
POST https://opendata.nationalrail.co.uk/authenticate
<body>
+
 
<h1>HTTP Status 401 - Unauthorized: Authentication token was either missing or invalid.</h1>
+
    {
<HR size="1" noshade="noshade">
+
      "username": "jane@doe.com",
<p>
+
      "password": "password"
<b>type</b> Status report</p>
+
    }
<p>
+
 
<b>message</b> <u>Unauthorized: Authentication token was either missing or invalid.</u>
+
==== Response (Ok) ====
</p>
+
 
<p>
+
    {
<b>description</b> <u>This request requires HTTP authentication.</u>
+
    "username": "jane@doe.com",
</p>
+
    "roles": {
<HR size="1" noshade="noshade">
+
      "ROLE_STANDARD": true,
<h3>Apache Tomcat/7.0.56</h3>
+
      "ROLE_KB_API": true
</body>
+
    },
</html> </pre></code>
+
    "token": "jane@doe.com:1491312310772:56c56baa3e56d35ff0ede4a6aad1bcfb"
 +
    }
 +
 
 +
The generated token is valid for 1 hour.
 +
 
 +
==== Response (Error) ====
 +
 
 +
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.
 +
 
 +
    {
 +
      "error": "Invalid username/password"
 +
    }
 +
 
 +
==== Step 2: Perform a HTTP GET call for each Knowledgebase 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:
 +
 
 +
==== Request ====
 +
 
 +
GET https://opendata.nationalrail.co.uk/api/staticfeeds/4.0/ticket-restrictions
 +
 
 +
    X-Auth-Token: jane@doe.com:1491312310772:56c56baa3e56d35ff0ede4a6aad1bcfb
 +
 
 +
Using the returned authentication token as an X-Auth-Token header.
 +
 
 +
==== Response (Ok) ====
 +
 
 +
    <?xml version="1.0" encoding="utf-8"?>
 +
    <TicketRestrictions
 +
    ...
 +
 
 +
==== Response (Unauthenticated) ====
 +
 
 +
    {
 +
        "timestamp": "2019-02-13T11:50:16.048+0000",
 +
        "status": 401,
 +
        "error": "Unauthorized",
 +
        "message": "Unauthorized",
 +
        "path": "/api/staticfeeds/4.0/ticket-restrictions"
 +
    }
 +
 
 +
==== Response (Not Subscribed to Knowledgebase API) ====
 +
 
 +
    {
 +
        "timestamp": "2019-02-13T11:51:29.992+0000",
 +
        "status": 403,
 +
        "error": "Forbidden",
 +
        "message": "Forbidden",
 +
        "path": "/api/staticfeeds/4.0/ticket-restrictions"
 +
    }
  
==== Step 2: Perform a HTTP GET call for each KnowledgeBase file ====
 
In this step using a REST client, you would perform a HTTP GET call to each Knowledgebase file using the token key produced in step 1. This will produce the xml file for the corresponding KnowledgeBase feeds.
 
The following are the required links to make the respective HTTP GET call:
 
* Ticket Restrictions: https://datafeeds.nationalrail.co.uk/api/staticfeeds/4.0/ticket-restrictions
 
* Companies: https://datafeeds.nationalrail.co.uk/api/staticfeeds/4.0/tocs
 
* Incidents: https://datafeeds.nationalrail.co.uk/api/staticfeeds/5.0/incidents
 
* National Service Indicator: https://datafeeds.nationalrail.co.uk/api/staticfeeds/4.0/serviceIndicators
 
* Promotions (Public): https://datafeeds.nationalrail.co.uk/api/staticfeeds/4.0/promotions-publics
 
* Stations: https://datafeeds.nationalrail.co.uk/api/staticfeeds/4.0/stations
 
* Ticket Types: https://datafeeds.nationalrail.co.uk/api/staticfeeds/4.0/ticket-types
 
The header of the HTTP response will also include the date when the xml file was last modified using this format: Last-Modified: DAY, DD MMM YYYY HH:MM:SS GMT
 
The following is an example of request/response with Ticket Restrictions Knowledgebase Feed via NRDP:
 
: Example HTTP GET Request to NRDP knowledgebase feed:
 
<code><pre>GET https://datafeeds.nationalrail.co.uk/api/staticfeeds/4.0/ticket-restrictions HTTP/1.1
 
Content-Type: application/json
 
Accept: */*
 
X-Auth-Token: NRDP_email_address:1491312310772:56c56baa3e56d35ff0ede4a6aad1bcfb
 
//Enter your NRDP email address and the Token Key used in step 1 above</pre></code>
 
: Corresponding example HTTP 200 Response Header:
 
<code><pre>Cache-Control: no-cache, no-store, max-age=0, must-revalidate
 
Content-Length: 1194601
 
Content-Type: text/plain;charset=ISO-8859-1
 
Date: Wed, 05 Apr 2017 08:29:16 GMT
 
Expires: 0
 
Last-Modified: Wed, 05 Apr 2017 08:16:39 GMT
 
Pragma: no-cache
 
Server: Apache-Coyote/1.1
 
X-Content-Type-Options: nosniff
 
X-Frame-Options: DENY
 
X-Xss-Protection: 1; mode=block
 
</pre></code>
 
: Corresponding XML Response file
 
<code><pre> <?xml version="1.0" encoding="utf-8"?>
 
<TicketRestrictions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:com="http://nationalrail.co.uk/xml/common" xsi:schemaLocation="http://internal.nationalrail.co.uk/xml/XsdSchemas/External/Version4.0/nre-ticket-restriction-v4-0.xsd" xmlns="http://nationalrail.co.uk/xml/ticketrestriction">
 
  <TicketRestriction>
 
    <Name><![CDATA[S2]]></Name>    <LinkToDetailPage><![CDATA[http://int.web.kb.awsnre.co.uk/times_fares/ticket_types/145184.aspx]]></LinkToDetailPage>
 
    <RestrictionCode>S2</RestrictionCode>
 
    <TicketRestrictionIdentifier>52CD8939787B42789817C8E83A38F74E</TicketRestrictionIdentifier>
 
    <ApplicableDays><![CDATA[<p>TEST SM 19/01</p>]]></ApplicableDays>
 
    <OutwardDirection>Outward Travel</OutwardDirection>
 
    <ReturnDirection>Return Travel</ReturnDirection>
 
    <RestrictionsType>2</RestrictionsType>
 
    <Restrictions>
 
      <Restriction>
 
        <DetailsOutward><![CDATA[<p>SM 2 </p>]]></DetailsOutward>
 
        <DetailsReturn><![CDATA[<p>SM TEST 2 </p>]]></DetailsReturn>
 
      </Restriction>
 
    </Restrictions>
 
  </TicketRestriction>
 
</pre</code>
 
 
== Real Time Incident Feed ==
 
== 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 as follows:
 +
 +
Using your preferred client, connect to the Message topic host using the credentials and topic name shown on
 +
My Feeds/ Knowledgebase Real Time Incidents Information.
 +
 +
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 ActiveMQ, you will start receiving each real time incident message, with its respective
 +
incident number and other message information.
 +
 +
=== 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 ====
 +
<pre>
 +
<?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>
 +
...
 +
</pre>
 +
 +
==== Modified Incident Message ====
 +
 +
<pre>
 +
<?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>
 +
...
 +
</pre>
 +
==== Removed Incident Message ====
 +
Removed messages contain empty bodies.
 +
<pre></pre>
 +
 +
= Support =
 +
KnowledgeBase XML schemas:
 +
* [[Media:nre-incident-v5-0.xsd.gz|Incidents v5]]
 +
* [[Media:nre-promotion-v4-0.xsd.gz|Promotions v4]]
 +
* [[Media:nre-service-indicator-v4-0.xsd.gz|National Service Indicator (NSI) v4]]
 +
* [[Media:nre-station-v4-0.xsd.gz|Stations v4]]
 +
* [[Media:nre-ticket-restriction-v4-0.xsd.gz|Ticket Restrictions v4]]
 +
* [[Media:nre-ticket-v4-0.xsd.gz|Ticket Types v4]]
 +
* [[Media:nre-toc-v4-0.xsd.gz|TOCs v4]]
 +
 +
Supporting/referenced schemas:
 +
* [[Media:nre-common-v4-0.xsd.gz|Common v4]]
 +
* [[Media:nre-common-v5-0.xsd.gz|Common v5]]
 +
* [[Media:AddressTypes-v2-0.xsd.gz|Address Types v2]]
 +
* [[Media:bs7666-v2-0.xsd.gz|BS7666 v2]]
 +
 +
KnowledgeBase specification:
 +
* [[Media:RSPS5050 KnowledgeBase Data Feeds 01-00.pdf.gz|RSPS5050 v01-00]]

Latest revision as of 10:23, 21 February 2019

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 (KB), Real Time incidents – for new, modified and deleted Incidents

Knowledgebase (KB), 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 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.

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

Step 1: Generate Authentication Token

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)

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

   Content-Type: application/x-www-form-urlencoded
   username=jane@doe.com&password=password

Request (JSON Body)

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

   {
     "username": "jane@doe.com",
     "password": "password"
   }

Response (Ok)

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

The generated token is valid for 1 hour.

Response (Error)

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.

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

Step 2: Perform a HTTP GET call for each Knowledgebase 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:

Request

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

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

Using the returned authentication token as an X-Auth-Token header.

Response (Ok)

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

Response (Unauthenticated)

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

Response (Not Subscribed to Knowledgebase API)

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

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 as follows:

Using your preferred client, connect to the Message topic host using the credentials and topic name shown on My Feeds/ Knowledgebase Real Time Incidents Information.

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 ActiveMQ, you will start receiving each real time incident message, with its respective incident number and other message information.

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: