"Direction names" in GTFS

[timMillet]

For the last update (2020-11-20) on the issue, please go to this comment.

---

Hi everyone,

I’m opening an issue regarding “direction names” (also called “directions”, “route directions”, “direction destinations”, or “direction headsigns”) as some GTFS stakeholders already provide and consume these data. Before making any specification proposal, I would appreciate having your input on:

1. If you would like these data to be officially adopted in the GTFS specification.
2. On how these data should be modeled.
3. On the name you would give to these "direction names".

The needs are:

• Providing riders with more detailed information on directions, especially for routes with complex trip patterns (e.g: routes with branches). The direction name would be a piece of information complementary to the trip_headsign and/or stop_headsign.
• Being defined per route at the trip level, at the direction level (trips.direction_id), and/or at the stop_time level. The use cases would be:
  • trip and direction levels: defining a direction that is true for all trips going to the same direction at all their stop_times (e.g with the Red Line in Boston: direction “Southbound” for trips heading either to “Ashmont” or to “Braintree”)
  • stop_time level: defining a direction that is true for all trips going to the same direction at that particular stop_time (e.g: direction “Inbound” until the first downtown stop is reached, then “Outbound”)
• Being compatible with all king of general directions (e.g: “South”, “Southbound”, “Inbound”, “Clockwise”, “Loop”, “Intérieur”, “Sud vers Paris”, “T-Centralen”, “Fruängen/Norsborg”).

The current implementations are (Gdoc with more details):

• 1 new file with 3 to 4 fields: MBTA, MTC (SF Bay Area), Trillium, TriMet
• 2 new fields in already-existing files: Transit

Thank you for all your feedback!

[laurentg]

Added a small comment in the Gdoc for Mecatran implementation and support.

We would be generally in favor of specifying (even if non-formal) at least direction per route/direction level (two directions names per route), as many feeds do produce such information but many different standards co-exist at the moment.

[gcamp]

Even if it's not our current implementation, I would suggest using the directions.txt file.

For places that would change direction name during their trip, I would suggest using block_id to link together two splitted trips that each have their direction. Imagine for CTA's 'L' loop, the trip could be split in two in the middle of the loop to show the change of direction.

[stevenmwhite]

I don't think that splitting trips is something that would be acceptable to most agencies, even if it doesn't technically change the experience of the feed. I'd advise trying to approach this similarly to the way that headsign overrides are used.

In our experience, agencies that change direction name during a trip also change the headsign. This is common for routes that go through a downtown or center city area and the headsign and direction will be something like the following:

• First half of the trip: Headsign "Route 1, Westside via Downtown" and direction "Inbound"
• Second half of the trip: Headsign "Route 1, Westside" and direction "Outbound"

It's very clearly a single trip that starts on the Eastside and goes to the Westside, through Downtown on the way.

From a headsign standpoint, this is handled well in GTFS already with trips.trip_headsign and stop_times.stop_headsign and I'd like to see us approach mid-trip direction changes in a similar way.

@gcamp This seems fairly similar to the extended way you're already handling this, but to utilize a new directions.txt file we'd need to allow stop_times to indicate a new override for direction_id.

(Point of order... should comments be here, on the Google doc, or both?)

[jamespfennell]

Just want to chime in with the New York City subway example. The NYC Subway doesn't have any additional route directions defined in the GTFS feed, but does provide an auxiliary CSV file that provides direction names on a per stop level. The CSV file is here.

For example, at the Port Authority station (stop ID A27), northbound trains (direction ID = false) have direction name "Uptown - Queens" and southbound trains (direction ID = true) "Downtown & Brooklyn". I use these directions to create stop headsigns for additional trips, as the realtime feed doesn't provide these.

Probably this case of "direction names" is a totally different problem to this ticket however if it is decided to add a new file to the GTFS Static spec, it might be good to call it route_directions.txt rather than directions.txt, in order to allow future non-route direction name features to be added.

[gcamp]

@gcamp This seems fairly similar to the extended way you're already handling this, but to utilize a new directions.txt file we'd need to allow stop_times to indicate a new override for direction_id.

If we do this we would need to accept more than 0 and 1 as direction_id, because in the example mentioned it would be 4 direction names.

