Skip to main content

bplan-geography

PyPI Python CI Licence: GPL-3.0

Parse Network Rail's BPLAN Geography extract, the physical rail network as the train planning system sees it, and ask how quickly a train could get between two points.

Network Rail uses BPLAN to check that a timetable is physically possible. The extract is a 90 MB tab-delimited text file with a dozen record types mixed together, no header row, no schema, and running times written as +04'00. This package turns it into CSVs and a routable graph of minimum running times.

from pathlib import Path
from bplan_geography import clean_extract, BplanTimingGraph

clean_extract(Path("PIF20260710570710068.txt"), Path("bplan"))
# {'LOC': 12012, 'NWK': 42426, 'TLK': 1166850, 'TLD': 607}

graph = BplanTimingGraph(Path("bplan"))
graph.minimum_running_time("LEEDS", "YORK", "185")
# 20.0 (minutes for a Class 185, stop to stop)

Install

Python 3.11 or later.

pip install bplan-geography

or, from a clone, pip install .. It depends on pandas and networkx.

Getting BPLAN

BPLAN Geography is on the Rail Data Marketplace, which holds extracts back to 2022. Registration is free and the dataset is called "BPLAN Geography". The file you download has a name like PIF20260710570710068.txt.

The Open Rail Data wiki describes the format.

Clean once, then query

Cleaning a full extract takes a few seconds:

$ bplan-geography clean PIF20260710570710068.txt -o bplan
NR extract, valid 2026-05-17 to 2026-12-12
LOC     12,012  -> bplan_locations.csv
NWK     42,426  -> bplan_network_links.csv
TLK  1,166,850  -> bplan_timing_links.csv
TLD        607  -> bplan_traction_loads.csv

The first line is the extract's validity window, read from its header. Check it matches the period you are studying.

Then ask how fast a train could get between two places, by TIPLOC:

$ bplan-geography time LEEDS YORK -d bplan -t 185
LEEDS -> YORK (traction 185): 20.0 min

$ bplan-geography time MNCRPIC LEEDS -d bplan -t 185
MNCRPIC -> LEEDS (traction 185): 44.0 min

These are minimum times: what the network allows, with no pathing, performance or dwell allowances. They come out a little under real timetabled journeys. Leeds to York is timetabled at around 23 to 25 minutes against the 20 above.

Or ask about the physical link between two adjacent points:

$ bplan-geography lines LEEDS YORK -d bplan
LEEDS -> YORK
  distinct running lines  1
  link distance           37,013 m

Add --json to any subcommand for machine-readable output, and -v to log progress.

When the traction code is not timed

BPLAN times each link for each traction and timing load code. A link often has no timing for the code you ask about, and the answer then uses the fastest traction recorded there, which makes it optimistic. The CLI says how much of the answer that affects:

$ bplan-geography time LEEDS SHEFFLD -d bplan -t 195
  note: only 89% of that is timed for traction 195; the rest falls back to the fastest recorded traction, so the figure is optimistic.
LEEDS -> SHEFFLD (traction 195): 37.5 min

In Python the same share comes from running_time_detail:

minutes, exact_share = graph.running_time_detail("LEEDS", "SHEFFLD", "195")
# (37.5, 0.89)

An exact_share of 1.0 means every link on the route was timed for that traction. The traction codes are BPLAN's own, listed in bplan_traction_loads.csv; they are not always class numbers.

How running times are worked out

Two stations a train calls at are usually not adjacent in BPLAN. The train runs through intermediate timing points between them, so running times are summed along a shortest path rather than looked up.

A calling train has to accelerate away from a stand and brake to one, and BPLAN times those separately from passing at line speed (an entry or exit speed of 0 against -1). The route is found using passing times. Its first link then takes the start-from-stand timing, its last link the stop timing, and a single-link journey takes the combined one.

Where several records exist for the same link and traction (different running lines, or superseded variants), the fastest is kept. The graph answers what is achievable: if any recorded variant is faster than a proposed timing, the data alone cannot show that timing to be infeasible.

