Merged and Multi-Property GTFS Feeds

Applies to: Avail GTFS static feeds and GTFS-Realtime feeds
Audience: Transit agencies, trip planners and other GTFS data consumers

An Avail merged feed puts more than one set of schedule data into a single GTFS feed. This article explains how to recognize a merged feed, how its IDs are structured, how schedule versions hand over on the calendar, and how to match GTFS-Realtime data to the static feed.

In this article

• Overview
• How to recognize a merged feed
• ID structure
• Calendar
• GTFS-Realtime
• Guidance for consumers
• FAQ

Overview

A merged feed combines more than one set of schedule data, and a suffix on each affected ID tells the sets apart. There are two kinds of merge, and one feed can use both.

With a schedule-change merge, the new schedule is in the feed before it starts. Trip planners can show it ahead of time, and there's no gap when it takes over. With a multi-agency merge, riders get one feed for the whole operation.

How to recognize a merged feed

Look at trip_id in trips.txt. If the IDs end in -v followed by a version, the feed is merged. If they also end in -a followed by a number, it's a multi-agency feed.

ID structure

IDs that belong to one schedule version end in -v<version>. In a multi-agency feed, -a<agency_id> comes after that. Treat every ID as an opaque string: the suffix is part of the ID.

The version is hexadecimal. It goes up by one with each schedule publish, so v9 is followed by vA through vF, then v10. Read it as text or as base 16. A script that only accepts digits will miss a version like vC. In a multi-agency feed, each agency has its own version number.

Same base ID, different trip. Apart from the suffix, a trip ID often stays the same from one version to the next, for example t219-bD-sl1C-v63 and t219-bD-sl1C-v64. These are different trips. A system that strips or ignores the suffix will merge them by mistake.

Stops in multi-agency feeds. A stop that two agencies both serve appears once for each agency. The copies have the same stop code, name and location but different IDs, such as 1005-a1 and 1005-a2. A trip planner may show both.

Calendar

In a schedule-change merge, the two versions never share a service date. The current version covers every date before the new schedule's start date, and the new version covers the start date onward. In a multi-agency merge, the agencies' schedules run side by side on the same dates.

Service days past midnight. Avail assigns each trip to a service day using the agency's own service-day boundary, not the calendar day. A trip that starts late and runs past midnight belongs to the service date it started on. At a changeover, late-night trips from the old version's last day keep the old version's IDs until they finish.

Service is defined either in calendar_dates.txt alone, which lists every service date, or in calendar.txt with exceptions in calendar_dates.txt. Which one a feed uses varies by agency. Both are valid GTFS.

GTFS-Realtime

Avail's realtime feeds use the same suffixed IDs as the static feed, so they match it directly. Join realtime to static on the full ID, suffix included.

• Trip IDs: trip.trip_id in TripUpdates and VehiclePositions carries the full suffix of the version running that service day, for example t219-bD-sl1C-v64 or t2E4-b277C-sl3-v50-a2.
• Stop IDs: in a multi-agency feed, stop references use the agency's stop ID, such as 750-a2.
• Service day: start_date in TripUpdates is the service day, not the calendar date. It follows the agency's service-day boundary, so overnight trips keep their original date.
• Vehicles: in a multi-agency feed, the vehicle ID carries the agency suffix (1800-a2) and the label riders see doesn't (1800).
• Alerts: alerts target routes or a whole agency. In a multi-agency feed, each alert names the agency_id it applies to.

Each feed is served as protobuf from one endpoint. FeedLabel names the feed and FeedType names the message type. A multi-agency feed uses one label for all its agencies.

Guidance for consumers

1. Keep IDs exactly as published. Never strip or parse the -v and -a suffixes.
2. Filter trips by service date, using calendar.txt and calendar_dates.txt. A merged feed holds trips that don't run on a given day.
3. Match realtime to static on the full trip_id and stop_id, and use start_date for the service day.
4. If you check versions in code, accept hexadecimal (0–9 and A–F).

FAQ