Skip to content

gtfsToInstant

  • Public transport timetables in GTFS feeds, where a stop time runs past midnight and still belongs to the service day its trip began on.
gtfsToInstant(serviceDate: string, gtfsTime: string, timeZone: string): string

The UTC instant a GTFS time names on its service day in the agency’s time zone.

  • A GTFS time is measured from “noon minus 12 hours” of the service day. That is midnight except on a day the clocks change, so 00:00:00 on a spring-forward day is 23:00 the day before, and the result can fall on another local date. The reference gives no reason for noon; it works because clocks change at night, so noon occurs once. Anchoring on local midnight would bring back the bug the definition avoids.
  • A time past 24:00:00 is elapsed time from that anchor, not a wall-clock move. A later clock change therefore shifts its local reading: 26:30:00 on 2024-03-09 in New York is 03:30 EDT, and 25:30:00 and 26:30:00 on 2024-11-02 both read 01:30, an hour apart.
  • serviceDate is a GTFS Date (YYYYMMDD). GMT’s plain-date form YYYY-MM-DD is read too, with a four-digit year only, as a GTFS date has.
  • timeZone is agency.agency_timezone, even for a stop that has its own stop_timezone. An IANA name is expected; a numeric offset is read as well.
  • A result outside years 0000 to 9999 is written with Temporal’s expanded year (+010000-02-10T15:59:59Z), not returned as "".
  • Nothing is trimmed: a space, tab, newline or byte order mark returns "".
  • Returns "" on invalid input. Disambiguation: the one local time this resolves is noon on the service date, with "reject": a noon the zone skipped (nonexistent) or repeated (ambiguous) returns "". The GTFS time itself is never resolved as a wall time; it is exact seconds after the anchor, so it is never ambiguous or nonexistent. Source: GTFS Schedule Reference § Field Types, Time and Date; § stop_times.txt arrival_time.
ParameterTypeDescription
serviceDatestringA GTFS service day, such as a calendar_dates.txt date: YYYYMMDD or YYYY-MM-DD
gtfsTimestringA GTFS Time, such as stop_times.txt arrival_time, as parseGtfsTime reads it: H:MM:SS to 999:59:59
timeZonestringThe feed’s agency.agency_timezone

The UTC instant ending in "Z", or "" on invalid input

import { gtfsToInstant } from "@northguild/gmt/rail/convert";
gtfsToInstant("20240130", "25:35:00", "America/Los_Angeles") // "2024-01-31T09:35:00Z"
output 

rail/convert/gtfsToInstant.ts

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