Difference between revisions of "KnowledgeBase"
Jump to navigation
Jump to search
EvelynSnow (talk | contribs) (Reword internal KB URLs section (internal. isn't the only source of them)) |
|||
| (13 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
= About = | = About = | ||
| − | |||
| − | |||
| − | |||
| − | Knowledgebase | + | 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: | |
| − | Knowledgebase | + | * 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 | + | 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 | + | 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 | ||
| − | |||
| − | '''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. | + | |
| + | = Internal KB URLs = | ||
| + | Some endpoints are currently accessible without authentication on subdomains reserved for internal use only. Internal KB was originally firewalled, this was removed in March of 2020, but it may return to being firewalled without warning. If a URL you're using starts with anything other than ''opendata.nationalrail.co.uk'', you're probably in the wrong place! | ||
= 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 two steps via a REST client. | |
| − | + | === Generate Authentication Token === | |
| − | + | See the [[National Rail Data Portal#Authentication|Authentication]] section on the [[National Rail Data Portal|National Rail Data Portal]] article | |
| − | ==== | + | ==== 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 | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | 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 | ||
| − | + | A successful response will result in the requested file: | |
| − | |||
| − | |||
<?xml version="1.0" encoding="utf-8"?> | <?xml version="1.0" encoding="utf-8"?> | ||
| Line 106: | Line 51: | ||
... | ... | ||
| − | + | If authorization failed, the response will be an HTTP 401 Unauthorized: | |
{ | { | ||
| Line 116: | Line 61: | ||
} | } | ||
| − | + | If you are not subscribed to the Knowledgebase API, the response will be an HTTP 403 Forbidden: | |
{ | { | ||
| Line 126: | Line 71: | ||
} | } | ||
| − | == | + | === 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 == | |
| − | + | The real-time incidents feed details the creation, modification, and deletion of Knowledgebase incidents in real-time. The underlying information is the same as is available through the HTTP API (which can be used as a snapshot, if necessary), but its real-time nature is useful for tracking state changes more reliably, efficiently, and quickly. Messages from the real-time incidents feed can be received using either STOMP or Openwire. After selecting the Knowledgebase real-time incidents checkbox on the ''edit account'' page, connection information (host, credentials, and topic name) will now be shown in the relevant section on your ''My Feeds'' page. | |
| − | + | Please note: | |
| − | + | * If using STOMP, your client must support STOMP v1.2. | |
| + | * Knowledgebase message bodies are not compressed, unlike the Darwin push port. | ||
| + | * The opening XML tag is malformed, and should be ''PtIncident'' instead of ''uk.co.nationalrail.xml.incident.PtIncidentStructure''. Simple string substitution can resolve this if it presents a problem using the schema. This issue does ''not'' affect the incidents file retrievable over HTTP. | ||
| + | * Topic advisory messages are disabled on the KB Real Time Incidents messaging host, so you must also connect with this facility disabled if using Openwire (e.g. by setting watchTopicAdvisories=false if using NMS) | ||
| + | * The feed is relatively low volume with typically only a few messages per hour and often gaps of several hours overnight; if monitoring message volumes, or testing, you should take this into account. | ||
=== Headers === | === Headers === | ||
| − | + | Each frame from the real-time incidents feed contains the following headers: | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | * ''INCIDENT_MESSAGE_STATUS'': either ''NEW'' (a new incident message), ''MODIFIED'' (a change to existing incident information), or ''REMOVED'' (incident deletion) | |
| − | + | * ''KNOWLEDGEBASE_DATA_TYPE'', set to ''INCIDENT_MESSAGE''. | |
| + | * ''INCIDENT_ID'': the ID of the KB incident | ||
=== Example Real Time Incidents Bodies === | === Example Real Time Incidents Bodies === | ||
| − | The following are examples of | + | The following are examples of real-time incidents messages which include ''new'', ''modified'' and ''deleted'' incidents. |
| − | |||
==== New Incident message ==== | ==== New Incident message ==== | ||
| Line 237: | Line 170: | ||
= Support = | = Support = | ||
| − | KnowledgeBase | + | KnowledgeBase documentation and schemas: |
| − | * [ | + | * [https://www.rspaccreditation.org/publicDocumentation.php#RSPS5xxx RSPS5050] |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | {{Navtable-NreDataFeeds}} | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | [[Category:National Rail Enquiries Data Feeds]] | |
| − | |||
Latest revision as of 16:25, 24 December 2023
Contents
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.
Internal KB URLs
Some endpoints are currently accessible without authentication on subdomains reserved for internal use only. Internal KB was originally firewalled, this was removed in March of 2020, but it may return to being firewalled without warning. If a URL you're using starts with anything other than opendata.nationalrail.co.uk, you're probably in the wrong place!
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
See the Authentication section on the National Rail Data Portal article
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
The real-time incidents feed details the creation, modification, and deletion of Knowledgebase incidents in real-time. The underlying information is the same as is available through the HTTP API (which can be used as a snapshot, if necessary), but its real-time nature is useful for tracking state changes more reliably, efficiently, and quickly. Messages from the real-time incidents feed can be received using either STOMP or Openwire. After selecting the Knowledgebase real-time incidents checkbox on the edit account page, connection information (host, credentials, and topic name) will now be shown in the relevant section on your My Feeds page.
Please note:
- If using STOMP, your client must support STOMP v1.2.
- Knowledgebase message bodies are not compressed, unlike the Darwin push port.
- The opening XML tag is malformed, and should be PtIncident instead of uk.co.nationalrail.xml.incident.PtIncidentStructure. Simple string substitution can resolve this if it presents a problem using the schema. This issue does not affect the incidents file retrievable over HTTP.
- Topic advisory messages are disabled on the KB Real Time Incidents messaging host, so you must also connect with this facility disabled if using Openwire (e.g. by setting watchTopicAdvisories=false if using NMS)
- The feed is relatively low volume with typically only a few messages per hour and often gaps of several hours overnight; if monitoring message volumes, or testing, you should take this into account.
Headers
Each frame from the real-time incidents feed contains the following headers:
- INCIDENT_MESSAGE_STATUS: either NEW (a new incident message), MODIFIED (a change to existing incident information), or REMOVED (incident deletion)
- KNOWLEDGEBASE_DATA_TYPE, set to INCIDENT_MESSAGE.
- INCIDENT_ID: the ID of the KB incident
Example Real Time Incidents Bodies
The following are examples of real-time incidents messages which include new, modified and deleted incidents.
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 documentation and schemas:
| National Rail Enquiries Data Feeds | |
|---|---|
| Data Feeds | About the Feeds • Darwin Webservice (Public) • Darwin Webservice (Staff) • Historical Service Performance • Push Port • KnowledgeBase • DTD • Locations (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 |