Probably this case of "direction names" is a totally different problem to this ticket however

I don't think this is a different use case, and it's exactly the way we use stop_direction_headsign in our app. If there are important enough use cases to warrant a separate text value in stop_times then it maybe it is the best way to do it.

[stevenmwhite]

If we do this we would need to accept more than 0 and 1 as direction_id, because in the example mentioned it would be 4 direction names.

Good point. I had originally written something saying that route_id + direction_id wouldn't be a reasonable unique key in this case, and then edited that out of my previous comment forgetting that direction_id is currently only 0 or 1.

[timMillet]

Thank you everybody for your feedback!

I’m trying to synthesize what have been said so far (please tell me if I’m wrong or anything):

• Everybody who commented would be in favor of adding direction names to the specification.
• It makes sense to define direction names per route and trips.direction_id.
• It would be useful if direction names could also be defined at the stop_time level.
• A new .txt file can be created for this purpose, and its name should contain “route” if direction names are defined for routes only.

Based on this feedback, MobilityData drafted 4 options for a GTFS proposal. You can view these options in section 4 of this Gdoc.

• The first 2 options are directly adapted from the current implementations
  • Option A is Transit’s
  • Option B is a merge of MBTA’s, MTC’s, Trillium’s, and TriMet’s solutions
• The last 2 options are “improved” versions of the options above, both suggesting a new .txt file and allowing the definition of direction names at the stop_time level.
  • Option C with a new stop_times.stop_direction_id
  • Option D with direction_name_ids defined at the trip and/or stop_time level

Do you have a favorite option? Which option would be best to suit your needs? Would you have any other modeling solutions in mind?

You may comment on this issue or directly in the Gdoc. Thank you!

[gcamp]

I think option C and D are both better than the existing ones.

Both would work with us but I'm curious of what other thinks of stop_direction_id. It's something we already have internal but might be a big hurdle to add for other consumers.

[stevenmwhite]

I find Option D to be the most flexible, particularly because that it provides multiples names per direction_id per route. I also like the fact that the same name can be used multiple times, so only one line of data is required no matter how many trips and/or stop times that use "West" as the direction.

While direction_id makes sense as a binary value from a data perspective -- within a route there's generally only two opposite directions -- the ability to define multiple qualitative names for different trips is important.

This is particularly true for partial trips (short lines) where the direction might be "West" even when the full trip's direction is "Southwest" because the route continues in a southern direction after going west.

[timMillet]

@laurentg, @jamespfennell As you participated previously in the conversation, would you have any opinion concerning the 4 modelization options? Or anyone else?

[skinkie]

In the spirit of GTFS option A would fit best, because all the other options introduce normalisation which is not found in GTFS.

[Bertware]

I would lean towards option A or D, as they follow the same principle as the current headsigns or stop_times.shapes_id.

However, I'm wondering what the exact difference is between trip_headsign and trip_direction_headsign? How would a data consumers show this data? I see the Stockholm metro lines being named, but aren't these already covered by the normal headsigns, given that they use the final station as a headsign/direction? I'm in favour of direction headsigns since there definitely seems to be a need for in cases where there are nortbound/southbound lines, but i feel like we could improve the specification of what should go in trip_headsign, direction_headsign, and what one should do when these are identical (should one be left out, or should consumers handle this if they don't want to show the same data twice).

[gcamp]

@Bertware this is how we use the direction name at Transit. "Southbound" is a trip_direction_headsign. "Ashmont" and "Braintree" are trip_headsign. "Downtown Crossing" is the stop name.

[skinkie]

@gcamp you might just have proved this is an anti-feature. Because it is used at stop level rather than stop_time level.

[brodyFlannigan]

In the spirit of GTFS option A would fit best, because all the other options introduce normalisation which is not found in GTFS.

@skinkie from my understanding of your comment, you would prefer option A as it does not include new IDs and new files. Is my understanding correct?

[skinkie]

@dudebrains01 given the current design of GTFS, that is correct.

[stevenmwhite]

It seems like most of the comments between this discussion and the Google Doc are leaning towards A or D, so I'll try to summarize the similarities or differences.

Common Benefits:

