# GTFS Time Reader

Industry: Rail

**Key point — Transit stop times**

A GTFS stop time can run past 24:00:00. `25:35:00` is not an error: it is 1 day past the service day, 01:35:00, and still part of the same service day. A clock-time check refuses it, and a fold into one day loses the day.

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`](/gmt/reference/rail/parse/parseGtfsTime/) returns the days past the service day and the seconds left over, or `null` when the text is not one, and [`isValidGtfsTime`](/gmt/reference/rail/validate/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`](/gmt/reference/rail/format/formatGtfsTime/).

**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`](/gmt/reference/rail/convert/gtfsToInstant/) turns a record into an instant, given the service date and the agency's zone, and the [GTFS Service Day Clock](/gmt/tools/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`](/gmt/reference/plain/validate/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.

```ts
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](/gmt/tools/gtfs-service-day-clock/?w=gtfsday&wa=%7B%22preset%22%3A%22past-midnight%22%7D); [a stop after midnight](/gmt/tools/gtfs-time-reader/?w=gtfstime&wa=%7B%22preset%22%3A%22next-day%22%7D) is valid and a day past the service day; [minute 60](/gmt/tools/gtfs-time-reader/?w=gtfstime&wa=%7B%22preset%22%3A%22bad-minute%22%7D) is refused; and [four hour digits](/gmt/tools/gtfs-time-reader/?w=gtfstime&wa=%7B%22preset%22%3A%22four-digits%22%7D) are refused too, because hours stop at 999. The guide is [Rail: GTFS service days](/gmt/guides/industries/rail-gtfs-service-days/), the story is [a GTFS time folded into one day](/gmt/scenarios/a-gtfs-time-folded-into-one-day/), and the pitfalls are in [Rail mistakes](/gmt/mistakes/rail/).
