Skip to content

Rail: GTFS Service Days

  • Public transport timetables in GTFS feeds, where a stop time runs past midnight and still belongs to the service day its trip began on.

A GTFS feed is a set of CSV files that describe a transit service. Its times are not clock readings. A trip that leaves at 23:40 and reaches its last stop after midnight does not restart the count at 00:00:00. The stop is written 25:35:00 and stays part of the service day the trip began on.

The functions here read that form, write it back and check it. They keep the whole days past the service day and the seconds left over as two numbers. Parse, format and validate never name a date; gtfsToInstant takes a service date and the agency’s zone and turns a time into an instant.

import { parseGtfsTime } from "@northguild/gmt/rail/parse";
import { formatGtfsTime } from "@northguild/gmt/rail/format";
import { isValidGtfsTime } from "@northguild/gmt/rail/validate";
import { gtfsToInstant } from "@northguild/gmt/rail/convert";

The functions live in @northguild/gmt/rail/parse, @northguild/gmt/rail/format, @northguild/gmt/rail/validate and @northguild/gmt/rail/convert.

The GTFS Schedule Reference defines the Time type as “Time in the HH:MM:SS format (H:MM:SS is also accepted)”. Minutes and seconds are two digits. The type is used by arrival_time, departure_time, start_pickup_drop_off_window and end_pickup_drop_off_window in stop_times.txt, by start_time and end_time in frequencies.txt, and by prior_notice_last_time and prior_notice_start_time in booking_rules.txt.

GTFS states no upper bound for the hours, so the bound is GMT’s. MobilityData’s gtfs-validator reads one, two or three hour digits, and GMT does the same, so the hours run from 0 to 999. The minutes and the seconds run from 00 to 59, and the digits are ASCII digits.

For a time after midnight on the service day, the reference says to “enter the time as a value greater than 24:00:00”, and gives 25:35:00 as “1:35AM on the next day”. Its definition of a service day says one “may exceed 24:00:00”, and gives a day that runs from 08:00:00 to 26:00:00.

Its example of blocks and service days has a trip_3 that runs from 24:00:00 to 24:55:00. The reference says it is part of the Friday service day. So 24:00:00 is the midnight at the end of the service day, and it is not the start of the next one.

parseGtfsTime(value) returns a record with two numbers. seconds is the written time less whole 24-hour blocks, from 0 to 86399, and it is not always the clock time (see below). dayOverflow is the number of whole days past the service day: 0 before 24:00:00, 1 from 24:00:00, and so on. It returns null for anything that is not a GTFS time.

import { parseGtfsTime } from "@northguild/gmt/rail/parse";
parseGtfsTime("25:35:00");
// { seconds: 5700, dayOverflow: 1 }
parseGtfsTime("8:05:00");
// { seconds: 29100, dayOverflow: 0 }
parseGtfsTime("24:00:00");
// { seconds: 0, dayOverflow: 1 }
parseGtfsTime("48:00:00");
// { seconds: 0, dayOverflow: 2 }
parseGtfsTime("1000:00:00");
// null (three hour digits at most)

The record holds the days past the service day apart from the time of day because folding them together loses one. Code that takes the hours modulo 24 turns 25:35:00 into 01:35:00, and 01:35:00 is a time at the start of a service day. The stop that belonged at the end of the night now sorts before the stops that came before it.

The library keeps both numbers, and writes them back as the same text.

import { parseGtfsTime } from "@northguild/gmt/rail/parse";
import { formatGtfsTime } from "@northguild/gmt/rail/format";
const record = parseGtfsTime("25:35:00");
// { seconds: 5700, dayOverflow: 1 }
if (record !== null) {
formatGtfsTime(record);
// "25:35:00"
}

formatGtfsTime(record) writes the form back with at least two hour digits, so 8:05:00 is written 08:05:00. It writes three hour digits when it has to: VIA Rail’s feed, for one, has a stop at 110:29:00. A record it cannot write gives "": seconds outside 0 to 86399, a negative or fractional count of days, or hours above 999.

import { formatGtfsTime } from "@northguild/gmt/rail/format";
formatGtfsTime({ seconds: 29100, dayOverflow: 0 });
// "08:05:00" (read from 8:05:00)
formatGtfsTime({ seconds: 52140, dayOverflow: 4 });
// "110:29:00"
formatGtfsTime({ seconds: 5700, dayOverflow: 0 });
// "01:35:00"
formatGtfsTime({ seconds: 5700, dayOverflow: 42 });
// "" (1009 hours)
formatGtfsTime({ seconds: 86400, dayOverflow: 0 });
// "" (a whole day belongs in dayOverflow)

isValidGtfsTime(value) reads the value the same way the parser does, so it is true exactly when the parser returns a record.

import { isValidGtfsTime } from "@northguild/gmt/rail/validate";
isValidGtfsTime("25:35:00");
// true
isValidGtfsTime("25:60:00");
// false (minute 60)
isValidGtfsTime("1000:00:00");
// false
isValidGtfsTime("25:35");
// false (no seconds)
isValidGtfsTime(" 25:35:00");
// false (a leading space)
isValidGtfsTime("");
// false

