Difference between revisions of "HSP"
Jump to navigation
Jump to search
PeterHicks (talk | contribs) (Tidy up HSP API documentation) |
|||
| Line 1: | Line 1: | ||
== About == | == About == | ||
| − | Historical Service Performance (HSP) is a platform containing historical Darwin | + | 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. | |
| − | There are | + | 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 === | === Service Metrics === | ||
| − | The serviceMetrics | + | 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 === | === Service Details === | ||
| − | The serviceDetails | + | 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 [https://groups.google.com/forum/#!forum/openraildata-talk openraildata-talk] mailing list, where other users of the service can help you. | |
| − | |||
Revision as of 11:47, 22 July 2016
Contents
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.
