Skip to main content

cif-timetable

PyPI Python CI Licence: GPL-3.0

Turn Network Rail's SCHEDULE feed into a flat table of calling points, and count how many trains run on each route.

The feed holds every train schedule in Great Britain as newline-delimited JSON, about 690,000 schedules in a 3.5 GB daily extract. Each one is a nested record with a validity window, a running-day bitmap and a calling pattern addressed by TIPLOC. Getting from that to the number of trains from A to B on a Wednesday takes more work than it looks.

from pathlib import Path
from cif_timetable import load_tiploc_crs_map, clean_timetable, analyse_routes

feed = Path("CIF_ALL_FULL_DAILY_toc-full.json")
mapping = load_tiploc_crs_map(feed, station_reference=Path("stations.csv"))
clean_timetable(feed, Path("timetable"), tiploc_to_crs=mapping)
analyse_routes(Path("timetable"))

Install

Python 3.11 or later.

pip install cif-timetable

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

Getting the feed

The SCHEDULE feed comes from Network Rail Open Data (free registration) or the Rail Data Marketplace. Download the JSON version, not the fixed-width CIF; this package reads only the newline-delimited JSON. The Open Rail Data wiki documents the record types.

You also need a station list with stationName and crsCode columns. The next section explains why.

Stations that go missing

The feed publishes several TIPLOCs for some stations, one per platform group. For some of them crs_code is null, even though tps_description names the station plainly:

{"tiploc_code": "WATRLMN", "crs_code": null, "tps_description": "LONDON WATERLOO"}

A call you cannot match to a station is no use, so any code that drops calls without a CRS loses those stations, without an error or a warning. On a national run that removes Waterloo, Victoria, London Bridge, Clapham Junction and Vauxhall, and every South Western flow into London with them.

Pass a station list and those TIPLOCs are recovered by matching the description against station names. On a real extract that recovers 39 TIPLOCs, and they are the ones you would expect:

WATRLMN -> WAT     CLPHMJC -> CLJ     LNDNBDE -> LBG
VICTRIC -> VIC     CLPHMJW -> CLJ     LNDNBDC -> LBG
VICTRIE -> VIC     VAUXHLM -> VXH     VAUXHLW -> VXH

Only exact matches count, after platform group qualifiers such as (MAIN) or PLATFORMS 1-4 are stripped. A description that does not resolve to exactly one station stays unmapped, so a depot, ferry pier or rail replacement bus stop never gains train service: CEEVILLE DEPOT does not become CEEVILLE. A few descriptions are too abbreviated to match, such as STOURBRIDGE JN (TOWN PLAT); give those in a JSON file with --overrides.

Without a station list you get a warning:

WARNING 8513 TIPLOC(s) have no published CRS and no station reference was given to
recover them. Calls at those locations will be unusable, which is how London Waterloo
goes missing. Pass station_reference to fix it.

Two steps

$ cif-timetable clean CIF_ALL_FULL_DAILY_toc-full.json -o timetable \
    --station-reference stations.csv
schedules read        690,533
schedules kept        559,702
call rows           6,769,321
-> timetable/timetable_calls.csv

That takes under a minute for a 3.5 GB extract. The file is streamed, and a substring test skips the JSON parse for the record types that are not needed, which is most lines.

$ cif-timetable routes -d timetable --top 8
84,307 routes -> timetable/route_frequency_summary.csv

origin_crs destination_crs  daily_trains  peak_tph  peak_hour
       WAT             CLJ           652        41          7
       CLJ             WAT           623        41         17
       VXH             CLJ           537        37         17
       WAT             VXH           537        37         17
       VXH             WAT           529        37          8
       CLJ             VXH           529        37          8
       LVJ             BKQ           435        28          8
       BKQ             LVJ           434        28          8

Waterloo to Clapham Junction, with 41 trains an hour in the morning peak, is the busiest pair in the country, and it would not appear at all without the CRS recovery above.

routes also writes route_frequency_hourly.csv, with trains per route per hour. Use --date to choose the day, --exclude-operator to leave an operator out, and --json for machine-readable output.

How trains are counted

Grouping rows is not enough, for two reasons.

