Skip to main content

track-distance

PyPI Python CI Licence: GPL-3.0

Measure how far apart two railway stations are along the track, rather than as the crow flies.

Straight-line distance between stations is easy to work out and usually wrong, because railways do not run in straight lines. Manchester to Leeds is 36 miles in a straight line and 42 by rail. This package measures along the rails, using a shapefile of track centre lines and a list of station coordinates.

from track_distance import TrackDistanceCalculator

calc = TrackDistanceCalculator("NWR_TrackCentreLines.shp", "stations.csv")

calc.calculate_distance("MAN", "LDS", "miles")  # 42.34
calc.calculate_distance("EUS", "MAN", "miles")  # 183.49
calc.distances_from("LDS", "miles")  # every reachable station

Compared with published rail mileages:

Route Measured Published
London Euston to Manchester Piccadilly 183.49 mi about 184 mi
London King's Cross to Edinburgh 392.40 mi about 393 mi
London Paddington to Reading 36.51 mi about 36 mi
Manchester Piccadilly to Leeds 42.34 mi about 42 mi

Install

Python 3.11 or later.

pip install track-distance

# with interactive HTML maps
pip install 'track-distance[map]'

or, from a clone, pip install . (or pip install '.[map]'). It depends on geopandas, networkx, numpy, pandas, scipy and shapely; the map extra adds folium.

What you need

A track model: a shapefile of track centre lines. Network Rail publishes one on the Rail Data Marketplace as the Network Rail Track Model, and the file you want is NWR_TrackCentreLines.shp. Any line geometry in a metre-based projection works, including an OpenStreetMap rail extract.

A station list: a CSV with a station code, latitude and longitude. The default column names match the widely shared National Rail station list:

stationName,tiploc,lat,long,crsCode
Abbey Wood,ABWD,51.490719,0.120343,ABW

Other column names can be given:

from track_distance import StationSource, TrackDistanceCalculator

calc = TrackDistanceCalculator(
    "tracks.shp",
    StationSource("stops.csv", code_column="id", latitude_column="y", longitude_column="x"),
)

The CLI takes the same as --code-column, --lat-column and --lon-column.

Command line

$ track-distance distance MAN LDS -t NWR_TrackCentreLines.shp -s stations.csv -u miles
MAN -> LDS      42.34 miles

Give several stations and each consecutive pair is one leg:

$ track-distance distance MAN HUD LDS YRK -t tracks.shp -s stations.csv -u miles
MAN -> HUD      25.31 miles
HUD -> LDS      18.15 miles
LDS -> YRK      26.16 miles
total             69.62 miles

Every station reachable from one, nearest first:

$ track-distance from LDS -t tracks.shp -s stations.csv -u miles -n 5
From LDS (2,601 reachable stations)
  COT       1.23 miles
  MLY       1.23 miles
  BUY       1.33 miles
  BLE       2.78 miles
  HDY       2.86 miles

Add --map route.html to distance for an interactive map of a single leg, --json for machine-readable output, or -v to log progress.

How it works

The track model becomes a graph. Each stretch of line is an edge weighted by its real length, and the points where stretches meet are nodes. The distance between two nodes is a shortest-path search: networkx for a single route, and scipy for distances_from(), which finds every station at once.

Only each line's two end points become nodes, not every vertex along it. Track segments meet end to end, so that is enough to route across the network, and it keeps the graph to about 39,000 nodes for the whole of Great Britain.

Stations are not in the track model, so each is projected into the model's coordinate system and attached to a nearby node, found with a KD-tree.

Disconnected fragments

A track model has small fragments that connect to nothing: sidings, stubs and digitising artefacts. A station beside one would attach to it and become unreachable from everywhere else. Nothing raises an error when that happens; the station just has no routes, which looks downstream like a station nobody travels to.

So the candidate nodes near each station are taken in order of distance, and the first one on the largest connected part of the network is used. If none of them is on it, the station goes to the nearest node on the main network as long as that is within 1 km. Spondon needs this: it sits beside a 26-node fragment, and its nearest main-network node is 710 m away. Stations on a genuinely separate network, such as the Isle of Wight's, are kilometres from the main one and keep their own nearest node. On the September 2026 Network Rail model this moves 39 stations off fragments:

INFO Snapped 39 station(s) past a disconnected track fragment onto the main network:
ALF, BFE, BFF, BOR, BOW, CEA, CFL, CGW, CLK, CUW, CYK, DUD, DWD, EDL, ENL, ERI, FMT,
FYS, HDW, HOL, HPE, HTW, KEI, KWL, MIR, NAR, NWH, PFY, PNF, PNM, PRT, SDY, SHH, SIN,
SPO, STK, TUR, WDS, WTL

