Skip to content

GTFS Time Reader

  • 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 arrival_time or departure_time is H:MM:SS, counted from the start of the service day, so a trip that runs through midnight keeps counting. Paste one and the tool says what it reads as. parseGtfsTime returns the days past the service day and the seconds left over, or null when the text is not one, and isValidGtfsTime says whether it is. Everything on the page is what those calls returned. A second section puts the same text through a clock-time check and a fold into one day, and a last section goes the other way with formatGtfsTime.

1. Read a GTFS time

25:35:00 is 01:35, one day past the service day.

Less whole days
nothing typed
formatGtfsTime
Days past the service day
nothing typed
parseGtfsTime

Type a GTFS time, such as 25:35:00, to read it.

Record: nothing typed

Written back: nothing typed

Type a GTFS time, such as 25:35:00.

The pair counts from noon minus 12 hours of the service day, so a clock time needs the date and the agency's zone. gtfsToInstant does that, and the GTFS Service Day Clock shows it.

2. Folded into one day

This is what code that does not know GTFS does with the same text: a clock-time check, then the time with the days dropped.

Clock-time check
nothing typed
isValidTime
Folded to
nothing typed
formatGtfsTime

Type a GTFS time above to fold it.

3. Write a GTFS time

Written back as the time you started with.

GTFS writes
nothing typed
formatGtfsTime
Reads back as
nothing typed
parseGtfsTime

Type the seconds and the days past the service day.

A record, not a date. The library returns a count of days past the service day and the seconds left over, which are not always the clock time. It never names a date, because the start of a service day is set by the agency and its zone. gtfsToInstant turns a record into an instant, given the service date and the agency’s zone, and the GTFS Service Day Clock shows it beside the answer you get from adding the time to local midnight. The note under the first section says the same.

The fold. The second section asks isValidTime about the same text and then writes the seconds with the days dropped. A reader that does that agrees with GTFS for every time before 24:00:00 and loses a whole day for every time after it.

Refusals. The library gives no reason, so the tool asks again. Spaces around the value are tried first, because GTFS asks the feed to remove them and the reader does not. A text that is exactly one of the presets names its own reason, such as minutes of 60, four hour digits, a missing seconds field, a sign or a fraction. Any other refused text gets the shape rule.

Writing a record. formatGtfsTime writes two hour digits below 100 and refuses a record it cannot write. The tool says whether the days, the seconds or the hours are the cause by asking the library about the same record with the other part set to zero.

import { parseGtfsTime } from "@northguild/gmt/rail/parse";
import { formatGtfsTime } from "@northguild/gmt/rail/format";
import { isValidGtfsTime } from "@northguild/gmt/rail/validate";
import { isValidTime } from "@northguild/gmt/plain/validate";
parseGtfsTime("25:35:00"); // { seconds: 5700, dayOverflow: 1 }
parseGtfsTime("9:05:00"); // { seconds: 32700, dayOverflow: 0 }
parseGtfsTime("24:60:00"); // null
isValidGtfsTime("25:35:00"); // true
isValidTime("25:35:00"); // false
formatGtfsTime({ seconds: 5700, dayOverflow: 1 }); // "25:35:00"
formatGtfsTime({ seconds: 100, dayOverflow: 42 }); // ""

Worth trying: the clock on 28 March in Berlin with 26:30:00; a stop after midnight is valid and a day past the service day; minute 60 is refused; and four hour digits are refused too, because hours stop at 999. The guide is Rail: GTFS service days, the story is a GTFS time folded into one day, and the pitfalls are in Rail mistakes.

© 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.