Real time¶

Real-time data has a single source — the driver's device — and two outlets: supervision on the operator's side, and passenger information on the public side.

The chain, from vehicle to passenger¶

1. The driver's device reports its position and the progress of the trip it is operating.
2. The API derives the actual progress from it: stops served, delay, position along the shape.
3. Those elements feed the standardised feeds consumed by journey planners and displays.

Each step is readable in the API, but not in the same place nor with the same freshness: a vehicle's position is queried as of now, whereas the trace of what happened is read from history.

No device, no real time¶

This is the dependency to remember: a trip whose device is not in service is not tracked. It stays scheduled in the reference, but no actual data concerns it — no position, no delay, no passing at stops.

The device knows the trip it is operating at a given moment, designated by the triplet described on the previous page. It also carries its connection state, which makes it possible to tell a stationary vehicle from one that has stopped reporting.

An unauthenticated caller gets a reduced response on the device list and detail: position, heading, freshness, line/trip and occupancy are kept, while operator-only fields are withheld and archived devices are left out.

What goes out to passengers¶

Two standardised formats broadcast the same network state, with two different formalisms. The choice depends on what the consumer expects, not on what Pysae prefers.

Those feeds are a product, not a source: they aggregate the reference, the devices' positions, the alerts and the trip updates. A discrepancy seen in a feed is therefore diagnosed by tracing back to whichever of those inputs carries it.

In GTFS-RT TripUpdate entities, an observed departure stays associated with the stop the vehicle left, including when it heads directly to a later stop. A change in delay does not shift that already observed departure. Until a departure is known, the published time remains an estimate based on the current delay, including at the stop where the vehicle is still standing.

In GTFS-RT positions, position.bearing gives the heading in degrees clockwise from north: 0° is north and 90° is east. When known, the heading is normalized to [0, 360) in both the full and vehicle position feeds, in binary and JSON. An unknown heading remains absent; 0° indicates a known heading towards north.

Disruptions¶

Two distinct objects feed the "disruption" part of the feeds, and they must not be confused:

• an alert is a message intended for passengers — works, an event, a stop not served;
• a trip update is a change to the service itself — a stop skipped, a trip diverted. In the GTFS-RT feed it is published both as a TripUpdate (skipped stops, delay) and as a TripModifications entity (replacement stops, modified shape).

One real disruption often gives rise to both: the service changes, and it is announced.

A replacement stop the static GTFS does not contain — a stop created for the deviation, or an existing stop served somewhere else — is published in the feed as a Stop entity alongside the TripModifications, under an id of its own prefixed with rt-stop:. That id denotes the position the deviation describes, and only that one: it never reuses the id of the static GTFS stop, so a stop moved for some trips stays unchanged for every other.

Next¶

Real time says what the vehicles are doing. What remains is who drives them and under which organisation — that is the subject of the Operations page.