NRE Developer Guidelines v.02-02
- 1. NRE Developer Guidelines_v 2.2 Version 01-00 (2014-05-21) Version History Version Date Author Comment 01-00 2014-05-29 Lindsay Bleakley First Complete Draft 02-02 2014-05-30 Lindsay Bleakley Second Complete Draft Copyright The copyright in this work is vested in Train Information Information Limited (TISL) and the information contained herein is confidential. This work (either in whole or in part) must not be modified, reproduced, disclosed or disseminated to others or used for purposes other than that for which it is supplied, without the prior written permission of TISL. If this work or any part hereof is furnished to a third party by virtue of a contract with that party, use of this work by such party shall be governed by the express contractual terms between TISL which is a party to that contract and the said party. © 2014 Developer Guidelines Document Ref:
- 2. Contents 1 Introduction.................................................................................................................3 1.1 This Document.......................................................................................................................3 1.2 Overview................................................................................................................................3 2 Accessing the Information............................................................................................3 2.1 Changes to the Access Process..............................................................................................3 3 Requirements of Use....................................................................................................4 3.1 Branding.................................................................................................................................4 3.2 Real Time Information...........................................................................................................4 3.3 Advertising in the Data..........................................................................................................4 3.4 Efficient Use of the Information............................................................................................4 4 Recommendations of Use.............................................................................................5 4.1 Good Practice ........................................................................................................................5 5 Clarification of OGL Terms............................................................................................5 5.1 Requirements ........................................................................................................................5 5.2 Exemptions............................................................................................................................6 6 Technical Specification Guides......................................................................................7
- 3. 1 Introduction 1.1 This Document This document provides guidance on the use and display of information which National Rail Enquiries (“NRE”) provide to developers through various Information (“Information”). This document also seeks to clarify some terms and conditions within the adapted Open Government Licence (“OGL”) used by NRE for certain feeds. Reference is also made to those other documents which you will need to review in order to correctly harness the Information. 1.2 Overview NRE have taken the decision to make Information more openly available for developers to use and innovate with. Our decision to release the data is intended to support the industry requirement to provide widely available, high quality, accurate, timely and consistent information to the travelling public across as many potential customer touch points as possible. Our aspiration is to maximise the benefit of partnerships to increase the reach of our Information and ultimately the availability of quality information about travelling by train. We will always use reasonable endeavours to provide high quality information to our existing and prospective developer partners. 2 Accessing the Information As of the 1st of June 2014 NRE’s real time train running Information is available under the terms and conditions of the adapted OGL. The process for gaining access to the Information is manual, whereby you request the Information by e-mailing nrelicensing@org.uk. There is no approval process so everyone who applies will be given access. 2.1 Changes to the Access Process Our intention is to make the process of accessing the Information as quick and easy as possible. Technical changes are being made to our systems which will automate the registration process and give immediate access to the Information. Pending the avoidance of unexpected technical difficulties, we aim to have the automated signup process in place for each relevant feed by the following dates: Darwin Webservice (Public & Staff Version): End of October 2014 Darwin Timetable Feed: End of April 2015 Darwin Push Port: End of April 2015 All of our other feeds, including those derived from the Knowledgebase and the Online Journey Planner, are still available under NRE Licence. No charges apply to any of NRE’s Knowledgebase feeds. Charges apply to the Online Journey Planner feeds because we are charged by our supplier; this is at a cost recovery rate only. In the future, access to Knowledgebase will also be given under the terms of an OGL based licence; there are no timescales for this currently.
- 4. 3 Requirements of Use When using NRE Information in the public domain there are a number of requirements to consider. Requirements are those practices which you MUST adhere to. 3.1 Branding The user of NRE Information must acknowledge NRE as the source by displaying the “Powered by National Rail Enquiries” logo. The branding should be displayed directly alongside, above or underneath the Information that is being displayed. Use of the logo must be in accordance with the National Rail Enquiries Brand Guidelines which are available on this website or by contacting NRElicensing@atoc.org. 3.2 Real Time Information The Darwin Push Port and the Darwin Webservice (Staff Version) contain information that must be interpreted and used in a regulated way for specific reasons, including: 3.2.1 Platform Numbers: Users must implement platform number suppression as directed in the feeds. Early display of platform numbers, particularly at origin and destination stations, can lead to platform overcrowding and/or staff not having sufficient time to prepare the train for oncoming passengers. Adhering to this requirement is an important condition of use. Please note; this is not an exhaustive list. Further requirements relating to the use of real-time information from Darwin Push Port and the Staff Version of Darwin Webservice will be added to this document by 10th of Jun-14. 3.3 Advertising in the Data You must ensure that advertising is not embedded in the data so as not to confuse, corrupt or detract from the accuracy or trustworthiness of the data in any way. This is a requirement that we also consider to be a fundamental element of good practice. For the avoidance of doubt, the clause does not restrict you from advertising alongside NRE Information. You are free to display advertising as you wish so long as it isn’t embedded in the information that derives from the NRE feed. 3.4 Efficient Use of the Information You must implement reasonable technical measures to make the most efficient use of the Information. Wherever possible you should apply technical or practical logic to limit the number of request made to a feed where a request is not necessary. By making the most efficient use possible, you can reduce the likelihood that you will exceed the “High Volume Usage” threshold. For more information on usage thresholds and associated usage based charging, please see the Usage Charging Document. The following example demonstrates how efficient use of a feed can be achieved in some circumstances.
- 5. Example – Screens showing Live Departure Boards: In a hypothetical case, a user displays live departures information for a single station across 25 screens. The screens derive their information from the Darwin Webservice using the same access token. The Darwin Webservice receives and automated enquiry to update each individual screen every 2 minutes. Each screen operates for 16 hours a day. The resulting usage figures follow: 25 screens x 30 requests per hour (r/h) = 750 r/h 750 r/h x 16 hours per day (h/d) = 12,000 r/d 12,000 r/d x 28 days per period (d/p) = 336,000 r/p Total Requests Per Period = 336,000 In this instance, the user could apply technical logic to enable a single local server to call the Darwin Webservice once every 2 minutes which could, in turn, feed all the screens. This would reduce usage by x25 to just 13,440 requests per period. We highly encourage you to use technical measures to achieve this sort of effect. 4 Recommendations of Use When using NRE Information in the public domain there are a number of recommendations you should consider; these recommendations are examples of good practice that we encourage you to adopt in order to support the industry to achieve consistency. 4.1 Good Practice Examples and recommendations of good practice can be found in the “Good Practice Guide for Customer Information”. The document is an industry manuscript, complied by the TOCs, about recommended good practice in the display of information to customers about rail travel. It has been informed by six years of customer research, is updated annually and can be found at the following URL http://www.nationalrail.co.uk/static/documents/GPG_v3.0_-_Final.pdf. 5 Clarification of OGL Terms For the avoidance of doubt, this section seeks to clarify some of the terms used within the adapted OGL used by NRE to licence our real time train running information feeds (“the OGL”). 5.1 Requirements 5.1.1 Where the OGL states: “You must ensure that Your use of the Information is accurate and is not misleading”, NRE mean that the Information must not be altered in any way so as to make it inaccurate. You must not display the information in a way that is misleading. For the avoidance of doubt,
- 6. amendments and modifications to the format and display of the information are not prohibited in any way. 5.1.2 Where the OGL states: “You must ensure that Your use of the Information does not defraud or is not used to defraud the rail industry” NRE mean that the Information must not be used for a purpose which could be considered fraudulent in accordance with the laws of England and Wales. If you create a service or product using the Information that ‘could’ make it possible for you or one of your customers to make fraudulent claims against the industry, then you are responsible and you must demonstrate appropriate preventative measures. If you are unable to do so, you risk your access to the Information being cut off. Termination of the information feeds is the limit of your liability. 5.1.3 Where the OGL states: “You must ensure the information You provide on registration is accurate and that You only use the Information for the purpose you indicate” NRE mean that your personal details and the details of your intended use of NRE Information must be accurate. This is for many reasons, including but not limited to: so that we can measure and understand the reach or our Information; to enable us to report on the use of our Information and thus inform our partnership strategy; so we can contact you should there be a problem with the Information or your use of the Information; so we can contact you if you reach the High Volume Usage threshold; and so we are able to ensure the correct display of our logo and branding. You will not be asked to disclose any specific details which you may deem to be your intellectual property. Most information that you will be asked for will be from a drop down selection menu. Free text fields that you will be asked to complete will primarily be for specific user names, domain names, e-mail addresses, app names, and telephone numbers. But don’t worry; your right to access the Information will not be subject to approval based on your stated proposed usage. 5.2 Exemptions 5.2.1 Where the OGL states: “This licence does not permit You to sublicense the use of the Information” NRE mean that you are not permitted to distribute the Information to others under the terms that we distribute the Information to you. Should you pass your access token or credentials on to others, all the resulting usage will be accumulated against your username. You would therefore be liable to pay all charges if the High Volume Usage threshold was exceeded. It is also important to NRE that we know each individual user accessing our information. This is for many reasons, including: if you have unique access credentials we can easily identify faults or problems related to your credentials; if multiple users were permitted access though one set of credentials, a fault could bring down all the products and services of the people using those credentials; and it better enables us to maintain a healthy system for the benefit of all the users; In addition, the following reasons apply again: we can measure and understand the reach or our Information; we can report on the use of our Information and thus inform our partnership strategy; we can contact you should there be a problem with the Information or your use of the
- 7. Information; we can contact you if you reach the High Volume Usage threshold; and we are able to ensure the correct display of our logo and branding. 6 Technical Specification Guides There are further developer guides for each individual feed which contain the technical specifications for developers to work against. All documents are available on request by contacting nrelicensing@atoc.org. Documentation can be requested for all the following feeds: Available under NRE Adapted OGL (version 2.0) Darwin Webservice (Public Version) Darwin Webservice (Staff Version) Darwin Push Port Darwin Timetable Changes Feed Available under NRE Licence Real Time Journey Planning Webservice – (charges apply) 3rd Party Alerting Webservice – (charges apply) Incidents XML National Information Indicator XML Stations XML TOCs XML Stations Made Easy XML Promotions XML Ticket Types XML