Feed Publishing & Implemented Practices

Supported Realtime Feed Types

This service supports the GTFS-Realtime data exchange format with the following types of information:

• Alerts — Unforeseen events affecting an agency and route.
• Trip Updates — Updated arrival and departure information.
  • Includes trips whose arrival or departure times differ from scheduled values.
  • Trips with an associated vehicle, and other trips in the same block, are included due to potential variance.
• Vehicle Positions — Information about a vehicle's location.
  • Only vehicles logged into an active trip are included.

Protocol Buffer Specification

GTFS-Realtime uses Google Protocol Buffers: a language and platform-neutral mechanism for efficient serialization of structured data (smaller and faster than XML). The data model is defined in the gtfs-realtime.proto file, which declares all message element hierarchies and types (e.g., FeedMessage, FeedHeader, FeedEntity).

Feed Encoding & Access Method

All feeds are provided as Protocol Buffer binary payloads (Content-Type: application/x-protobuf) over HTTP. Consumers request specific feeds by supplying a feed label (configured logical key) and a feed type.

Request Pattern

GET /GtfsProtoBuf?FeedLabel={feedKey}&FeedType={Alerts|TripUpdates|VehiclePositions}

• FeedLabel — Case-insensitive key identifying the configured feed (visible on the Feed Dashboard).
• FeedType — One of Alerts, TripUpdates, or VehiclePositions (case-insensitive).

Feed Refresh Cadence

Feeds are refreshed at least every 30 seconds, or sooner when underlying data (e.g., vehicle position) changes. If no entity content changes, a new FeedHeader.timestamp is still emitted to assert that the snapshot remains valid at that moment.

Internal pruning logic may remove stale entities (expired alerts, inactive vehicles, completed trips) before serialization to keep payloads relevant and lean.

Conditional Retrieval: Last-Modified & If-Modified-Since

Each response supplies a Last-Modified header derived from the feed header's UNIX timestamp (converted to RFC1123 format). Clients are encouraged to send If-Modified-Since on subsequent requests; if the timestamp has not advanced, the service returns 304 Not Modified (no body), conserving bandwidth.

This conditional model helps both producers and consumers avoid redundant parsing and transmission of unchanged binary payloads.

Conditional Retrieval: ETag & If-None-Match

In addition to Last-Modified / If-Modified-Since, the feed endpoint supports ETag-based conditional retrieval:

• Each 200 response includes an ETag header derived from the feed's content.
• Send If-None-Match: <etag> on subsequent requests; if the feed has not changed, the service returns 304 Not Modified.
• Either conditional mechanism can be used independently or together.

Protocol Buffer Feed Endpoint Details

The GTFS-Realtime protocol buffer payloads are served by the /GtfsProtoBuf endpoint. Each request returns a binary FeedMessage (as defined in gtfs-realtime.proto) with Content-Type: application/x-protobuf.

Example URLs

/GtfsProtoBuf?FeedLabel=regional&FeedType=TripUpdates
/GtfsProtoBuf?FeedLabel=regional&FeedType=VehiclePositions
/GtfsProtoBuf?FeedLabel=agencyA&FeedType=Alerts

Response Status Codes

Code	Meaning
200 OK	Feed returned successfully.
304 Not Modified	ETag or Last-Modified matched — reuse your cached payload.
400 Bad Request	Missing or invalid FeedLabel or FeedType.
404 Not Found	No current feed for the given combination.
429 Too Many Requests	Request frequency limit exceeded.
500 Internal Server Error	Unexpected server-side failure.

Feed Freshness Strategy

Internally each feed tracks the originating GTFS-Realtime FeedHeader.timestamp. Even when no underlying entity (trip, vehicle, or alert) changes, a periodic refresh ensures consumers know the data is still valid as of the latest timestamp. Expiration logic (e.g., vehicle inactivity, alert aging, trip suppression) occurs before serialization.

Caching Guidance

• Use If-Modified-Since with the previous Last-Modified value, or If-None-Match with the previous ETag.
• On a 304 response, continue using your previously parsed entities — no re-download or re-parse needed.
• Consumers should poll no more frequently than the feed refresh cadence (approximately every 30 seconds).

Data Integrity

Each message is atomic: treat the entity list as the authoritative snapshot for the requested feed type at the given timestamp. Partial updates are not issued — consumers should replace their entire local state for that feed type on each successful fetch.