How Can You Build a GTFS Service-Date Checker?
From the earlier reference collection. Read the current software blog.
Build a small checker that resolves weekday service and date-specific exceptions, then lists the trips active on a chosen date.
Start with a date and the feed’s service tables
A service-date checker answers a narrow question: given a feed and a calendar date, which trip IDs are scheduled to run? In GTFS, trips refer to service IDs, while calendar rules and date-specific exceptions determine whether those services are active. The schedule reference also defines a service day as potentially extending past midnight, so the checker should avoid treating a trip’s departure clock time as the service-date rule itself.
For a first version, accept a feed archive and a date such as 2026-10-28. Read trips.txt, calendar.txt, and, when present, calendar_dates.txt. Validate that the date parses, the required columns exist, and service IDs are treated as strings; identifiers such as 0007 must not become the number 7. The GTFS reference is useful for checking the meanings and presence conditions of these tables and fields.
Resolve the base calendar rule
For each row in calendar.txt, check whether the selected date falls between start_date and end_date, inclusive. Then inspect the weekday flag corresponding to the date. For example, if the date is Wednesday, a row with Wednesday set to 1 is active only when the date also lies within the row’s range. A flag of 0 means that row does not provide base service that day.
Represent the result as a set of active service IDs. Keeping the set makes the later exception step straightforward and avoids counting multiple trips as multiple service rules. Report malformed date fields with the table name and row number instead of silently skipping them.
Apply exceptions and select trips
Next, process calendar_dates.txt for the chosen date. Exception type 1 adds the service ID to the active set; type 2 removes it. Apply these records after calculating the base calendar so an explicit exception can override the weekday pattern. If duplicate or contradictory exception rows appear, report them as a feed issue rather than choosing an undocumented winner.
Finally, scan trips.txt and select rows whose service_id is active. Print the selected date, each matching trip ID and route ID, and a total. If no trips match, say so plainly; that result can mean there is no scheduled service or that the feed is incomplete.
Make the result auditable
A useful checker distinguishes an empty result from a parsing failure. Include counts for active service IDs and matched trips, and send errors to a nonzero exit status when required files or columns are missing. Keep the program read-only: it should explain what the supplied feed says, not modify it.
For example, a weekday rule may activate WKD, while an exception for the selected date removes WKD and adds EVENT. The trip listing then includes EVENT trips and excludes WKD trips. This small example is also a good fixture for manual checking. Once the rule order is clear, add tests for range boundaries, weekdays, exceptions, and dates absent from both calendar tables.