HSP: Difference between revisions

Revision as of 11:47, 22 July 2016

About

Historical Service Performance (HSP) is a platform containing historical data from Darwin, with an API to allow easy querying of service performance data.

You can query for all trains between a pair of locations, between two times and on two dates and filter the results by train operator.

Accessing the API

To access the HSP API, you must have an account on the National Rail Data Portal at https://datafeeds.nationalrail.co.uk/. If you already consume real-time data from Darwin, you will already have an account.

After logging in and/or signing up, ensure the 'HSP' box is checked under 'Subscription type'.

Using the API

There are two API calls available - 'serviceMetrics' and 'serviceDetails', and documentation is available at https://hsp-prod.rockshore.net/.

For each API call, you must set the HTTP Content-type header to 'text/json', and provide an HTTP Authorization header with the username and password for the National Rail Data Portal.

Service Metrics

The serviceMetrics call is used to request a summary of service performance for a particular journey. It requires an HTTP POST call with a JSON hash containing the following keys:

from_loc and to_loc are valid three-letter codes (CRS codes) for the origin and destination locations on a journey
from_time and to_time are the times of the day you wish to query and must be in the format HHMM, e.g. 0700
from_date and to_date are the historical dates on which you wish to query and must be in the format YYYY-MM-DD
days must be either WEEKDAY, SATURDAY or SUNDAY, and will limit the query to trains which run Monday to Friday, or on Saturday, or on Sunday
toc_filter (optional) must be a list of TOC Codes
tolerance (optional) is a set of up to three values to set the tolerances, e.g. ['2', '5', '10'] will return statistics for the number of trains which arrived at the to_loc within 2 minutes, within 5 minutes and within 10 minutes of their scheduled time

The response will be a JSON object containing:

A header with the from_loc and to_loc of the query
A Services containing a serviceAttributesMetrics with the origin_location and destination_location of the train, the gbtt_pta and gbtt_ptd (public arrival and departure times), the toc_code of the operator of the service, and a matched_services containing a list of rids of all trains. These RIDs can be used in the serviceDetails call to get further information.
A Services containing a Metrics, with the tolerance_value selected, a num_not_tolerance (number of trains outside this tolerance), a num_tolerance (number of trains within this tolerance), and a percent_tolerance and global_tolerance

Service Details

The serviceDetails call is used to request details of a particular train by using its RID - a unique identifier for a train on a day, used in Darwin. It requires an HTTP POST call with a JSON hash containing a rid with the RID of the service in question.

The response will be a JSON object containing:

A serviceAttributesDetails containing the date_of_service, toc_code and rid of the train, along with a list of locations containing the location code, gbtt_pta and gbtt_ptd',, the actual_ta and actual_td (actual time of arrival and departure), and if the train was delayed or cancelled, a late_canc_reason with the reason for the delay or cancellation

Help!

For help in using the API, please post to the openraildata-talk mailing list, where other users of the service can help you.

@@ Line 1: / Line 1: @@
 == About ==
-Historical Service Performance (HSP) is a platform containing historical Darwin data and can be used to provide metrics on the performance of services through the HSP API.
+Historical Service Performance (HSP) is a platform containing historical data from Darwin, with an API to allow easy querying of service performance data.
-== How can I access the platform? ==
+You can query for all trains between a pair of locations, between two times and on two dates and filter the results by train operator.
-To access the HSP API, you must register for an account at http://datafeeds.nationalrail.co.uk, selecting HSP as the Subscription type. Once you have submitted the registration form, you should receive a confirmation email. Follow the instructions in the email and set your new password.
+== Accessing the API ==
-== HSP APIs ==
+To access the HSP API, you must have an account on the National Rail Data Portal at https://datafeeds.nationalrail.co.uk/.  If you already consume real-time data from Darwin, you will already have an account.
-There are 2 API methods available; serviceMetrics and serviceDetails.
+After logging in and/or signing up, ensure the 'HSP' box is checked under 'Subscription type'.
+== Using the API ==
+There are two API calls available - 'serviceMetrics' and 'serviceDetails', and documentation is available at https://hsp-prod.rockshore.net/.
+For each API call, you must set the HTTP Content-type header to 'text/json', and provide an HTTP Authorization header with the username and password for the National Rail Data Portal.
 === Service Metrics ===