• Both allow multiple direction names for a single trip
• Direction names can be identified at the stop time level
• Direction names are text fields that can be defined by an agency (as opposed to a limited set of enumerated values)
• Both allow custom extensions for MTC/MBTA/Tri-Met to continue as-is

Benefits of A over D:

• Some consumers/producers already do this
• Extending existing files, not adding new ones
• Clearly fits within the existing structure of GTFS

Benefits of D over A:

• Potentially smaller file sizes overall as the full name doesn't need to be repeated
• May potentially be extended to entities other than routes/trips (like pathways), though this is undefined

---

With the above summary, we'd be happy to support either of these two options and could commit to being an early adopter on the producer side for all of our customer agencies as soon as we see a clear signal which way it's going to go.

One thing I might note on Option A is that the actual name of the column trip_direction_headsign is perhaps a little confusing in context next to trip_headsign and it would be more clear if it was something like trip_direction_name or trip_direction_text (the direction text may not always be on the headsign, and the headsign label is better used specifically for the actual text a rider sees as the vehicle is approaching).

[skinkie]

Potentially smaller file sizes overall as the full name doesn't need to be repeated

With all GTFS files being zipped, I have my doubts on this benefit.

[stevenmwhite]

With all GTFS files being zipped, I have my doubts on this benefit.

I agree -- at the end of the day I don't think the file size is a major issue with these additions even if it does make a relatively significant difference between the two.

[sam-hickey-arcadis]

Our preference is a revised version of Option C that adds Option A to it (more on this below). The main shortcoming we see with Options A and D is there is not a way for a producer to unambiguously define for each route only one direction name for direction_id = 0 and only one direction name for direction_id = 1. This goes back to one of the needs noted in the first post in this issue:

trip and direction levels: defining a direction that is true for all trips going to the same direction at all their stop_times (e.g with the Red Line in Boston: direction “Southbound” for trips heading either to “Ashmont” or to “Braintree”)

We think it’s important for producers to have the ability to define their preferred direction name for each of the two direction_id values. Without this, it will be up to consumers to decide on their own the direction name to associate with a direction_id based on possibly two or more direction names associated with trips that share the same direction_id.

We also see the value in providing the ability to define direction name at the trip and stop level.

We would revise Option C as follows:

1. Replace stop_direction_id in stops_times.txt as proposed in Option C with stop_direction_headsign from Option A but rename this to stop_direction_name
2. Remove stop_direction_id in route_directions.txt as proposed in Option C
3. Add the extension to trips.txt from Option A but rename this field to trip_direction_name

Option C-modified would then consist of the following:

1. route_directions.txt (added; same as Option C but with stop_direction_id removed)
2. trips.txt (extended; same as Option A but field renamed to trip_direction_name)
3. stop_timex.txt (extended; same as Option A but field renamed to stop_direction_name)

This Option C-modified would then allows producers to define one direction name for each route_id-direction_id combination and also override this direction name at the trip and/or stop time level.

[stevenmwhite]

there is not a way for a producer to unambiguously define for each route only one direction name for direction_id = 0 and only one direction name for direction_id = 1

Wouldn't this simply be done by defining the trip_direction_headsign in the same manner for all trips on the route with the same direction_id? Theoretically the same issue exists for headsigns currently but as far as I know that hasn't been a problem. If there's only one headsign per direction, then the headsign values are just the same for each trip.

