Registry / serialization / gtfs-realtime-bindings

gtfs-realtime-bindings

library2.0.0pypypi✓ verified 84d ago

The gtfs-realtime-bindings library provides Python classes generated from the GTFS-realtime Protocol Buffer specification. These classes enable developers to parse binary Protocol Buffer GTFS-realtime data feeds into Python objects, facilitating the consumption of real-time transit information. The project is currently at version 2.0.0 and has been maintained by MobilityData since early 2019, with updates typically released to stay in sync with the evolving GTFS-realtime specification and Protobuf library.

serialization data

pip install gtfs-realtime-bindings

github ↗package ↗

INSTALL

IMPORT

SIG · GTFS-REALTIME-BIND

gtfs-realtime-bindings

serializationpythonv2.0.0

Install

1.9s avg

Import

184ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.312s · 19.5MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.9s · import 0.057s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gtfs_realtime_pb2

✓ from google.transit import gtfs_realtime_pb2

This module contains the generated Python classes for GTFS-realtime messages, such as FeedMessage, TripUpdate, and VehiclePosition.

This quickstart demonstrates how to fetch a GTFS-realtime feed from a URL, parse its binary content into a `FeedMessage` object, and iterate through its entities to print basic information about trip updates, vehicle positions, or service alerts. It uses the `requests` library for fetching the data, which is a common pattern for consuming GTFS-realtime feeds.

import requests from google.transit import gtfs_realtime_pb2 import os # Replace with the actual URL of your GTFS-realtime data feed GTFS_REALTIME_FEED_URL = os.environ.get('GTFS_REALTIME_FEED_URL', 'https://gtfs.example.com/realtime-feed.pb') # Optional: If your API requires an API key in headers API_KEY = os.environ.get('GTFS_REALTIME_API_KEY', '') headers = {'x-api-key': API_KEY} if API_KEY else {} try: response = requests.get(GTFS_REALTIME_FEED_URL, headers=headers, timeout=10) response.raise_for_status() # Raise an exception for HTTP errors feed = gtfs_realtime_pb2.FeedMessage() feed.ParseFromString(response.content) print(f"Successfully parsed feed from {GTFS_REALTIME_FEED_URL}") print(f"Feed header timestamp: {feed.header.timestamp}") print(f"Number of entities: {len(feed.entity)}") for entity in feed.entity: if entity.HasField('trip_update'): print(f" Trip Update: {entity.trip_update.trip.trip_id}") # Example of accessing a field, always check HasField() first if entity.trip_update.trip.HasField('route_id'): print(f" Route ID: {entity.trip_update.trip.route_id}") elif entity.HasField('vehicle'): print(f" Vehicle Position: {entity.vehicle.trip.trip_id}") if entity.vehicle.HasField('position'): print(f" Lat: {entity.vehicle.position.latitude}, Lon: {entity.vehicle.position.longitude}") elif entity.HasField('alert'): print(f" Service Alert: {entity.alert.header_text.translation[0].text if entity.alert.header_text.translation else 'N/A'}") except requests.exceptions.RequestException as e: print(f"Error fetching GTFS-realtime feed: {e}") except Exception as e: print(f"Error parsing GTFS-realtime feed: {e}")

Debug

Known issues

breakingThe `gtfs-realtime-bindings` library relies on the underlying `protobuf` library. Future major versions of `protobuf` (e.g., beyond 5.0) may introduce breaking changes or require specific versions for optimal compatibility, potentially leading to parsing errors if `protobuf` is not correctly managed.

fix

Ensure your `protobuf` installation is compatible with the `gtfs-realtime-bindings` version. Regularly check the project's GitHub issues for reported `protobuf` compatibility problems and upgrade your `protobuf` library as recommended by the `gtfs-realtime-bindings` project.

affects: <2.0.0 and potentially future versions with protobuf incompatibilities

gotchaProtocol Buffers distinguish between a field explicitly set to its default value (e.g., 0 for an integer) and a field that is entirely unset. Directly accessing fields without checking for their presence using the `HasField()` method can lead to misinterpretation, as an unset field will return its default value in Python, which might not be the intended semantic zero or empty string.

fix

Always use `if entity.HasField('field_name'):` before attempting to access the value of an optional field to ensure it was present in the original data stream.

affects: All versions

gotchaThe `gtfs-realtime-bindings` library is generated from the `gtfs-realtime.proto` specification. The GTFS Realtime specification itself evolves, introducing new fields, deprecating old ones, or clarifying semantics (e.g., GTFS-realtime v2.0 spec). Using older bindings with newer feeds (or vice-versa) may result in parsing issues or incorrect interpretation of data, particularly with experimental features or required field changes.

fix

Keep your `gtfs-realtime-bindings` library updated to the latest version to ensure compatibility with the most recent `gtfs-realtime.proto` specification. If working with feeds that use experimental features, be aware that these may change or be removed in future spec updates.

affects: All versions, especially when the GTFS-realtime spec is updated.

gotchaThe GTFS Realtime specification provides guidelines on data freshness. Specifically, Trip Updates and Vehicle Positions should generally not be older than 90 seconds, and Service Alerts not older than 10 minutes. Consuming stale data, even if successfully parsed, can lead to inaccurate real-time information for end-users.

fix

Implement checks on the `FeedHeader.timestamp` to ensure the data being processed is within acceptable freshness thresholds. Contact the data producer if feeds are consistently stale.

affects: All versions (operational concern)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'google.transit.gtfs_realtime_pb2'

The 'gtfs-realtime-bindings' library, which contains the generated Python Protocol Buffer classes, is either not installed or not correctly installed in the Python environment being used.

fix

Install the package using pip: `pip install --upgrade gtfs-realtime-bindings`

google.protobuf.message.DecodeError: Tag had invalid wire type.

This error occurs when the data provided to `feed.ParseFromString()` is not a valid GTFS-realtime Protocol Buffer binary message. This could be due to an incorrect data source URL, the server returning an HTTP error page (e.g., HTML) instead of binary data, or corrupted feed data.

fix

Verify the URL of your GTFS-realtime feed, check the HTTP response status code before attempting to parse, and ensure the content received is the expected binary protobuf data. For example, check `response.status_code` and `response.headers['Content-Type']` if using `requests`.

AttributeError: module 'google.transit.gtfs_realtime_pb2' has no attribute 'FeedMessage'

This error typically arises when attempting to access `FeedMessage` directly from the `gtfs_realtime_pb2` module without properly instantiating it, or due to an older/corrupted installation.

fix

Ensure you are importing the module correctly and then creating an instance of `FeedMessage`: `from google.transit import gtfs_realtime_pb2; feed = gtfs_realtime_pb2.FeedMessage()`.

Upgrade

Version history

2.0.0latest on PyPI · released Dec 3, 2025

Audit

Dependencies

protobufrequiredRequired for parsing Protocol Buffer encoded GTFS-realtime data.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/MobilityData/gtfs-realtime-bindings ↗

packagehttps://pypi.org/project/gtfs-realtime-bindings/ ↗