Feed to Report

What actually arrives

Two HTTP requests to the Bus Open Data Service, one per bounding box, repeated round the clock. This is one real pair, timed while writing this page.

Two boxes rather than one because the two service areas are 250 km apart, and a single rectangle drawn round both is most of England — four times the vehicles to match and store for the same two areas' worth of answers.

One vehicle, exactly as it came off the wire

id: "37fa80bc-fe90-483b-bfb1-1e8aec8d3f03"
    vehicle {
      trip { trip_id: ""
             route_id: "" }
      position { latitude: 53.3651772
                 longitude: -3.06502604
                 bearing: -1 }
      timestamp: 1787681530
      vehicle { id: "A2BV-24" }
    }

That is the whole record. A fleet number, a point, a clock reading. No stop, no route in this case, and — on every vehicle in the country, in both feeds BODS publishes — no delay. Nothing here says whether this bus is early or late. Everything else on this page is built from that absence.

Note the heading, too: bearing: -1 is GTFS-RT for don't know, and a quarter of the fleet sends it — some publishers send 0 for the same thing, which is why due north turns up fourteen times more often than any other single degree. Both are dropped, and a heading is worked out instead from the ground the bus has covered since its last fix. A bus that hasn't moved is drawn without an arrow rather than with one pointing north.

Where a delay figure comes from

The poller keeps each bus's place along its scheduled journey between polls. When a bus is seen far enough past a stop, it writes down that the bus left — and what time the timetable said it should have.

Below is one real journey from the capture window: Stagecoach Yorkshire 26030, service 28, Pontefract Bus Station 19:45 → Barnsley Interchange 20:55, on 25 August. The timetable gives it 81 stops, ten of them timing points. Sixty-six departures were recorded. Each bar is one of them: how far from its due time the bus actually left.

The shaded band is "on time" as the UK convention defines it: one minute early to five minutes late. Every one of these 66 departures sits inside it. The journey lost three and a half minutes and still scores 100% — which is what the convention is for, and also what it hides. Timing points, the stops an operator publishes times for and is held to, are marked below the axis; times at the stops between them are interpolated by the publisher rather than promised, which is why the reporting scores timing points only.

Read left to right, this is a journey losing three and a half minutes through Pontefract in the first ten stops, holding that gap along the A628, and pulling it back to arrive half a minute early. One row of one report, from a bus that never reported a delay at any point.

What gets written down

The split matters when someone asks why a figure moved. The live board can be wrong for ninety seconds and self-correct; the record cannot be re-derived, because the feed is a snapshot with no history. If the poller is down for an hour, that hour is simply not evidence, and every report that touches it has to say so rather than count it as failure.

The window you have just watched, in the record

1,342 timing-point departures, from 1,361 journeys and 55 operators, in five minutes and fifty seconds. Bands are the UK convention: on time is one minute early to five minutes late.

The mechanism, in detail

Everything above, restated as it is actually implemented. The values below are the ones the running poller uses; where a figure is a threshold somebody chose, the reason it is that number is given with it.

One poll, in full

GET https://data.bus-data.dft.gov.uk/api/v1/gtfsrtdatafeed/
    ?api_key=<key>&boundingBox=-3.80,52.90,-0.10,55.90

feed = gtfs_realtime_pb2.FeedMessage()
feed.ParseFromString(response.content)      # protobuf, not JSON

Two of those, one per bounding box, every ten seconds — so 17,280 requests a day. The feed is a complete snapshot each time rather than a stream of changes, which is why a missed poll costs resolution and nothing else, and why the poller backs off to a maximum of five minutes rather than retrying hard against an API that is already struggling.

The same bus can arrive twice in one pass. Boxes are not meant to overlap, but the feed also repeats vehicles inside a single box — 8 of 7,838 northern vehicles on 21 August, all of them untracked, where two operators happened to use the same fleet number. Vehicles are therefore keyed on (vehicle_id, route_id, trip_id) and the fresher fix wins: position deliberately plays no part in identity, because two requests a moment apart legitimately carry different fixes for the same bus. Untracked vehicles report 0.0, 0.0 rather than omitting the position, so null-island fixes are dropped before anything else looks at them.

From a point to a place on the journey

A latitude and longitude are not progress. Every question the reports ask — how far along, how late, which stops have been served — comes from one derived number: the distance the vehicle has travelled along its trip. That is obtained by projecting the position onto the chain of the trip's stops and reading the schedule off at that point, interpolating between the stops either side so that a bus halfway between two of them is not counted late by the whole hop.

A projection can be wrong, and most of the work is in refusing bad ones. Circular services pass the same road twice; a bus can be legitimately far from the straight line between two stops; equipment goes quiet mid-journey. These are the limits that decide what is accepted:

The moment a bus counts as having left

At a ten-second poll a bus doing 30 mph moves about 130 metres between fixes, so it can clear a stop without ever being seen near it. Nothing is detected by proximity. A stop is served when the vehicle's progress crosses it — when the distance travelled goes from below the stop's position on the chain to above it — and the time it did so is interpolated between the two fixes either side.

