How Do GTFS Calendar Files Determine a Trip’s Service Date?
From the earlier reference collection. Read the current software blog.
A trip’s service date comes from matching its service identifier against weekday rules and date-specific additions or removals.
Start with the trip’s service identifier
A GTFS trip refers to a service identifier. That identifier connects the trip to calendar rules; it does not by itself mean that the trip runs every day or on the date a rider boards. To decide whether a particular service date activates the trip, first find the calendar information for that identifier.
This distinction matters for overnight trips. A trip departing after midnight may still belong to the previous service date, depending on the schedule’s time convention. Establishing which service date is active is the first step before interpreting departure and arrival times.
Apply the weekday calendar
A regular calendar entry describes a date range and the weekdays on which that service operates. For example, suppose service X is active Monday through Friday from September 1 through September 30. A Tuesday within that range is a candidate service date; a Saturday is not, based on that rule alone.
The calendar is a rule, not a list of every individual trip departure. Once a candidate date matches the range and weekday, the service identifier can be considered active for that date unless a date-specific exception changes the result. GTFS defines calendar and calendar_dates files for this scheduling information. [GTFS schedule reference](https://gtfs.org/documentation/schedule/reference/)
Check date-specific changes
An exception can add service on a date that the weekday pattern would otherwise exclude, or remove it on a date the pattern would include. Suppose a holiday falls on a Tuesday. If the regular weekday rule says service X runs, but an exception removes X for that date, the trip is not active under X that Tuesday. Conversely, an added exception can make X active on an otherwise inactive date.
A reliable implementation evaluates the date-specific entry for the same service identifier and date alongside the regular calendar. It should not treat an exception for another identifier as relevant, or assume every holiday follows the same rule.
Use a clear decision sequence
For a chosen date, identify the trip’s service identifier, test the weekday rule and date range, then apply any matching addition or removal. Only after that should the app include the trip’s scheduled stop times in results.
This sequence makes debugging easier: if a departure is missing, inspect the identifier and date rules before changing time-zone display or midnight conversion. A calendar answers whether service is scheduled for a service date; the trip records answer what that service does.