GTFS Style Guide

[Brian Ferris]

When it comes to producing a "valid" GTFS feed, some things are black and white.  For example, an entry in routes.txt should have a route_id value and every entry in trips.txt should reference one of those route_id values.  This constraint is easy to verify and there is little question about what separates a valid feed from an invalid feed.

But not all aspects of a GTFS feed are quite so clear-cut.  For example, when is a route_short_name no longer short?  How should an agency map their routes and lines to entries in routes.txt?  Is calendar.txt preferred to calendar_dates.txt?  There are a number of recurring issues that I've seen when looking at how agencies have interpreted the spec and I'm sure other consumers of GTFS have their own pet-peeves.  For many of these issues, there may be no "right" answer.  But I do think we can do a better job of giving GTFS producers guidance about best-practices when it comes to constructing a feed.  Various parts of the existing GTFS spec page serve this goal (eg https://developers.google.com/transit/gtfs/examples/display-to-users) but maybe don't go far enough.

So here is what I'm proposing.  I'd like to create a GTFS Style Guide.  This would be a guide that attempts to come up with some best-practices around creating a GTFS feed, focusing especially on those places in there spec where there may be more than one way to do things.  This would live on the GTFS spec page along with the existing spec resources.

How do we create a GTFS Style Guide?  I think the process would be similar to the existing mechanism for proposing an extension to GTFS:

1) A number of interested parties get together and put together some text for a section of the GTFS style guide.

2) The text is floated before the community for feedback.

3) If we can come to consensus that the proposed style section is worthy of addition, we add it.

What do you guys think?  Is this something that people would find useful, both for GTFS producers and consumers?  If so, is anyone else out there interested in contributing?  I've certainly got some ideas of my own about where to start, but I'm curious where others see room for improvement.

Thanks,

Brian

[Aaron Antrim]

I think this sounds like a useful resource and project.

--
You received this message because you are subscribed to the Google Groups "General Transit Feed Spec Changes" group.
To post to this group, send email to gtfs-c...@googlegroups.com.
To unsubscribe from this group, send email to gtfs-changes...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/gtfs-changes?hl=en.

[Wojciech Kulesza]

Very much +1 for Brian's proposal as well from me & goEuropa team.

Wojciech

--

[Roger Slevin]

+1 from me - though I think it is important to stress that this should be seen as generating “preferred style guidelines” without changing the technical spec ... and I wonder whether we will find that there are some styles that will differ depending on what database system underlies the creation of the GTFS files.  No harm in that - but I think the project should recognise this possibility from the outset and accept that in some cases there just may be some parallel preferred styles to suit different data sources.

 

Roger

--

[Brian Ferris]

Thanks for the feedback everybody.  I think that there were enough positive responses that I'd like to try working on a first section for the guide to see how the process works in practice.  To get started, I'd like to propose some text outlining some best practices for mapping physical routes to entries in routes.txt:

https://docs.google.com/document/d/1IG3cUIUvikFmmcg8yVLy9a51uNj3Oh9E6I0pRH0300M/edit

If everything works as it should, anybody should be able to add comments to that document.  If you feel really strongly about editing actual text, I can even give you edit privileges.

And to get needlessly meta, if I had to write a style-guide for the style-guide, it would say "Keep it short." so if you can think of a way to say something more concisely than I have, I'd definitely like your feedback.

Thanks,

Brian

[Brian Ferris]

Anybody have feedback on this proposal?  Love it?  Hate it?  TL;DR?

[Aaron Antrim]

Brian,

Thank you for generating this proposal.  I added the following comment to the Google Doc:

I don't understand the purpose of grouping all trips of one intercity "service class" into a route.  This seems inconsistent with the way local transit services are usually organized: where "routes" are a collection of trips that serve the same (or roughly the same) travel corridor.  In other words, there is a requirement of shared route alignment.

Yet, the suggestion here is that intercity trips with different travel patterns should be assigned the same route_id in a GTFS file.  This could pose issues for software or projects that generate timetables or interactive route maps.

route_long_names have not been immediately obvious in some of Trillium's work.  Here is an example.  NorthWest Point is a service between Astoria and Portland in Oregon.  NorthWest Point is the "brand" of the service, which is operated by OC&W Coachways, which also operates other services in Oregon and Washington.  For the GTFS, we decided to use NorthWest Point as the route name.  Service destinations are provided in the trip_headsign field.  OC&W Coachways is the agency_name.

NorthWest Point schedule and service information: http://www.northwest-point.com/schedule.html

GTFS: http://oregon-gtfs.com/gtfs_data/ocw-or-us/

Note that the GTFS contains one other OC&W operated service.

I am sure that I will have additional comments, contributions, and questions as the style guide develops.  I plan to consult and contribute to the style guide during the process of preparing and maintaining GTFS, so my participation will be steadily ongoing rather than immediate and concentrated upfront.  I wouldn't object to edit privileges if you are ready to assign them.

Cheers,

Aaron

[Brian Ferris]

