Clarify implied timezone for time values in stop_times.txt

[e-lo]

As a transit provider operating in multi-timezones, Amtrak needs GTFS to be more clear (and consistent) on what time zone the values in stop_times.txt refer to.

Current stop_times.arrival_time definition:

Arrival time at a specific stop for a specific trip on a route. If there are not separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.

The above definition, with use of the word "local" implies that stop_times.txt should use the time zone of the local stop. However, the stop.stop_timezone definition clearly states that if used, that stop_times shoudl refer to agency.agency_timezone.

Excerpt of current stops.stop_timezone definition:

If stop_timezone values are provided, the times in stop_times.txt should be entered as the time since midnight in the timezone specified by agency.agency_timezone.

Example Problem

Amtrak's Southwest Chief Route travels between Kingman AZ (KNG) and Needles CA (NDL):

Amtrak has implemented the following:

agency.agency_timezone is set to Eastern
stops.stop_timezone is set to Mountain for KNG and Pacific for NDL
stop_times.departure_time for KNG is specified as 12:28 AM (Mountain Time)
stop_times.arrival_time for NDL is specified as 12:26 AM (Pacific Time)

...which results in the validator giving a too-fast travel warning (See this issue in the GTFS Validator Repository

Proposed Solution

Clarify definition of arrival_time and departure_time in stop_times.txt and Time term definition as follows

Field Type: Time
Time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur) in the time zone specified by agency_timezone. in agency.txt For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.
Example: 14:30:00 for 2:30PM or 25:35:00 for 1:35AM on the next day.

stop_times.arrival_time
Arrival time at a specific stop for a specific trip on a route **in the time zone specified by agency_timezone. ** If there are not separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins....

...and ditto with departure_time

[asvechnikov2]

Hi @e-lo, thanks for bringing this up! I can confirm that Google uses agency_timezone for all stop_times times. Please let me know if I can clarify any other question you might have.

Do you think we can also propose the next change as part of this issue?

If stop_timezone values are provided, the times in stop_times.txt should must be entered as the time since midnight in the timezone specified by agency.agency_timezone.

[MartinH-open]

I'm new to GTFS and I find it weird : for me a time without date is useless and a date without timezone is useless too.
We should use only fully qualified date-time-timezone (in future GTFS versions).
With fully qualified values you can pick any timezone you want and even select it depending on local daylight saving time preferences. (see https://en.wikipedia.org/wiki/ISO_8601)

[kperkGoogle]

Thanks for the replies, all!

From the proposed solution, it is clear now that Google uses the agency timezone -- therefore from Google's end we agree that Elizabeth's proposal to better clarify the definitions is the best next step. Updating on Google's end would require more time and discussion, and we would need to leave partners like Amtrak hanging until it is done.

Are there any concerns in updating the definition? If not, I'm actually not familiar with the process here -- @e-lo are you able to make initiate that change?

[asvechnikov2]

Thanks @MartinH-open! The main problem with using times with date and timezone is the format of data, it's possible to define the same trip to run on different dates which significantly reduce amount of data. We should take a look at the ways to reduce confusions.

cc: @isabelle-dr

[e-lo]

PR Opened: #328

[derhuerst]

Conceptually, is there a reason why Google doesn't use the stop_timezone? It makes a lot of sense to use it, right?
It also cleanly handles weird exceptions like Arizona's DST handling, whereas using agency_timezone only does not.

---

cc @juliuste

[asvechnikov2]

Hi @derhuerst, I don't know why it was done this way historically. I can see some potential issues with using stop_timezone.

• Some GTFS feeds may be a concatenation (or merged version) of multiple other feeds corresponding to different agencies. Since stop_timezone is an optional field merging/concatenation must be done with some level of cautiousness to make sure that times are presented consistently.
• Another case is when a trip stops in multiple timezones and daylight saving doesn't happen simultaneously across different timezones. This means that a new trip must be created for each combination of timezones, which will also open space for misinterpretations and errors.

I think one of possible ways to get rid of such problems is to define all times using UTC, however, it's not clear how this would affect service dates. So probably operating in a context of an agency timezone isn't that bad.

[derhuerst]

• Some GTFS feeds may be a concatenation (or merged version) of multiple other feeds corresponding to different agencies. Since stop_timezone is an optional field merging/concatenation must be done with some level of cautiousness to make sure that times are presented consistently.

Can you give an example of what could go wrong in this process?

• Another case is when a trip stops in multiple timezones and daylight saving doesn't happen simultaneously across different timezones. This means that a new trip must be created for each combination of timezones, which will also open space for misinterpretations and errors.

Does it? I'd rather say the opposite: If for such a trip only agency_timezone is defined, it is hard to know which timezone to apply to each stop, as their regions do have different timezone offsets; If each stop has a stop_timezone however, it is very clear how to convert (and display to users, subsequently) the stop time to an epoch/UNIX timestamp.

I think one of possible ways to get rid of such problems is to define all times using UTC, however, it's not clear how this would affect service dates. So probably operating in a context of an agency timezone isn't that bad.

GTFS' current design has the disadvantage that agencies can't "1-to-1-map" their schedules, which AFAIK are usually planned using & defined in wall clock times, to GTFS trips & stop times; It seems like this was an explicit design goal.

Following this assumption, by changing all stop times to be in UTC, you effectively shift the interpretation/conversion problem to the producer, but don't get rid of it! GTFS producers, sometimes without IT-literate staff, will have to do this, instead of (mostly?) software/data engineers.