It seems that including the ability to define at the route and trip and stop time level adds unnecessary complexity because if it's defined at a lower level you don't need to define it at the higher level. (Yes, you could say the same thing about just trip and stop time, but since this model is already well established in GTFS I don't think we should change it.)

[sam-hickey-arcadis]

Wouldn't this simply be done by defining the trip_direction_headsign in the same manner for all trips on the route with the same direction_id? Theoretically the same issue exists for headsigns currently but as far as I know that hasn't been a problem. If there's only one headsign per direction, then the headsign values are just the same for each trip.

Yes, a producer could define the trip_direction_headsign in the same manner for all trips for a route_id-direction_id combination, but this will not always be the case as Options A and D allow producers to define more than one direction name for a route_id-direction_id combination. So perhaps a better way to say that quoted portion of our post is that the main shortcoming we see with Options A and D is consumers are not guaranteed to be able to unambiguously determine the preferred direction name to associate with a route_id-direction_id combination.

[stevenmwhite]

consumers are not guaranteed to be able to unambiguously determine the preferred direction name to associate with a route_id-direction_id combination

My understanding of the proposals and the goals so far is that this "is a feature, not a bug." Agencies don't always define direction names per route... they often define them per trip or per portion of trip (stop time), so the idea is that we don't want consumers to associate this data on a route basis.

[brodyFlannigan]

A PR (#242) has been opened to introduce GTFS-DirectionNames to the specification.

[timMillet]

The PR (#242) has been closed. MobilityData will suggest soon in this issue:

• a modelization for the solution C-modified, as proposed by IBI-Group.
• a modelization for a solution D-modified with only one trips.direction_name defined per combination of route_id and direction_id.

[timMillet]

Hi everyone! Thanks again for all your comments!

I’m trying to synthesize what has been said since my comment from last month (please tell me if I forgot anything):

• Nobody who commented would be in favor of option B.
• Options A and D are the most popular so far.
• Like option C, there should be a way to assign without ambiguity a direction name per (route_id, direction_id) pair. Options A and D do not offer this possibility.
• In option A, direction headsigns should be renamed direction names to prevent confusion with the current trip_headsign and stop_headsign.
• Some guidance should be provided to show the difference between direction names and headsigns.

Following all this feedback, here are 3 new options for this proposal:

• Option E is based on @sam-hickey-ibigroup ’s idea for an “option C-modified”, as a combination of options A and C.
• Option A2 and option D2 are respectively the options A and D with a single major change: the addition of a rule for defining only one trip_direction_name per (route_id, direction_id) pair.

Also, the examples are rephrased in the options E, A2, D2, in order to make the difference between direction names and headsigns clearer. In the same way, some Best Practices are added.

Do these new options change your previous choice? From all these options, what would be your favorite one, and the ones you would agree with even though they are not your favorite?

Thank you!

[stevenmwhite]

I believe one of the strengths of the previous proposals (over similar existing options like that used by MTC today) was that it allowed more than one direction name per direction, so I'd take issue with the new rules added to A and D in A2 and D2 that require only a single name per direction type.

In the same way that the headsign may change on a short-line trip, so may the direction name. We're currently working with a few customers who have expressed specific interest in this when using "Inbound/Outbound" directions... For example:

• Route A starts on the eastern edge of the city, passes through downtown and ends on the western edge of the city: -- Trip 1 direction ID of 0 with a name of "Inbound" -- Stop times in the second half of Trip 1 have an override with direction name "Outbound" after it passes through downtown.
• During the evening rush, some of the trips start downtown and provide service only on the second half of the route heading west -- Trip 2, one of these trips, has a direction ID of 0 with a name of "Outbound"

This would be against the new rules, and it seems that by requiring uniqueness per route and direction id this is not longer relevant to trips.

Therefore I advocate for removing the rule added in option A2 and D2.

[timMillet]

Thanks @stevenmwhite for your feedback!

In option E, the route_directions.route_direction_name can be overridden by trips.trip_direction_name and stop_times.stop_direction_name. Would this option work for you? Following your example:

• Route A with direction_id=0would have route_direction_name=Inbound;
• trip 1 would have thestop_direction_names not populated for the first stop_times, then stop_direction_name=Outbound for the stop_times from downtown to the terminus;
• trip 2 would have trip_direction_name=Outbound.

[stevenmwhite]

@timMillet Technically, yes that would work for what I'm describing.

However, it seems convoluted and like a lot of added complexity. Why add an entire new file and define directions at the route level in that file and also extend two existing files to define directions at the trip level and the stop time level? This seems really overdone and duplicative when Options A and D as they previously existed both provide all of the relevant information.

Perhaps I'm not understanding the importance of defining a single, specific direction text per route direction? Can someone (perhaps IBI, which as far as I can tell is the only organization pushing for this option) explain that to me? I don't want my ignorance to get in the way of an important use case if it exists.

[antrim]

Here's some perspective from @Trillium-Solutions. Note: Until recently I've been a member of the @MobilityData team. I'm back with Trillium and will be representing Trillium (and our transit agency and DOT clients) in this forum.

1. If you would like these data to be officially adopted in the GTFS specification.

We support adding direction names in GTFS.

2. On how these data should be modeled.
3. On the name you would give to these "direction names".

Option D is appealing because because it provides flexibility and also follows a consistent structure. However, we really don't have a strong position about the structure. Whatever works…

Requests and comments from Trillium:

• We recommend either defining that only two directions are allowed per route (at the trip level), or at least making this highly recommended. I tried looking for examples of more than two directions being used in traveler-facing information on a route and didn't turn anything up after a short search (note the search was not exhaustive). Does anyone have examples of more than two directions per route?
• We suggest adding guidance with regard to matching timetables -- should direction names always be supplied if they are on timetables? Timetables are where we most often see "North", "South", etc. Those directions may or may not appear on vehicle and other signage.
• Timetable generation is another potential use for direction information in GTFS. The GTFS-to-HTML software consumes direction name in timetables.txt, which is currently supplied in many Trillium feeds.
• It would be great to involve the MTC in this conversation because directions are currently defined within the GTFS+ "Extended" spec. We hope for a unified spec.
• Below are screenshots that show a similar trip on Redwood Transit in Google Maps and Transit. The headsign is "HSU (Northbound)". Note that Transit is parsing this text to show it in a way that's consistent with their UI. We do think it will be useful to break out direction and destination so that presentation can work better in a variety of UIs.

[timMillet]

@stevenmwhite I totally agree Option E is repetitive. @sam-hickey-ibigroup mentioned that a strict definition (only one direction name per route and direction_id) allows the data consumer to unambiguously determine the preferred direction name to associate with a representation of a route-direction (e.g: on a timetable, on an app view). That’s something that does not exist for headsigns, but that could be useful. Maybe data consumers (@gcamp or anyone else) could tell us if it is something that will be actually useful?

---

@sam-hickey-ibigroup Would you see any other reasons why a strict definition (only one direction name per route and direction_id) would be useful? Also, does option E fit with your needs? Would you agree with other options even though they are not your favorite one?

---

@antrim Thanks for Trillium’s feedback on this issue. Here are answers to some questions/comments you expressed:

Does anyone have examples of more than two directions per route?

I do have an example of a route that has more than 2 directions. The RER C in Paris has 3 directions: Nord, Ouest, and Sud. The directions Nord and Ouest could be combined in Nord et Ouest but that wouldn’t be true once the stop Champs de Mars Tour Eiffel is passed. NB: last-stop names are also used (as headsigns) to indicate the destination, e.g: “Nord vers Pontoise”.

We suggest adding guidance with regard to matching timetables -- should direction names always be supplied if they are on timetables? [...] Those directions may or may not appear on vehicle and other signage.

1. IMHO, to facilitate the rider comprehension, the wayfinding system used by the agency should be consistent throughout each medium of communication (e.g: maps, timetables, signage, vehicle headsign, GTFS data). If there is a distortion throughout its wayfinding system, I think the agency should first evaluate if it’s worth it.

2. Otherwise, I’d tend to say that more information is better than less information, so I’d include these timetable directions into the dataset.

If nobody is against these 2 ideas, I’d add that guidance to the section “Best Practices”.

It would be great to involve the MTC in this conversation because directions are currently defined within the GTFS+ "Extended" spec. We hope for a unified spec..

Good idea. I’m contacting someone from the MTC. Please do not hesitate (Aaron or anyone else) to do so too, if you have contacts there.

[jewel1965]

I am coming into this conversation late. I tried to absorb as much as my brain would allow, but I am sure I missed something. So, if my comments seems redundant, please ignore.

My understanding of the purpose of direction_id in the trips.txt file is grouping trips into one or two distinct directions of the route. When we developed the directions.txt file, our goals included, 1) maintaining route direction names that the public is familiar with, 2) organize timetable under route direction names instead of meaningless binary 0/1 values, and 3) accomplish it without changing the GTFS spec for trips.txt. Only reasonable solution at that time seemed to be an extra file, directions.txt. But, i am not married to that. We always wondered why the trips.direction_id field couldn't have been an enumeration under a field name trips.direction. I still believe that the purpose of trips.direction_id can be fulfilled with an enumeration field, trips.direction (name). If and when the direction changes in the middle of a trip, a field in stop_times.txt similar to the stop_times.stop_headsign can be used, naming it something like stop_times.stop_direction.

