Skip to main content

hsp-client

PyPI Python CI Licence: GPL-3.0

A Python client for the Rail Delivery Group's Historic Service Performance (HSP) API, which records how late trains between two stations actually ran, from Darwin's historical data.

HSP is the industry's public record of past punctuality for individual trains in Great Britain. It has no bulk download; you query it live, and it answers with deeply nested JSON in which every number is a string and every time that does not apply is an empty string. This package sends the requests and turns the answers into tables.

from hsp_client import HspClient, parse_service_metrics

client = HspClient()  # reads NRDP_USERNAME and NRDP_PASSWORD

raw = client.service_metrics(
    "BTN",
    "VIC",
    from_time="0700",
    to_time="0800",
    from_date="2024-01-08",
    to_date="2024-01-12",
    days="WEEKDAY",
)
frame = parse_service_metrics(raw)

Install

Python 3.11 or later.

pip install hsp-client

or, from a clone, pip install .. It depends on pandas for the tables. HTTP goes through urllib from the standard library.

Credentials

You need a National Rail Data Portal account with HSP ticked under "Subscription type".

A missing tick is the usual reason requests fail. An NRDP account without it works for the other feeds and gets a 401 from HSP, so the client says what to check instead of just reporting the status code:

error: HSP rejected the credentials (HTTP 401). Check the username and password,
and confirm the account has 'HSP' ticked under Subscription type at
https://opendata.nationalrail.co.uk. An NRDP account without that subscription
works for the other feeds but not for HSP.

Set the credentials in the environment:

export NRDP_USERNAME="you@example.com"
export NRDP_PASSWORD="..."

The CLI has no --password flag and nothing here reads a password from a config file. A flag ends up in shell history and a config file tends to end up in git.

The two endpoints

metrics: punctuality between two stations

Every departure pattern between an origin and a destination over a date range, with the share of services that arrived within each tolerance.

hsp-client metrics BTN VIC \
  --from-time 0700 --to-time 0800 \
  --from-date 2024-01-08 --to-date 2024-01-12 \
  --days WEEKDAY --tolerance 5 10

The output has one row per departure pattern per tolerance:

origin_location destination_location gbtt_ptd gbtt_pta toc_code  matched_services  tolerance_value  num_tolerance  percent_tolerance
            BTN                  VIC     0722     0822       GX               9.0              5.0            8.0               88.0
            BTN                  VIC     0722     0822       GX               9.0             10.0            9.0              100.0

details: stop-by-stop times for one service

Take a RID from the rids column above to see what that train did:

hsp-client details 201601013091406
location gbtt_pta actual_ta  arrival_delay gbtt_ptd actual_td  departure_delay
     BTN                              <NA>     0722      0724                2
     HHE     0739      0741              2     0740      0742                2
     VIC     0822      0819             -3                                <NA>

HSP does not return arrival_delay and departure_delay; they are worked out here, in minutes late (negative if early), with <NA> where the time does not apply. An origin has no public arrival and a terminus no public departure, and HSP sends those as "". They are missing values, not midnight. A train due at 23:58 that arrives at 00:03 is five minutes late.

Add --csv out.csv to write a file, or --raw for the JSON as HSP sent it.

What HSP leaves out

HSP only includes a service if

  • its public departure and arrival times and its operator match the query exactly,
  • it is not marked as deleted, and
  • at a location it calls at, it has a recorded actual arrival time.

The full rules are under "Rules for Inclusion of Trains" on the Open Rail Data wiki. An empty result does not mean no train ran, and the CLI says so rather than printing nothing:

No services returned. HSP excludes trains whose public times or operator do not
match exactly, and those with no recorded actual arrival, so an empty result does
not prove that nothing ran.

Other limits:

  • HSP holds roughly the last year. Older dates return nothing.
  • days is WEEKDAY, SATURDAY or SUNDAY. There is no option for all days, so query the three and combine them.
  • Up to three tolerance values per request.
  • Times are HHMM strings and dates YYYY-MM-DD, both passed to HSP unchanged.

Python API

Name
HspClient(username=None, password=None, timeout=60) a connection; credentials default to the environment
.service_metrics(from_loc, to_loc, ...) the raw serviceMetrics JSON
.service_details(rid) the raw serviceDetails JSON
parse_service_metrics(raw) one row per pattern per tolerance
parse_service_details(raw) one row per calling point, with delays
parse_hhmm("0712") minutes since midnight, or None
delay_minutes(scheduled, actual) minutes late, allowing for midnight

Every error is a subclass of HspError: MissingCredentialsError, AuthenticationError, HspRequestError and InvalidRequestError. Bad arguments raise InvalidRequestError before anything is sent, so a typo in days costs no request.

Part of a set of Python packages for Great Britain's open rail data:

  • bplan-geography, minimum running times from Network Rail's BPLAN extract
  • cif-timetable, calling points and trains per route from the Network Rail CIF timetable
  • rail-loading, UK train operators' passenger loading data in one schema
  • rsp-fares-feed, every fare between two stations, from the National Rail fares feed
  • tag-databook, DfT TAG Data Book appraisal values without opening Excel
  • track-distance, station distances along the rails, from Network Rail's track model
  • rail-codes, TIPLOC, CRS, NLC and STANOX lookups from Network Rail's CORPUS
  • orr-station-usage, entries and exits at every station by year, from ORR tables 1410 and 1415

Development

git clone https://github.com/rosedillon/hsp-client
cd hsp-client
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check . && ruff format --check . && mypy src

The tests replace urlopen with a fake that records each request, so they cover request building, the authentication header and error handling with no network or credentials. The response fixtures follow the shapes documented on the Open Rail Data wiki, string-encoded numbers and empty-string times included.

Licence

GPL-3.0. See LICENSE.

Not affiliated with or endorsed by the Rail Delivery Group or National Rail.

Metadata

Release files for hsp-client 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hsp-client 0.1.1
File Size Uploaded Provenance Actions
hsp_client-0.1.1.tar.gz 30.4 kB With provenance Details for hsp_client-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hsp-client 0.1.1
File Interpreter ABI Platform Actions
hsp_client-0.1.1-py3-none-any.whl Python 3 none any Details for hsp_client-0.1.1-py3-none-any.whl

Total release size: 56.6 kB

Release files / hsp_client-0.1.1.tar.gz

Download URL hsp_client-0.1.1.tar.gz
Size 30.4 kB
Tags Source
SHA-256 checksum
How to use checksums
6da0ec52e09c67dc60a021afd3aaad8f1b2696c1fa4457f6b8238f165792c17a
BLAKE2b-256 checksum
How to use checksums
6ff13a7369c1528b4d924e6ff239635f1a39baaf422a1a6832d23bd7d45f6268
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / hsp_client-0.1.1-py3-none-any.whl

Download URL hsp_client-0.1.1-py3-none-any.whl
Size 26.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
26f2fd51ba6cbdc28ef0d231535bd5ce35d5c56b9b6d9edf7d76179506fa90f9
BLAKE2b-256 checksum
How to use checksums
6e5868e2b8bd6d403668053510fee0ef6d879482292ce0a802994d990c9b8f3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for hsp-client 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hsp_client-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page