gtfsToInstant
Signature
Section titled “Signature”gtfsToInstant(serviceDate: string, gtfsTime: string, timeZone: string): stringThe 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:00on 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:00is elapsed time from that anchor, not a wall-clock move. A later clock change therefore shifts its local reading:26:30:00on 2024-03-09 in New York is 03:30 EDT, and25:30:00and26:30:00on 2024-11-02 both read 01:30, an hour apart. serviceDateis a GTFSDate(YYYYMMDD). GMT’s plain-date formYYYY-MM-DDis read too, with a four-digit year only, as a GTFS date has.timeZoneisagency.agency_timezone, even for a stop that has its ownstop_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.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
serviceDate | string | A GTFS service day, such as a calendar_dates.txt date: YYYYMMDD or YYYY-MM-DD |
gtfsTime | string | A GTFS Time, such as stop_times.txt arrival_time, as parseGtfsTime reads it: H:MM:SS to 999:59:59 |
timeZone | string | The feed’s agency.agency_timezone |
Returns
Section titled “Returns”The UTC instant ending in "Z", or "" on invalid input
Examples
Section titled “Examples”import { gtfsToInstant } from "@northguild/gmt/rail/convert";
gtfsToInstant("20240130", "25:35:00", "America/Los_Angeles") // "2024-01-31T09:35:00Z"Source
Section titled “Source”© 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.