Rail: GTFS Service Days
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 time form
Section titled “The GTFS time form”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.
Times past midnight
Section titled “Times past midnight”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.
Reading
Section titled “Reading”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)Why the overflow is kept apart
Section titled “Why the overflow is kept apart”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"}Writing a time back
Section titled “Writing a time back”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)Checking a value
Section titled “Checking a value”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");// trueisValidGtfsTime("25:60:00");// false (minute 60)isValidGtfsTime("1000:00:00");// falseisValidGtfsTime("25:35");// false (no seconds)isValidGtfsTime(" 25:35:00");// false (a leading space)isValidGtfsTime("");// falseNothing 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.
From a record to an instant
Section titled “From a record to an instant”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)}Noon minus 12 hours
Section titled “Noon minus 12 hours”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.
The agency’s zone
Section titled “The agency’s zone”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.
The two clock-change days
Section titled “The two clock-change days”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.
More than a day of seconds
Section titled “More than a day of seconds”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"No anchor
Section titled “No anchor”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.
What this layer does not do
Section titled “What this layer does not do”- It does not pick the service days a trip runs on. That is
calendar.txtandcalendar_dates.txt. - It does not read the
Local timetype. - It does not split a CSV row. It reads one field.
See it break, then work
Section titled “See it break, then work”- A GTFS Time Folded into One Day
- A GTFS Trip Anchored at Midnight
- Rail mistakes
- GTFS Time Reader, a tool that reads, checks, folds and writes a GTFS time
- GTFS Service Day Clock, a tool that shows the instant GTFS means beside the answer from local midnight
- GTFS Trip Board, a tool that reads a whole trip and shows what each stop’s own zone gets wrong
Sources
Section titled “Sources”- 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.txtandbooking_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.