Revision as of 14:16, 18 March 2019

The RDG Locations Proof of Concept (PoC) API brings together mutiple sources of locations data from various RDG and NR services into a single service. It allows consumers to search for codes associated to a location description or to request data asscoiated to a NLC, CRS, TIPLOC or STANOX code.

This is a Proof of Concept - it is intended to evaluate the potential usefulness of such an API and should not be incorporated into any services as it may be withdrawn, or unavailable, at any time

API

The Locations PoC API has two functions:

A search by location name/description function, to return codes associated to locations
A lookup by NLC, CRS, TIPLOC or STANOX function, to return data associated to the specified code

Access

The API is provided as a RESTFul JSON API and is available from the following endpoints. Both endpoints only accept a POST request with a simple JSON body:

Description search
- Endpoint: https://0hvzyzu9q6.execute-api.eu-west-1.amazonaws.com/beta/locs-desc
- JSON Body: e.g. {"id" : "leeds"}

Code search
- Endpoint: https://0hvzyzu9q6.execute-api.eu-west-1.amazonaws.com/beta/locs-js
- JSON Body: e.g. {"id" : "LDS", "type" : "C"}

Security

As this is a proof of concept a single access token has been created for use by the open community. This token needs to be included as a 'Auth-Token' header within the HTTPs request:

Auth-Token: ea8b2166-058c-4689-a72c-dd4b9b84cb82

Functions

Search by Location

https://0hvzyzu9q6.execute-api.eu-west-1.amazonaws.com/beta/locs-desc
e.g. {"id" : "leeds"}

The search by location function allows consumers to specify a string of 3 or more characters, which will be matched against the initial characters of each word within a location name. For example, if a user posts {"id" : "cross"} to the endpoint the following stations would be returned:

CrossHill
CrossKeys
Kirby Cross
London Kings Cross
etc.

The response will consist of a JSON array of objects, with each object containing the location name plus at least one of:

NLC
CRS
TIPLOC
STANOX

Note: The response is determined by location descriptions as set in multiple data sources. So the same location may appear more than once if it has been spelt differently in different feeds. For example, searching for {"id":"clapham junction"} will return:

[

{"description": "CLAPHAM JUNCTION LONDON", "nlc": "5595", "crs": "CLJ", "tiploc": "CLPHMJN", "stanox": "87219"},

{"description": "CLAPHAM JUNCTION", "nlc": "5595", "crs": "CLJ", "tiploc": "CLPHMJN", "stanox": "87219"}

]

whilst this is clearly the same location, as evidenced by the codes, it is shown twice because of the different descriptions.

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

@@ Line 1: / Line 1: @@
-The RDG Locations Proof of Concept (PoC) API brings together mutiple sources of locations data from various RDG and NR services into a single service. It allows consumers to search for codes associated to a location description or to request data asscoiated to an NLC, CRS, TIPLOC or STANOX code.
+The RDG Locations Proof of Concept (PoC) API brings together mutiple sources of locations data from various RDG and NR services into a single service. It allows consumers to search for codes associated to a location description or to request data asscoiated to a NLC, CRS, TIPLOC or STANOX code.
-This is a '''''Proof of Concept''''' - it is intended to evaluate the potential usefulness of such an API and should not be incorporated into any services as it may be withdrawn, or be unavailable, at any time
+This is a '''''Proof of Concept''''' - it is intended to evaluate the potential usefulness of such an API and should not be incorporated into any services as it may be withdrawn, or unavailable, at any time
 = API =
-The Locations PoC has two functions:
+The Locations PoC API has two functions:
-:* A search by location name/description, to return codes associated to locations
+:* A search by location name/description function, to return codes associated to locations
-:* A lookp by NLC, CRS, TIPLOC or STANOX to returned data associated to the specified code
+:* A lookup by NLC, CRS, TIPLOC or STANOX function, to return data associated to the specified code
 = Access =
-The API is REST JSON and is available from the following endpoints. Both endpoints only accept a POST request with a simple JSON body:
+The API is provided as a RESTFul JSON API and is available from the following endpoints. Both endpoints '''only''' accept a POST request with a simple JSON body:
 :* Description search
-:**  Endpoint: https://0hvzyzu9q6.execute-api.eu-west-1.amazonaws.com/beta/locs-desc
+:** Endpoint: https://0hvzyzu9q6.execute-api.eu-west-1.amazonaws.com/beta/locs-desc
 :** JSON Body: e.g. {"id" : "leeds"}
 :* Code search
-:**  Endpoint: https://0hvzyzu9q6.execute-api.eu-west-1.amazonaws.com/beta/locs-js
+:** Endpoint: https://0hvzyzu9q6.execute-api.eu-west-1.amazonaws.com/beta/locs-js
 :** JSON Body: e.g. {"id" : "LDS", "type" : "C"}
 = Security =
-As this is a proof of concept a single access token has been created for use by the open community. This token needs to be included as a header within the HTTPs request:
+As this is a proof of concept a single access token has been created for use by the open community. This token needs to be included as a 'Auth-Token' header within the HTTPs request:
 :* Auth-Token: ea8b2166-058c-4689-a72c-dd4b9b84cb82
@@ Line 28: / Line 28: @@
 e.g. {"id" : "leeds"}
-The search by location function allows consumers to specify a string of 3 or more characters, which will be matched against the ''initial'' characters of:
+The search by location function allows consumers to specify a string of 3 or more characters, which will be matched against the ''initial'' characters of each word within a location name. For example, if a user posts {"id" : "cross"} to the endpoint the following stations would be returned:
-:* A single word location name; and
-:* Each word of a multi-word location name
-For example, if a user posts {"id" : "cross"} to the endpoint the following stations would be returned:
 :* CrossHill
@@ Line 41: / Line 36: @@
 :* etc.
-Where the first two were matched by the initial 5 characters of their single word location name, whereas the latter two were matched against the initial 5 characters of the second and third words in the respective location names.
+The response will consist of a JSON array of objects, with each object containing the location name plus at least one of:
-The response with contain a JSON array of objects, with each object containing the location name plus at least one of:
 :* NLC
@@ Line 50: / Line 43: @@
 :* STANOX
-'''Note:''' The response is determined by unique location description as set in multiple data sources. So the same location may appear more than once if it has been spelt differently in different feeds. For example, searching for {"id":"clapham junction"} will return:
+'''Note:''' The response is determined by location descriptions as set in multiple data sources. So the same location may appear more than once if it has been spelt differently in different feeds. For example, searching for {"id":"clapham junction"} will return:
 :[
@@ Line 57: / Line 50: @@
 :]
-this is clearly the same location, as evidenced by the codes, but is shown twice because of the different descriptions.
+whilst this is clearly the same location, as evidenced by the codes, it is shown twice because of the different descriptions.
 {{Navtable-NreDataFeeds}}
 [[Category:National Rail Enquiries Data Feeds]]