# Rail

Industry: Rail

Transit agencies publish timetables as GTFS feeds. A stop time there can run past midnight, because a trip that leaves late in the evening still belongs to the day it began. This layer reads, writes and checks that time without folding it back into one day.

## What these functions solve

- **A trip after midnight lands on the wrong day.** [`parseGtfsTime`](/gmt/reference/rail/parse/parseGtfsTime/) returns the whole days past the service day and the seconds left over as two numbers, so a stop after midnight stays with the trip that reaches it. See [guide](/gmt/guides/industries/rail-gtfs-service-days/), [scenario](/gmt/scenarios/a-gtfs-time-folded-into-one-day/), [tool](/gmt/tools/gtfs-time-reader/).
- **A time written back loses its service day.** [`formatGtfsTime`](/gmt/reference/rail/format/formatGtfsTime/) writes the hours past midnight as the feed wrote them, so reading its output back gives the same day and time. See [guide](/gmt/guides/industries/rail-gtfs-service-days/), [mistakes](/gmt/mistakes/rail/).
- **A clock-time check refuses a valid stop time.** A time of day stops before midnight, and a stop time does not. [`isValidGtfsTime`](/gmt/reference/rail/validate/isValidGtfsTime/) accepts any hour the format can hold and refuses minutes or seconds out of range. See [mistakes](/gmt/mistakes/rail/), [tool](/gmt/tools/gtfs-time-reader/).
- **A stop time is anchored at midnight on a clock-change day.** A GTFS time counts from noon minus twelve hours of the service day, which is off midnight on a day the clocks change, by the size of the change, an hour in most zones. [`gtfsToInstant`](/gmt/reference/rail/convert/gtfsToInstant/) counts from that point in the agency's zone. See [guide](/gmt/guides/industries/rail-gtfs-service-days/), [scenario](/gmt/scenarios/a-gtfs-trip-anchored-at-midnight/), [tool](/gmt/tools/gtfs-service-day-clock/).
- **A stop's or a printed time is read in the wrong zone.** Rail draws on the transport layer. GTFS reads every stop time against the agency's zone, so [`gtfsToInstant`](/gmt/reference/rail/convert/gtfsToInstant/) given a stop's own zone moves the instant by the difference between the two offsets that day, an hour from Madrid to Lisbon. [`scheduleDelivery`](/gmt/reference/transport/calculate/scheduleDelivery/) reads a printed departure in the zone you name, and the timetable reader shows a repeated or skipped hour. See [mistakes](/gmt/mistakes/rail/), [tool](/gmt/tools/gtfs-trip-board/), [tool](/gmt/tools/timetable-reader/).

Start with the guide: [Rail: GTFS Service Days](/gmt/guides/industries/rail-gtfs-service-days/).

## Its own functions

### [`rail`](/gmt/reference/rail/)

**[convert](/gmt/reference/rail/convert/)**

- [`gtfsToInstant`](/gmt/reference/rail/convert/gtfsToInstant/): The UTC instant a GTFS time names on its service day in the agency's time zone.

**[format](/gmt/reference/rail/format/)**

- [`formatGtfsTime`](/gmt/reference/rail/format/formatGtfsTime/): Writes a GTFS Schedule `Time` value, keeping the days past the service day in the hour.

**[parse](/gmt/reference/rail/parse/)**

- [`parseGtfsTime`](/gmt/reference/rail/parse/parseGtfsTime/): Reads a GTFS Schedule `Time` value, keeping the days past the service day apart from the time of day.

**[validate](/gmt/reference/rail/validate/)**

- [`isValidGtfsTime`](/gmt/reference/rail/validate/isValidGtfsTime/): Checks a GTFS Schedule `Time` value, including one past `24:00:00`.

## Functions it draws on

### [`transport`](/gmt/reference/transport/)

Part of the [Transport](/gmt/industries/transport/) industry layer.

**[calculate](/gmt/reference/transport/calculate/)**