Bus, ship, London Underground and Tyne and Wear Metro timings are left out of the graph, because they are not trains on Network Rail track. BPLAN has a bus timed from Brighton to North Wembley, and with it in the graph a train from Brighton to Victoria came out at 35 minutes. The excluded codes are in bplan_geography.timing.NON_RAIL_TRACTION, plus anything starting BUS.

What it reads

Record Holds Written to
LOC the TIPLOC register: name, OSGB easting and northing, STANOX bplan_locations.csv
NWK links between adjacent TIPLOCs: running line, direction, distance, route availability bplan_network_links.csv
TLK minimum sectional running times by traction and running line bplan_timing_links.csv
TLD traction and timing load definitions: maximum speed, description, category bplan_traction_loads.csv

PLT (platforms), REF (reference codes) and the other record types make up most of the file. A prefix test skips them before any field is split, which is why a 90 MB extract cleans in seconds.

The field layout

The column positions were worked out from real extracts, not taken from an interface specification. They have been cross-checked:

  • the LOC eastings and northings for London Euston (529500, 182700) and Kings Cross (530200, 183200) match published OSGB grid references, and
  • NWK and TLK values around Leeds and on the slow Aberdare branch give believable distances and speeds.

No specification has confirmed them, though. Records with too few fields are skipped, counted and logged as a warning, so a change in layout shows up instead of producing wrong columns.

Limitations

  • BplanNetworkLinks.running_line_count() is as close as BPLAN gets to saying a segment is multi-track. It is not a count of tracks or of platforms (platforms are in PLT, which is not parsed), and the running line labels have not been checked against a specification. It is useful context for someone looking at a possible headway conflict, but not a reason to dismiss one automatically.
  • The timing graph is directed. A route one way does not mean there is one back.
  • Records are not filtered by date. The fastest variant is used whatever its validity window.

Python API

Name
clean_extract(source, output_dir) write the four CSVs and return row counts
BplanTimingGraph(cleaned_dir) the running time graph
.minimum_running_time(from, to, traction) minutes, or None with no route
.running_time_detail(from, to, traction) minutes and the exact traction share
.fastest_path(from, to, traction) the TIPLOCs on that route, or None
BplanNetworkLinks(cleaned_dir) running lines and distances between adjacent TIPLOCs
read_header(path) the extract's validity window
iter_records(path) stream (record_type, fields) for the kept types
parse_srt_minutes("+04'30") 4.5

Development

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

The tests build small synthetic extracts with the same field layout as the real thing (column positions, +MM'SS times, the entry and exit speed convention), so the index constants are under test too. No licensed data is committed.

Licence

GPL-3.0. See LICENSE.

Not affiliated with or endorsed by Network Rail.

Metadata

Release files for bplan-geography 0.2.0

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

Source distribution (sdist)

Source distribution for bplan-geography 0.2.0
File Size Uploaded Provenance Actions
bplan_geography-0.2.0.tar.gz 34.1 kB With provenance Details for bplan_geography-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bplan-geography 0.2.0
File Interpreter ABI Platform Actions
bplan_geography-0.2.0-py3-none-any.whl Python 3 none any Details for bplan_geography-0.2.0-py3-none-any.whl

Total release size: 64.0 kB

Release files / bplan_geography-0.2.0.tar.gz

Download URL bplan_geography-0.2.0.tar.gz
Size 34.1 kB
Tags Source
SHA-256 checksum
How to use checksums
4250dfd7286d93ae046be4af0cc848d32af0b62fb2df236413f250a268144148
BLAKE2b-256 checksum
How to use checksums
d61897609f8125a87973696a0e112023892b2b02e5d19c882de09a3b4426c6eb
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 / bplan_geography-0.2.0-py3-none-any.whl

Download URL bplan_geography-0.2.0-py3-none-any.whl
Size 29.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c938a27c39bb3107e0201c5f06696695ee9f8a8f6cf7f05098658a51971bc8b9
BLAKE2b-256 checksum
How to use checksums
ee1fb19a732afc064bfd8950d6cf5dc4b6191796740488f42c29e5a9400bf47b
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 bplan-geography 0.2.0

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 bplan_geography-0.2.0.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.2.0 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