previous_distance < mark <= current_distance   # the whole test

mark = cumulative[i] + min(40 m, gap_to_next / 2)   # departure
mark = cumulative[i]                              # arrival

Two marks per stop, forty metres apart, and which one is used is the single most consequential choice on this page. Arrival is when the bus reaches the stop; departure is when it has cleared it. A bus that arrives early at a timing point waits there until it is due, so timing arrivals records correct behaviour as early running — which is what moved "early" from 19.9% to 6.7% when it was corrected. The terminus is the exception in both directions: a bus that finishes its journey never departs, so the arrival is all there is, and it is compared against the scheduled arrival rather than a departure that does not exist.

Two writes, two shapes

Every poll ends in exactly two statements, and their conflict clauses are where the difference between the live table and the record actually lives.

INSERT INTO vehicle_positions (…)
VALUES %s
ON CONFLICT (vehicle_id)
  DO UPDATE SET …

INSERT INTO stop_observations (…)
VALUES %s
ON CONFLICT (service_date, trip_id,
             stop_sequence)
  DO NOTHING

One row per vehicle, overwritten forever; one row per departure, written once and never revised. DO NOTHING is what makes the record idempotent: the poller can restart mid-journey, re-observe stops it has already recorded, and change nothing. It also means the first observation of a departure is the one that stands, which is the right way round — a later re-match is a guess made with less information, not more.

The record is indexed for the three questions the reports ask of it — by line and date, by stop and date, by operator and date — and pruned to 35 days by the same nightly job that aggregates it. Departures are kept at timing points only, except in two ATCO areas (370 South Yorkshire and 450 West Yorkshire) where the journey-times reports need a run time and a dwell at every stop. That exception is scoped by area because that is what the cost scales with: every stop in South Yorkshire is ~290k rows a weekday, every stop across everything polled would be ~2.3M, and ~5 GB a month becomes ~40 GB. is_timepoint marks which rows are promised times and which are the publisher's interpolations.

What is joined to what

"Combined" is four joins, and only one of them is on anything the live feed provides. Everything else is keyed on identifiers that come out of the weekly timetable export or are already encoded in the stop code itself.

The first row is the whole fragility of the system in one line. A journey id that no longer resolves does not error — it produces a bus that is on the road, in the feed, and absent from every report.

The last row is what we do about it downstream. Matching a live bus has to use the id the feed quotes; a report does not, and since 17 September every journey we schedule is also given a key of our own that a republished timetable cannot move. It is what the exported files ask people to join on.

And then it is arithmetic

The nightly aggregation is one INSERT … SELECT … GROUP BY per job. Punctuality groups a day's departures by service date, area, operator, line and hour, counts each band with a filtered aggregate, and keeps two extra columns — the sum of delays and the sum of their squares — so that variance can be recovered later without going back to rows that will have been pruned:

GROUP BY service_date, LEFT(stop_id, 3), operator_noc, line_name,
         route_id,
         EXTRACT(HOUR FROM scheduled_at AT TIME ZONE 'Europe/London'),
         EXTRACT(MINUTE FROM scheduled_at AT TIME ZONE 'Europe/London') / 30

The route is in that list because a line number is not a service: Stagecoach Yorkshire run two services called 21, Barnsley to Penistone and Rotherham to Harthill, with not one stop in common, and a mean across both describes neither. The half-hour is there because the bands this is reported against do not all turn on the hour — the AM peak ends at 09:30 — and hour keeps its meaning, so anything grouping by it alone still sums both halves. Between them they are why this table holds 67,785 rows for a day rather than 34,279.

The time zone in that last line is not decoration. The server runs on CEST; bucketing on its clock would label the morning peak 09:00 for buses that ran it at 08:00, and that is the sort of number which gets quoted in a meeting long before anyone notices it is an hour out.

Turning a night's departures into a day's figures

Nothing on the reports queries thirteen million raw rows. Each night, five jobs reduce the day to something a page can read in milliseconds. These are the counts for Wednesday 16 September 2026.

Keeping the timetable in step

A position only means something against the journey it was supposed to be running. That comes from the national GTFS export, and it goes stale faster than anyone expects.

Currently loaded: export 20260822_024148, imported 23 August — 403,136 journeys, 17,381,506 scheduled stop times, 312,501 stops, 634 operators. One unattended job downloads the national export, rebuilds the journey-planning graph, imports the same export into the timetable tables, and restarts the poller, so the two can never drift apart.

The failure this guards against is silent. A re-issued timetable does not produce an error; it produces an operator whose buses are on the road, in the feed, and absent from every report. That is why the reporting carries a coverage panel comparing scheduled journeys against departures actually recorded, per operator.

What comes out

Everything above, combined. Every figure below comes out of the two tables on this page and the timetable they are matched against — nothing else feeds them.

What this data cannot tell you

The gaps are properties of the feed, not of the build. Each was measured nationally rather than assumed.