How Do You Document a GTFS Feed’s Service Range?
From the earlier reference collection. Read the current software blog.
A feed’s service range is best described as dates with scheduled service, alongside exceptions and the caveat that calendar coverage alone does not prove every trip runs.
State the date span and its source
Give the first and last dates covered by the service calendars, using an unambiguous format such as YYYY-MM-DD. Say what those dates mean: they are the boundaries declared in the feed’s schedule data, not a promise that a particular route runs every day in that span. If you calculate the range from calendar and exception records, explain that method briefly and identify the feed version or retrieval date.
Avoid describing the range as simply “valid through June” when the exact date is available. A reader planning travel needs to know whether a service day applies on the day in question. If there are multiple calendars with different boundaries, report the overall range and point out important route- or service-specific differences rather than flattening them into a universal claim.
Explain exceptions and service days
A date span can include days with no service or days where exceptions alter the usual weekly pattern. Describe relevant added or removed service dates, holidays, seasonal schedules, or calendar exceptions present in the feed. Make clear whether the note reflects what the feed declares or whether it has been checked against a separate agency notice. Do not imply a feed includes an exception that is absent from its files.
Service-day times can extend beyond midnight. The GTFS reference defines a service day as an agency-specific period that may not match a calendar day, and scheduled times can exceed 24:00:00 for trips continuing after midnight. This matters when a trip shown as 25:10 belongs to the preceding service day. [GTFS schedule reference](https://gtfs.org/documentation/schedule/reference/)
Make the practical limits explicit
Tell readers what the range cannot establish. It does not by itself confirm that a trip is operating in real time, that the schedule is current with every announced detour, or that every stop and route has service each date. If a calendar has an end date in the past, show that clearly and state when the feed was last retrieved. If a future date falls outside the declared range, tell users that the feed offers no scheduled coverage for it rather than presenting an empty itinerary as proof that no transit exists.
A helpful summary might read: “This feed declares scheduled service from September 1 through December 14, 2026. Calendar exceptions add service on October 12 and remove it on November 26. Dates describe feed coverage; consult agency notices for later changes.” Use actual dates only when they have been calculated from the current feed. Link to the underlying dataset so developers can inspect the calendars and exceptions themselves.