Nothing is trimmed. The reference asks that “extra spaces between fields or field names should be removed” because “many parsers consider the spaces to be part of the value”, and says a value must not hold tabs, carriage returns or new lines. It also says files with a byte-order mark are acceptable. Taking out the spaces and the mark is the job of the CSV reader that splits the row, so a stray space reaches these functions as a refusal, not as a quiet repair.

A check made for clock times does not do this job. isValidTime("25:35:00") from @northguild/gmt/plain/validate is false, because there is no 25th hour on a clock.

The reference measures the time “from ‘noon minus 12h’ of the service day (effectively midnight except for days on which daylight savings time changes occur)”. So dayOverflow × 86400 + seconds is the elapsed time from that point, and it matches the wall clock only when no clock change falls between that point and the time.

import { parseGtfsTime } from "@northguild/gmt/rail/parse";
const record = parseGtfsTime("25:35:00");
if (record !== null) {
record.dayOverflow * 86400 + record.seconds;
// 92100 (seconds from noon minus 12 h of the service day)
}

The reference defines the anchor and gives no reason for it. Our explanation is that counting from noon works because noon happens once on a clock-change day. Midnight can be missing or repeated on some days, and noon is not, in any zone that changes its clocks at night.

Every stop_times.txt value is in agency.agency_timezone, never in stop_timezone, and a feed has one agency zone. The zone is a parameter of gtfsToInstant: GMT looks up no agency, so the caller passes the zone from agency.txt.

gtfsToInstant takes the service date, the time and the zone, and returns the instant. In Berlin the clocks go forward on 29 March 2026 and back on 25 October 2026.

import { gtfsToInstant } from "@northguild/gmt/rail/convert";
gtfsToInstant("20260329", "00:00:00", "Europe/Berlin");
// "2026-03-28T22:00:00Z"
gtfsToInstant("20260329", "08:00:00", "Europe/Berlin");
// "2026-03-29T06:00:00Z"
gtfsToInstant("20261025", "00:00:00", "Europe/Berlin");
// "2026-10-24T23:00:00Z"
gtfsToInstant("20261025", "08:00:00", "Europe/Berlin");
// "2026-10-25T07:00:00Z"

Adding the time to local midnight gives a different answer on both days. In spring, local midnight of 29 March is 2026-03-28T23:00:00Z, so 08:00:00 becomes 2026-03-29T07:00:00Z, an hour later than the feed means. In autumn, local midnight of 25 October is 2026-10-24T22:00:00Z, so 08:00:00 becomes 2026-10-25T06:00:00Z, an hour earlier.

A stop time of 24 hours or more is the exact seconds elapsed from that point, not a move on the wall clock. For the service day Saturday 28 March, 26:30:00 is 26 hours 30 minutes after the anchor, which is 03:30 on Sunday in Berlin, not the 02:30 that reading it as a clock gives.

import { gtfsToInstant } from "@northguild/gmt/rail/convert";
gtfsToInstant("20260328", "26:30:00", "Europe/Berlin");
// "2026-03-29T01:30:00Z"

When the zone skipped or repeated the noon of the service date, there is no point to count from, and gtfsToInstant returns "". It has no option to choose one. Samoa skipped the whole of 30 December 2011 when it moved across the date line.

import { gtfsToInstant } from "@northguild/gmt/rail/convert";
gtfsToInstant("20111230", "08:00:00", "Pacific/Apia");
// ""

The zone can also be an offset such as +05:30, and a result after the year 9999 is returned as Temporal writes it, with an expanded year:

import { gtfsToInstant } from "@northguild/gmt/rail/convert";
gtfsToInstant("20260329", "08:00:00", "+05:30");
// "2026-03-29T02:30:00Z"
gtfsToInstant("99991231", "999:59:59", "UTC");
// "+010000-02-10T15:59:59Z"

The GTFS Service Day Clock shows both anchors for a date, a time and a zone, with the clock change marked on the day.

  • It does not pick the service days a trip runs on. That is calendar.txt and calendar_dates.txt.
  • It does not read the Local time type.
  • It does not split a CSV row. It reads one field.
  • MobilityData and Google, GTFS Schedule Reference, revised 27 April 2026: Field Types, Time and Date; Term Definitions, Service day; trips.txt, Example: Blocks and service day; stop_times.txt, frequencies.txt and booking_rules.txt; stops.txt, stop_timezone; agency.txt, agency_timezone; File Requirements.
  • MobilityData, gtfs-validator, GtfsTime.java: the source of the three-digit hour (\d{1,3}) that GMT reads.
© 2026 NorthGuild · Licences

Code examples: MIT-0. Packages: MIT. Third-party data and components: their own licences, credited where they appear. Everything else: © 2026 NorthGuild, all rights reserved.