A schedule is not a train. Each has a validity window and a running-day bitmap, and one service can appear several times as seasonal variants, so counting rows counts some trains twice or more. Instead a snapshot date is chosen, either the one you give or the middle of the data's own span moved to a Wednesday. Only schedules that are permanent, cover that date and have a 1 in that weekday's place in the bitmap are counted. Short-term overlays, buses, ships and empty stock are left out.

A route is more than a train's two ends. Every ordered pair of a service's public stops counts as one train, timed by the earlier stop's departure hour. A Leeds to London train counts towards Leeds to Wakefield, Wakefield to Doncaster and Leeds to London alike, because a passenger can use it for any of them. Counting only origin to destination would show Wakefield to Doncaster with almost no service.

Scope

Give clean a station list and only schedules touching those stations are kept:

cif-timetable clean feed.json -o timetable -s my-stations.csv

A kept schedule keeps its whole calling pattern: every in-scope stop plus every public stop anywhere. A Leeds to London train's London terminus is recorded even when London is out of scope, so the journey can still be looked up. Only out-of-scope operational passes are dropped. The in_scope column says whether each stop is one of the selected stations.

The calls table

timetable_calls.csv has one row per calling point, with the service's fields repeated on each row so the table is flat:

Group Columns
Service train_uid, stp_indicator, atoc_code, days_runs, start_date, end_date, train_category, power_type, timing_load, speed, signalling_id
Whole journey svc_origin_crs, svc_origin_tiploc, svc_origin_dep, svc_dest_crs, svc_dest_tiploc, svc_dest_arr, n_scope_stops
This call seq, tiploc, crs, location_type, arrival, departure, pass, public_arrival, public_departure, is_public_call, in_scope

read_public_calls() reads it back filtered to permanent, public, passenger calls with a CRS. That is what most analysis wants, and it is a fraction of the rows.

rail-loading reads this table to fill in departure times that train operators leave out of their passenger counts.

Limitations

  • Associations are not followed. JsonAssociationV1 records (trains joining and dividing) are skipped, so a journey that needs a portion change is not shown as a through service.
  • Short-term changes are left out, not applied. Only permanent (P) schedules are counted, so an overlay or cancellation that changes a train on your snapshot date is ignored.
  • Times stay as clock strings: 0712 is 0712. Trains running past midnight are not moved onto the next day.
  • There is no routeing or ticketing logic. The table says what the feed says a train does, not whether a ticket is valid on it.
  • analyse_routes counts ordered pairs of stops, so busy stations have a great many routes. 84,307 routes for Great Britain is expected.

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
  • 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/cif-timetable
cd cif-timetable
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 synthetic feed with the same record shapes as the real one. It includes a TIPLOC published without a CRS, a depot that must not match a station, a Sunday-only train, a short-term overlay, a bus and a pass-only service, and each exclusion rule has a test. No licensed data is committed.

Licence

GPL-3.0. See LICENSE.

Not affiliated with or endorsed by Network Rail.

Metadata

Release files for cif-timetable 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 cif-timetable 0.1.1
File Size Uploaded Provenance Actions
cif_timetable-0.1.1.tar.gz 38.4 kB With provenance Details for cif_timetable-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cif-timetable 0.1.1
File Interpreter ABI Platform Actions
cif_timetable-0.1.1-py3-none-any.whl Python 3 none any Details for cif_timetable-0.1.1-py3-none-any.whl

Total release size: 71.3 kB

Release files / cif_timetable-0.1.1.tar.gz

Download URL cif_timetable-0.1.1.tar.gz
Size 38.4 kB
Tags Source
SHA-256 checksum
How to use checksums
4a284fedc8464ae1154324bdc4f124111251da659fb81a50258e1a75fd4fb9c8
BLAKE2b-256 checksum
How to use checksums
0a43ae1f53242ea63dbcd3a587120c885d0f2adc6a5e16d31c30b4adab83b9e3
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 / cif_timetable-0.1.1-py3-none-any.whl

Download URL cif_timetable-0.1.1-py3-none-any.whl
Size 32.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eacbd58193f7f5fc1ba2e64c32051965fea8d51595ac01d77f54e994214d34e9
BLAKE2b-256 checksum
How to use checksums
d08fa412f0269ed817ef7e7e4d9c5f84858b0bc4ce6dbbdc65ff2cf626777eb5
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 cif-timetable 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 cif_timetable-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