-The serviceMetrics method is used to request and receive service performance information for a particular journey.
+The serviceMetrics call is used to request a summary of service performance for a particular journey.  It requires an HTTP POST call with a JSON hash containing the following keys:
-* The from_loc and to_loc fields in the request must be valid CRS codes
-* The from_time and to_time fields in the request must be in HHMM format
+* ''from_loc'' and ''to_loc'' are valid three-letter codes (CRS codes) for the origin and destination locations on a journey
-* The from_date and to_date fields in the request must be in YYYY-MM-DD format
+* ''from_time'' and ''to_time'' are the times of the day you wish to query and must be in the format HHMM, e.g. 0700
-* The days type in the request must be WEEKDAY, SATURDAY or SUNDAY
+* ''from_date'' and ''to_date'' are the historical dates on which you wish to query and must be in the format YYYY-MM-DD
-* Service Metric results can be filtered to only return metrics for specific Train Operating Companies by using the 2-character TOC code as the toc_filter in the request
+* ''days'' must be either WEEKDAY, SATURDAY or SUNDAY, and will limit the query to trains which run Monday to Friday, or on Saturday, or on Sunday
-* Each request will generate a response providing metrics based on a service’s performance compared to a global tolerance value
+* ''toc_filter'' (optional) must be a list of [[TOC Codes]]
-* Up to 3 additional tolerance values can be submitted in each request to find out how the services are performing according to those tolerances
+* ''tolerance'' (optional) is a set of up to three values to set the tolerances, e.g. ['2', '5', '10'] will return statistics for the number of trains which arrived at the ''to_loc'' within 2 minutes, within 5 minutes and within 10 minutes of their scheduled time
+The response will be a JSON object containing:
+* A ''header'' with the ''from_loc'' and ''to_loc'' of the query
+* A ''Services'' containing a ''serviceAttributesMetrics'' with the ''origin_location'' and ''destination_location'' of the train, the ''gbtt_pta'' and ''gbtt_ptd'' (public arrival and departure times), the ''toc_code'' of the operator of the service, and a ''matched_services'' containing a list of ''rids'' of all trains.  These RIDs can be used in the ''serviceDetails'' call to get further information.
+* A ''Services'' containing a ''Metrics'', with the ''tolerance_value'' selected, a ''num_not_tolerance'' (number of trains outside this tolerance), a ''num_tolerance'' (number of trains within this tolerance), and a ''percent_tolerance'' and ''global_tolerance''
 === Service Details ===
-The serviceDetails method is used to provide details of a particular service (RID).
+The serviceDetails call is used to request details of a particular train by using its RID - a unique identifier for a train on a day, used in Darwin.  It requires an HTTP POST call with a JSON hash containing a ''rid'' with the RID of the service in question.
+The response will be a JSON object containing:
+* A ''serviceAttributesDetails'' containing the ''date_of_service'', ''toc_code'' and ''rid'' of the train, along with a list of ''locations'' containing the ''location'' code, ''gbtt_pta'' and ''gbtt_ptd',, the ''actual_ta'' and ''actual_td'' (actual time of arrival and departure), and if the train was delayed or cancelled, a ''late_canc_reason'' with the reason for the delay or cancellation
+== Help! ==
-== API User Guide ==
+For help in using the API, please post to the [https://groups.google.com/forum/#!forum/openraildata-talk openraildata-talk] mailing list, where other users of the service can help you.
-The API user guide contains full details of each request and response and can be found at https://hsp-prod.rockshore.net/docs/hspapi/index.html