I apologize for not responding to this sooner, but I have been struggling to articulate exactly what I want to say regarding route organization for inter-city service.

I think the trickiness around inter-city service is that these routes typically don't have a route short name in the same way that local routes do.  Let's say an agency takes the reasonable approach of grouping their routes by cities visited.  You might have a hypothetical train that travels back and forth between Boston and New York as one route entry and another route entry for service between New York and Washington DC.  If these routes don't have branded names, agencies will often generate a "route_long_name" like "Boston - New York" or "New York - Washington DC", while "route_short_name" is blank.  The trick is that most applications tend to display the combination of route name + trip headsign together, which means you can get awkward combinations like "Boston - New York towards Boston" or "New York - Washington DC - New York" for instances where the trip is headed in the opposite direction of the how the labels happened to be ordered in the "route_long_name".  We've talked about this problem with route_long_name before (http://groups.google.com/group/gtfs-changes/browse_thread/thread/9533dacb183e3d0b) and maybe the addition of "route_service_name" could address this issue.  But ideally we'd have some form of service name for each route that isn't just a combination of waypoints.

However, the ultimate point I was trying to make about intercity-routes is that they don't always have an obvious service name in the same way that local routes often do.  There are a couple of ways that agencies might provide one:

1) Use the "branded" service name as you've described in your example.

2) Use the "service class" (eg. ICE - Inter-City Express) as the service name.

I guess my question for you example is what would happen if (hypothetically) there was NorthWest Point between multiple cities in Oregon?  Would you make NorthWestPoint the agency and then group the routes by city pairs?  Or would you keep NorthWest Point as the route and allow trips to just use their headsign to indicate direction of travel?

Thanks,

Brian

[Aaron Antrim]

Brian,

I understand your reasoning better now.

I agree that using locations served in the route_long_name and in the trip_headsign is awkward.  Here is an example of this (Newport/Bend service operated by Valley Retriever): http://g.co/maps/p5ptg

I think it may be easier for customers to understand this if the route_long_name was "Valley Retriever", which would then duplicate the agency_name, which should be "Valley Retriever Busline."

I'd suggest a good indicator for whether to use multiple rows in routes.txt to describe an intercity service such as NorthWest Point or Valley Retriever is whether the information is presented in separate timetables or not.  If it is presented in separate timetables, then it would be useful to have a way of referencing the distinct URLs for each timetable.

I think it is useful to look at the two major intercity services in the United States, Greyhound (not a GTFS publisher) and Amtrak (apparently a GTFS publisher, though not through a public feed):

Greyhound seems to have route numbers (potentially, matching to the route_short_name field rather well) that identify their services and timetables (click on the link for the route map):

http://extranet.greyhound.com/Revsup/schedules/pageset.html

I know that Greyhound puts a destination indicator on their buses.  I can't remember if the route numbers are ever exposed to passengers in the travel process, though.

Amtrak uses service names:

http://www.amtrak.com/servlet/ContentServer/Page/1237405732505/1237405732505

In summary:

* I agree that services that share a branded service name would be most often best expressed with one row in routes.txt, and trips with trip_headsign values that indicate destinations to which service is provided.

* I think that it could be useful to have route identifiers in many cases, and this comes up on the boundary between GTFS expressing the service as it is already being described, and making recommendations for how agencies should describe their services across all media: timetables, GTFS, and etc.

* I'll reach out to some intercity agencies and, pending their input, may modify some GTFS datasets to follow the style guidelines.

* I think that some of the ideas/discussion at http://groups.google.com/group/gtfs-changes/browse_thread/thread/9533dacb183e3d0b?pli=1 may be helpful in the future.

Cheers,

Aaron

[Brian Ferris]

I agree that this seems to be more of an issue of choosing good route names rather than choosing good route organization.  Indeed, the second item on my GTFS Style Guide TODO list was route naming, so perhaps we can tackle those issues there.

In the meantime, I've removed the second half of the GTFS route organization style guide proposal:

https://docs.google.com/document/d/1IG3cUIUvikFmmcg8yVLy9a51uNj3Oh9E6I0pRH0300M/edit

The guide boils down to "organize your routes in the same way your organize your timetables" at this point.

Thoughts?  Is this closer to acceptable?

Brian

[Aaron Antrim]

I think this is good, Brian.

Let's bring some of this discussion back to tackle route naming.

I can't see the revision history for the "GTFS Route Organization" document.  It might be useful if everyone could see the evolution of the document.

-Aaron

[Brian Ferris]

In Google Docs, under the "File" menu item, you should see a "See Revision History" menu item that should do the trick.

Brian

[Aaron Antrim]

On Thu, Mar 22, 2012 at 10:57 AM, Brian Ferris <bdfe...@google.com> wrote:

In Google Docs, under the "File" menu item, you should see a "See Revision History" menu item that should do the trick.

The "See Revision History" option is grayed out for me.  I assume this is true for everyone with comment-only privileges. 

[Brian Ferris]

Duly noted.  I've opened it up to editing for anyone with the link.

--