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

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

  • cif-timetable, calling points and trains per route from the Network Rail CIF timetable
  • hsp-client, how late UK trains actually ran, from the National Rail HSP API
  • 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/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.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 bplan-geography 0.2.1
File Size Uploaded Provenance Actions
bplan_geography-0.2.1.tar.gz 35.2 kB With provenance Details for bplan_geography-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 65.6 kB

Release files / bplan_geography-0.2.1.tar.gz

Download URL bplan_geography-0.2.1.tar.gz
Size 35.2 kB
Tags Source
SHA-256 checksum
How to use checksums
5c06174228488822babd5b7b08e30a7c49726ddf3c28dacab755ba5f62b2f0e1
BLAKE2b-256 checksum
How to use checksums
7bb04ec707ee4cf4c26e0f3526b8e04a4f95625a5bbc8e8d4696b0d6c007a5de
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.1-py3-none-any.whl

Download URL bplan_geography-0.2.1-py3-none-any.whl
Size 30.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f3645f907d3fccef1d94abd651e13dc84e274f47e1439aa9e1b680b18343b41b
BLAKE2b-256 checksum
How to use checksums
484dc4333552ca605e298c7dfb13638e1399e34e4d6a5bd2a80f5031a2d402b8
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.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 bplan_geography-0.2.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.2.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