- [`bestAvailable`](/gmt/reference/transport/calculate/bestAvailable/): Pick the best available timestamp for an event from its planned, estimated, requested and actual records, and say which class it is.
- [`crossingTime`](/gmt/reference/transport/calculate/crossingTime/): Measure a crossing — a canal transit, a strait passage, a border queue — and render both ends in the zone the crossing is administered in.
- [`cutoffAt`](/gmt/reference/transport/calculate/cutoffAt/): Find a deadline stated as an offset before an anchor event, in the local time of the place that enforces it.
- [`cutoffSchedule`](/gmt/reference/transport/calculate/cutoffSchedule/): Compute a whole stack of cut-offs against one anchor event, earliest first.
- [`dwellTime`](/gmt/reference/transport/calculate/dwellTime/): Measure how long something sat somewhere, and how many local calendar days it sat there.
- [`estimateDrift`](/gmt/reference/transport/calculate/estimateDrift/): Measure how far an estimate moved between its first and last revision.
- [`nextDeparture`](/gmt/reference/transport/calculate/nextDeparture/): Find the next departure a connection can make: the first scheduled departure at or after `after` plus the minimum connection time.
- [`punctualityRate`](/gmt/reference/transport/calculate/punctualityRate/): The share of planned/actual pairs that were on time under one tolerance.
- [`scheduleDelivery`](/gmt/reference/transport/calculate/scheduleDelivery/): Chain the legs of a multi-modal move into an end-to-end ETA with zone-local times at every handoff.
- [`transitTime`](/gmt/reference/transport/calculate/transitTime/): Add a transit duration to a departure and return the arrival, in the departure's own zone.

**[compare](/gmt/reference/transport/compare/)**

- [`classifyPunctuality`](/gmt/reference/transport/compare/classifyPunctuality/): Classify an arrival as early, on time or late against the caller's tolerance.
- [`isPastCutoff`](/gmt/reference/transport/compare/isPastCutoff/): Report whether a cut-off has passed.
- [`scheduleDeviation`](/gmt/reference/transport/compare/scheduleDeviation/): Measure how far an actual time is from its plan: positive when late, negative when early.
- [`timeToCutoff`](/gmt/reference/transport/compare/timeToCutoff/): Measure the time left until a cut-off, negative once it has passed.

**[convert](/gmt/reference/transport/convert/)**

- [`etaAtZone`](/gmt/reference/transport/convert/etaAtZone/): Render an arrival instant as local time in the zone where it will be read.

## Guides

- [Rail: GTFS Service Days](/gmt/guides/industries/rail-gtfs-service-days/): Read, write and check a GTFS stop time such as 25:35:00, which runs past midnight and stays with its service day, and turn it into an instant on a service date in the agency's zone.

## Tools

- [GTFS Service Day Clock](/gmt/tools/gtfs-service-day-clock/): Type a GTFS service date, a stop time and the agency's zone. The tool turns them into the instant GTFS means with gtfsToInstant, shows the instant a midnight anchor gives next to it, and draws both on one day rail with the clock change marked.
- [GTFS Time Reader](/gmt/tools/gtfs-time-reader/): Paste a GTFS stop time, H:MM:SS with hours up to 999. The tool reads it with parseGtfsTime and isValidGtfsTime, shows the days past the service day, the same text put through a clock-time check, and writes a record back with formatGtfsTime.
- [GTFS Trip Board](/gmt/tools/gtfs-trip-board/): Paste one trip's stop_times.txt rows with each stop's zone, a service date and the agency's zone. The tool turns every time into an instant with gtfsToInstant, shows the clock on each platform, the reading a stop's own zone would give, and the length of each leg.

## Scenarios

- [A GTFS Time Folded into One Day](/gmt/scenarios/a-gtfs-time-folded-into-one-day/): A feed import folds 25:35:00 into 01:35:00, and a night trip's last stops move to the start of its service day.
- [A GTFS Trip Anchored at Midnight](/gmt/scenarios/a-gtfs-trip-anchored-at-midnight/): A feed import adds each stop time to local midnight, and on the day the clocks go forward every stop of that service day shows an hour late.

## Mistakes

- [Rail](/gmt/mistakes/rail/): Common mistakes with GTFS stop times — folding a time past midnight into one day, checking it as a clock time, writing it back, spaces and the byte-order mark, and treating seconds as a clock reading — in GMT's Rail layer.
