Real Time

Real Time data can be used to track the progress of trips, vehicle details, route and stop information for both scheduled and live tracked trips.

Overview

Distribusion serves real-time transit data via GTFS-RT feeds on the Distribusion API. These feeds give retailers live vehicle positions, estimated arrival/departure times, and cancellation status for active rides.

GTFS-RT feeds work only in combination with static GTFS files — the static file defines the schedule, and the real-time feed provides updates to it (estimated times, cancellations, positions). Without the static baseline, real-time data cannot be interpreted.

Available Feeds

Two feeds per carrier, following GTFS-RT spec v2.0. All return the full current state (FULL_DATASET) — not incremental deltas.

Endpoints

Auth: standard Distribusion API Api-Key header.

Format: Protocol Buffers (protobuf).

Prerequisites

To consume GTFS-RT feeds you need:

1. Static GTFS file for each carrier — kept in sync with Distribusion's published version. Trip IDs in real-time feeds reference the current static file.
2. GTFS-RT parser — any standard library that reads protobuf GTFS-RT messages.
3. Polling — pull model. Recommended intervals: 15–60s for vehicle positions, 30–120s for trip updates.

Static GTFS is mandatory. Real-time feeds reference trip, route, and stop IDs from the static file. They cannot be used standalone.

Feed Structure and Examples

Both feeds return data in Protocol Buffers (protobuf) format only. There is no JSON interface on the API.

Note on examples below: The examples in this section are shown in JSON purely for illustration purposes, to make the data structure easier to read. The actual API responses are protobuf-encoded and must be parsed with a GTFS-RT protobuf library.

How trip IDs connect to static GTFS

Every entity contains a trip object with a trip_id that matches a record in the trips.txt file of the corresponding static GTFS. The stop_id values in stop time updates match records in stops.txt. This is how you join real-time data with the static schedule.

Trip Updates — example entity

{
  "id": "1218367546",
  "trip_update": {
    "trip": {
      "trip_id": "NEXP-19:55-GBBLKCCS-196e10cd",
      "start_date": "20260521",
      "schedule_relationship": "SCHEDULED"
    },
    "stop_time_update": [
      {
        "stop_sequence": 0,
        "stop_id": "GBBLKCCS",
        "arrival": {
          "time": "2026-05-21T18:58:42.997000+00:00"
        },
        "departure": {
          "time": "2026-05-21T18:58:42.997000+00:00"
        }
      },
      {
        "stop_sequence": 1,
        "stop_id": "GBMANCBS",
        "arrival": {
          "time": "2026-05-21T20:14:06.986000+00:00"
        },
        "departure": {
          "time": "2026-05-21T20:14:06.986000+00:00"
        }
      }
    ],
    "timestamp": "2026-05-21T19:02:20+00:00"
  }
}

Key fields:

• trip.trip_id → matches trip_id in static GTFS trips.txt
• trip.schedule_relationship → SCHEDULED (running) or CANCELED
• stop_time_update[].stop_id → Distribusion station code (e.g. GBBLKCCS), matches stop_id in static GTFS stops.txt
• stop_time_update[].arrival.time / departure.time → current estimated times (ISO 8601)

Vehicle Positions — example entity

{
  "id": "1218367546",
  "vehicle": {
    "trip": {
      "trip_id": "NEXP-19:55-GBBLKCCS-196e10cd",
      "start_date": "20260521",
      "schedule_relationship": "SCHEDULED"
    },
    "vehicle": {
      "id": "vehicle_000-6bf0e592547b"
    },
    "position": {
      "latitude": 53.805274963378906,
      "longitude": -3.0455329418182373
    },
    "timestamp": "2026-05-21T19:02:36+00:00"
  }
}

Key fields:

• trip.trip_id → same trip ID as in Trip Updates and static GTFS
• position.latitude / longitude → WGS84 coordinates
• timestamp → when the position was recorded

Response envelope

Both feeds wrap entities in the same envelope:

{
  "header": {
    "gtfs_realtime_version": "2.0",
    "incrementality": 0,
    "timestamp": "2026-05-21T19:02:20+00:00"
  },
  "entity": []
}

incrementality: 0 means FULL_DATASET — each response is the complete current state, not a delta.