Run with -v to see the list. If yours is much longer, the track model probably has connectivity problems worth looking into.

Routes that cannot be right

Some gaps are in the main network itself. Headbolt Lane and Kirkby are a mile apart, but the 2023 link between them is not joined up in the model, so the route goes the long way round:

$ track-distance distance HBL KIR -t tracks.shp -s stations.csv -u miles
HBL -> KIR      39.84 miles
$ track-distance distance HBL KIR -t tracks.shp -s stations.csv -u miles --plausible
HBL -> KIR       1.04 miles

With --plausible (or plausible=True in Python), a route shorter than 0.9 times the straight line or longer than 3 times it is treated as a gap in the model. The straight line times 1.2 is used instead, 1.2 being the median ratio of route to straight line across about 9,900 station pairs. Stations closer than 800 m are left alone. It is off by default, so you see what the track model says unless you ask.

Totals on shared track

route_edges() returns the physical segments a route uses, with keys that do not depend on direction:

from collections import Counter

usage = Counter()
for origin, destination in corridors:
    usage.update(calc.route_edges(origin, destination))

Use this to colour a map by flow without overdrawing. Around a hub, dozens of corridors share the same rails, and drawing one full route per corridor stacks them on top of each other. Totalling onto shared segments gives one line per stretch of track with a real total.

Performance

Building the calculator reads the shapefile and builds the graph, which takes about a second for the whole network, so build it once and reuse it. Routes are cached in both directions, since track distance is symmetric.

For many destinations from one origin, use distances_from(). It runs one shortest-path search for all of them instead of one per pair.

Limitations

  • This is track distance, not journey distance. It is the shortest path over the physical network. A train may take a longer route for operational reasons, and the route a ticket allows is a separate question for the National Routeing Guide.
  • Every edge can be used in both directions by any train. Single-line working, freight-only lines and closed sections are not distinguished unless your track model leaves them out.
  • A station attaches to the end of a track segment, not to the closest point along it. Over a whole journey that makes little difference; for two stations a few hundred metres apart it can.
  • The working coordinate system must be in metres, because edge weights are geometry lengths. The default is the British National Grid (EPSG:27700); pass working_crs (or --working-crs) elsewhere.
  • Unreachable pairs raise NoRouteError and unknown codes raise StationNotFoundError. distances_from() leaves unreachable stations out.

Python API

Name
TrackDistanceCalculator(track_shapefile, stations) build the graph and attach the stations
.calculate_distance(origin, destination, unit="km", plausible=False) one distance
.distances_from(origin, unit="km", plausible=False) every reachable station
.route_edges(origin, destination) the track segments a route uses
.route_geometry(origin, destination) the route's line geometries
.route_frame(origin, destination) the route as a GeoDataFrame
.save_map(origin, destination, path) an interactive HTML map (needs the map extra)
StationSource(path, ...) a station CSV and its column names
convert_metres(metres, unit) metres to km, miles or metres

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
  • 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
  • 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/track-distance
cd track-distance
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check . && ruff format --check . && mypy src

The tests build a small network in British National Grid coordinates with round metre positions, so the expected distances are exact. The station CSV is made by projecting those positions back to latitude and longitude, so the tests go through the real projection code. The disconnected fragment case has its own fixture. No licensed data is committed.

Licence

GPL-3.0. See LICENSE.

Not affiliated with or endorsed by Network Rail.

Metadata

Release files for track-distance 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 track-distance 0.2.1
File Size Uploaded Provenance Actions
track_distance-0.2.1.tar.gz 34.8 kB With provenance Details for track_distance-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for track-distance 0.2.1
File Interpreter ABI Platform Actions
track_distance-0.2.1-py3-none-any.whl Python 3 none any Details for track_distance-0.2.1-py3-none-any.whl

Total release size: 64.2 kB

Release files / track_distance-0.2.1.tar.gz

Download URL track_distance-0.2.1.tar.gz
Size 34.8 kB
Tags Source
SHA-256 checksum
How to use checksums
b03fe5578ffe3e67405555e997456d698ad6d77152f68f4e725c6a0bbc5bf5b4
BLAKE2b-256 checksum
How to use checksums
671a033f667070f204bcc515ec665e2d4fe507be1fc48b481c92d77e4b64a988
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 / track_distance-0.2.1-py3-none-any.whl

Download URL track_distance-0.2.1-py3-none-any.whl
Size 29.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb65381422e7583de683fcc20e4860b66cf3d2910f4b584cb4be12f7094972f1
BLAKE2b-256 checksum
How to use checksums
987cbf7c019ba55379a71e8b8ce648eb5fcb4aaa1785fe5d66c5d97a73d4a370
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 track-distance 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 track_distance-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