# gtfsToInstant

Industry: Rail

:::caution[Unreleased]
Not in `@northguild/gmt` 1.21.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
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.

## 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

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

## Examples

```ts
import { gtfsToInstant } from "@northguild/gmt/rail/convert";

gtfsToInstant("20240130", "25:35:00", "America/Los_Angeles") // "2024-01-31T09:35:00Z"
```

## Source

[rail/convert/gtfsToInstant.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/rail/convert/gtfsToInstant.ts)
