{"id":6661,"library":"gtfs-realtime-bindings","title":"GTFS Realtime Python Bindings","description":"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.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/MobilityData/gtfs-realtime-bindings","tags":["gtfs","realtime","transit","protobuf","transportation","mobility"],"install":[{"cmd":"pip install gtfs-realtime-bindings","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for parsing Protocol Buffer encoded GTFS-realtime data.","package":"protobuf","optional":false}],"imports":[{"note":"This module contains the generated Python classes for GTFS-realtime messages, such as FeedMessage, TripUpdate, and VehiclePosition.","symbol":"gtfs_realtime_pb2","correct":"from google.transit import gtfs_realtime_pb2"}],"quickstart":{"code":"import requests\nfrom google.transit import gtfs_realtime_pb2\nimport os\n\n# Replace with the actual URL of your GTFS-realtime data feed\nGTFS_REALTIME_FEED_URL = os.environ.get('GTFS_REALTIME_FEED_URL', 'https://gtfs.example.com/realtime-feed.pb')\n\n# Optional: If your API requires an API key in headers\nAPI_KEY = os.environ.get('GTFS_REALTIME_API_KEY', '')\nheaders = {'x-api-key': API_KEY} if API_KEY else {}\n\ntry:\n    response = requests.get(GTFS_REALTIME_FEED_URL, headers=headers, timeout=10)\n    response.raise_for_status()  # Raise an exception for HTTP errors\n\n    feed = gtfs_realtime_pb2.FeedMessage()\n    feed.ParseFromString(response.content)\n\n    print(f\"Successfully parsed feed from {GTFS_REALTIME_FEED_URL}\")\n    print(f\"Feed header timestamp: {feed.header.timestamp}\")\n    print(f\"Number of entities: {len(feed.entity)}\")\n\n    for entity in feed.entity:\n        if entity.HasField('trip_update'):\n            print(f\"  Trip Update: {entity.trip_update.trip.trip_id}\")\n            # Example of accessing a field, always check HasField() first\n            if entity.trip_update.trip.HasField('route_id'):\n                print(f\"    Route ID: {entity.trip_update.trip.route_id}\")\n        elif entity.HasField('vehicle'):\n            print(f\"  Vehicle Position: {entity.vehicle.trip.trip_id}\")\n            if entity.vehicle.HasField('position'):\n                print(f\"    Lat: {entity.vehicle.position.latitude}, Lon: {entity.vehicle.position.longitude}\")\n        elif entity.HasField('alert'):\n            print(f\"  Service Alert: {entity.alert.header_text.translation[0].text if entity.alert.header_text.translation else 'N/A'}\")\n\nexcept requests.exceptions.RequestException as e:\n    print(f\"Error fetching GTFS-realtime feed: {e}\")\nexcept Exception as e:\n    print(f\"Error parsing GTFS-realtime feed: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"breaking","affected_versions":"<2.0.0 and potentially future versions with protobuf incompatibilities"},{"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.","message":"Protocol 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions, especially when the GTFS-realtime spec is updated."},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions (operational concern)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}