cif-timetable
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.
JsonAssociationV1records (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:
0712is0712. 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_routescounts ordered pairs of stops, so busy stations have a great many routes. 84,307 routes for Great Britain is expected.
Related packages
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.