I believe this idea has been captured in option A2, except that the option adds a new field in trips.txt. I guess adding a new field makes sense because that would avoid any disruption to existing use of trips.direction_id. Maybe trips.direction_id field can be deprecated over time as the data consumers gradually moves over to the new field trips.direction.

--Nisar Ahmed, 511 SF Bay

[sam-hickey-arcadis]

Taking a step back, here are two principles that are guiding our stance on this:

(1) direction_id has two allowed values, so it makes sense to have one unique name assigned to each.

(2) allow simple cases to be implemented in a simple way while allowing for more complex implementations.

Answering questions from @timMillet first: The two use cases of timetables and app views are good examples of why we’re in favor of a strict definition of only one direction name per route_id and direction_id. Other examples like this don’t come to mind immediately, but this strict definition is important for any case where there is a need to group all trips with the same direction_id with a label.

While we may be ok with options A2 and D2, both are quite verbose for what we see as the most common scenario where an agency has one unique direction name per route_id and direction_id (in A2 and D2, producers would need to repeat the same trip_direction_name or direction_name_id for every row for the same route_id and direction_id in trips.txt). On the other hand, Option E allows this assignment of direction name with just one row in a new route_directions.txt file.

Although Option E may come across as complex, it will lead to complex implementations only for complex cases. For the simple case of one direction name per route_id and direction_id, the fields trip_direction_name and stop_direction_name do not need to be used.

It would be great to get input from more producers and consumers as well.

[stevenmwhite]

I agree with point 2:

(2) allow simple cases to be implemented in a simple way while allowing for more complex implementations.

In that regard, option E doesn't concern me all that much, but at the same time I don't think the verbosity of options A2/D2 should be much of a concern. It's easy for software to duplicate a field on many rows. I would generally release my concerns about the complexity of the format and say I'm ok with either option in that regard.

On point 1, however, I do not agree with the premise:

(1) direction_id has two allowed values, so it makes sense to have one unique name assigned to each.

The documentation for trips.direction ID currently states

it provides a way to separate trips by direction when publishing time tables.

With that ID, you're able to separate trips into two timetables if you need to. But each timetable does not necessarily need to have a single name. This seems like prescribing a way to describe service for an agency, rather than modeling the way that an agency already describe their service.

As far as I can tell in the RER-C example that @timMillet posted earlier, timetables don't use labels for the directions at all, but that the trains headed west are all combined into a single section. I can't see how forcing these to also share a direction name with northbound trains would be helpful.

A simpler example may be a bi-directional loop. A good example from a customer of ours is Key West Transit. They actually recently re-did their routes so this specific example isn't in use today, but it was for years.

A single route was called the "Green & Blue Route"-- this was a bi-directions loop where Blue was the clockwise direction and Green was the counterclockwise direction. Setting aside for moment the color-centric metadata (which can't be modeled per-pattern in GTFS), this is not an uncommon type of route. A single loop route that goes in two directions.

On maps, timetables, and headsigns, one direction is named "Outbound" when it is on the north half of the route (heading towards the east) and is named "Inbound" when it is on the south half of the route (heading towards the west). The opposite direction is the opposite, named "Outbound" when it was on the south half of the route (still heading towards the east) and named "Inbound" when it is on the north half of the route (heading towards the west).

In this case, the agency has one route, two direction IDs (so you can split a timetable into two), and each direction ID has two names based on stop times. Neither of those names would apply to the entirety of the trips of either direction ID. It doesn't seem like the data standard should force the agency to define a single direction name per direction ID in this case...

Unless perhaps you want to consider "Clockwise" (which the agency doesn't use anywhere, except in a little icon in the legend) or "Blue" the direction name for the first direction, and then override it on every single trip and stop time to use "Outbound" and "Inbound" as applicable? How would a consumer be expected to handle this situation, in which there is a direction defined for the direction ID, but it is overridden in every possible instance?

[antrim]

Are there cases where the direction indicated on a timetable is different than the direction indicated on a vehicle? I was trying to look for how this is represented for the RER C example (https://www.transilien.com/lignes/rer-trains/rer-C). @stevenmwhite: Where did you find the RER C timetable you posted?

[stevenmwhite]

@antrim Those timetables are here: https://parisbytrain.com/wp-content/uploads/2019/03/paris_rer_c_train_schedule_paris_versailles_monday-friday_2017.pdf https://parisbytrain.com/wp-content/uploads/2019/03/paris_rer_c_train_schedule_paris_orly_massy_monday-friday_2017.pdf -- it looks like they have actually split out multiple timetables, beyond just two, based on the general direction names and show the branching within a direction name on one timetable. Though the names that appear on the maps (Ouest, Sud, etc.) don't appear on the timetables.

Another example of the loop situation is Santa Monica Big Blue Bus.

Route 41 is a clockwise loop.

• It has two directions named on the timetable: "SMC -> SMC 17TH ST STATION" and "E LINE -> MONTANA AVE."
• The trip headsign is: "↷ 41 Clockwise" but the direction names are not represented in GTFS.
• This would require two direction names per route and they would be overridden on every single trip and stop time if there was a single direction name defined at the route+direction_id level.

https://www.bigbluebus.com/Routes-and-Schedules/PdfHandler.ashx/41/little-blue-book.pdf

[timMillet]

@stevenmwhite I don't really understand the example of Santa Monica Big Blue Bus route 41. What would be the correct and accurate direction name(s) for route 41, according to you? Would it be Clockwise, or SMC -> SMC 17TH ST STATION and E LINE -> MONTANA AVE., or else?

I'm asking because the "SMC -> 17TH ST STATION E LINE -> MONTANA AVE" displayed on the timetable looks like a route_long_name or a route_desc value to me. It's also displayed on this Big Blue Bus webpage:

[stevenmwhite]

@timMillet You're totally correct. I think I misinterpreted the line break on the timetable (although "17th St Station E Line" is an odd way to refer to it) as that being two separate things, when in fact it's a single description. That is what they use as the long name.

---

As far as this issue goes in general, I'd love to keep it moving forward because I see the value in standardizing direction names. The sticking point with me in the entire discussion isn't really any of the specific technical representation options, but the rules that were added requiring only two direction names per route (uniqueness per route+direction_id). I find this to be prescriptive more than descriptive and I don't believe we should prescribe how agencies are allowed to describe their service, but rather represent how they already do.

However, I also seem to be the only one expressing concern with that rule, and technically the ability to override direction per trip and stop_time does allow an agency to use more than one direction name per direction_id. So, with that in mind I would be ok removing my opposition to E while maintaining that it's an inelegant solution.

I would like if someone can provide an example of how a consumer should handle the following cases:

The first, as described by Tim above:

In option E, the route_directions.route_direction_name can be overridden by trips.trip_direction_name and stop_times.stop_direction_name. Would this option work for you? Following your example:

• Route A with direction_id=0 would have route_direction_name=Inbound;
• trip 1 would have the stop_direction_names not populated for the first stop_times, then stop_direction_name=Outbound for the stop_times from downtown to the terminus;
• trip 2 would have trip_direction_name=Outbound.

The second, a loop example modeled in a similar fashion (genericized from my Key West example):

One direction of a loop with the direction_id=0 and route_direction_name=Inbound

• Trip 1 with direction_id=0 and the second half of the stop times populated with stop_direction_name=Outbound

A second direction of the loop with the direction_id=1 and route_direction_name=Outbound

• Trip 2 with direction_id=1 and the second half of the stop times populated with stop_direction_name=Inbound

This seems to technically accomplish what I'm expecting in the data, but I don't know a consumer would actually treat this on a timetable? The route direction has a name of "Inbound" while certain trips and stop times on that route direction have the opposite name? How would we expect a consumer to show the route-level label when it's been overridden for specific trips?

And finally, to clarify what is required and optional: Is the route_directions.txt file in Option E optional even trip_direction_name and stop_direction_name are used? If so, then I would say these examples could simply be handled completely in the trips and stop times files and the route_directions file omitted and that would assuage my concerns.

[sam-hickey-arcadis]

Our reading of Option E is that route_directions.txt is optional even if trip_direction_name and/or stop_direction_name are populated. It would also be ok if a producer included values in route_direction.txt for only some routes and directions.

In the case where trip_direction_name overrides a route_direction_name, we would expect standard behavior by consumers would be to show the route_direction_name when grouping trips with the associated route_id and direction_id.

For the two examples from @stevenmwhite, we recognize that an agency may have internal standards to use only Inbound and Outbound, but both examples seem like they would be better represented with different route_direction_name values (Westbound/Eastbound for the first example and Clockwise/Counterclockwise for the second example) that would allow natural grouping at the route and direction level while also using overrides as needed at the trip or stop times level.

[stevenmwhite]

Our reading of Option E is that route_directions.txt is optional even if trip_direction_name and/or stop_direction_name are populated.

If this is going to be how it's understood generally, I'm ok moving forward with Option E. I don't see how it satisfies others' desires to have only one route name per direction ID, if that's optional and can be overridden on each trip/stop_time, but this way would be ok with me and I wouldn't vote against a proposal reflecting this.

[jewel1965]

One thing I forgot to mention in my earlier comment is that 511 SF Bay would like the direction name (in whatever option we decide to move forward with) to be a required data. We, with our transit agency partners in the region, have worked very hard over the years to collect this data. We would like not to loose that progress to an 'optional' data field.

--Nisar Ahmed, 511 SF Bay

[stevenmwhite]

@jewel1965 I think you can still require that agencies in your region provide this information for 511 integration without it being a requirement in the general scope of the spec. That should be perfectly reasonable.

[jewel1965]

@stevenmwhite, I agree with you. At the same time, if it is not a required field, the motivation for transit agencies to comply with the new specification will be low. Some will and we will have to support them, while maintaining support for those who will need time to move away form our directions.txt file for a long time.

[stevenmwhite]

@jewel1965 I understand that completely, and we'd be in the same position considering we produce feeds for a few agencies in the Bay Area as well as many outside that region.

In general from the GTFS spec standpoint I don't think we can really be adding new required fields or it immediately invalidates every existing feed that does currently comply and adequately describes a transit service.

[gcamp]

Yes I don't think making it required is really a possibility. Making the direction name required without making the headsign required would not be logical.

[antrim]

Local/regional organizations can still set their own guidelines and requirements, layered over the global specification, similar to how the proposed California Minimum GTFS Requirements. MTC's GTFS Extended is another example of this, though if these direction name fields were adopted in the global GTFS, there would be two different approaches. Local requirements or guidelines can specify that fields that are optional globally are required locally. This would be best for interoperability.

[jewel1965]

Does GTFS spec maintain version? If so, spec updates could be rolled out as new versions. That will allow data producers and consumers to declare their version compatibility. An 'optional' data element in one version could become 'required' in the next version. Not suggesting that this is needed for the direction name element, but thinking in general.

[timMillet]

@jewel1965 GTFS is not versioned, and the current Specification Amendment Process mentions that "changes to the spec should be backward-compatible". IMHO, making required a new file like route_directions.txt is not backward-compatible, unfortunately. However, as Aaron stated, producers can still set their own requirements, layered over the global specification that every consumer will be able to implement.

[antrim]

I think the @Trillium-Solutions preferred option would be Option D with the addition of a recommendation (not requirement) that there is only 2 directions per route. (From this thread, it seems like there are cases where more than 2 directions are represented on a route.)

It would be useful to converge on one option (even if we don't immediately vote on it), so that data providers including Trillium can begin to plan for this addition.

Does anyone else have an update on their opinion after this discussion?

[stevenmwhite]

Thanks @antrim. Our preference at GMV Syncromatics would be, in this order:

1. Option D
2. Option A
3. Option E

I'd be fine supporting any of those three. Ultimately I would be against a requirement that there only be two direction names per route, but ok with a recommendation as you suggest (though perhaps a recommendation is better in a best practice document and not in the spec itself).