GTFS Best Practices

Google Transit Extensions to GTFS

Introduction

The Google Transit team is continuously working to improve the GTFS specification to accommodate the needs of our partners. Several extensions have been proposed for inclusion in the GTFS spec that in the meantime can be used by partners in their feed submitted to Transit in Google Maps.  Below, you can find a comprehensive list of these features.

If you have your own proposals for extending the GTFS specification, see the official GTFS Change process.


Multi-agency fare attributes

In order to support fare attributes in a feed with multiple agencies, the following extensions have been proposed (see discussion):

fare_attributes.txt

Field Name Required Details
agency_id Optional Use this field to associate the fare attributes to routes of one specific agency.

Maximum transfer count for a particular fare

In order to support fare attributes in a feed with multiple agencies, the following extensions have been proposed:

fare_attributes.txt

Field Name Required Details
transfers Optional Google Transit accepts values from 0 to 5; the GTFS spec states that it can take values from 0 to 2. Use this field to set the maximum number of transfers (excluding block transfers) allowed with the fare.

Additional Route Types

GTFS currently defines a number of route types that can be used to describe the type of service for a particular route (eg. bus vs rail vs ferry). To support a more rich set of types, an extension to the routes.txt route_type field has been proposed. For more details, see the Help Center article.


Station vehicle types

An extension has been proposed to allow specifying the type of vehicles serving a particular stop.

stops.txt

Field Name Required Details
vehicle_type Optional

Use this field to describe the type of transportation used at the stop. It accepts an valid routes.txt route_type value, including our proposed extended route type values.


Station entrances

For agencies using the stop-station hierarchy feature, it is useful to define entrances.  We propose an extension to the location_type field of stops.txt to allow the specification of these features.

stops.txt

Field Name Required Details
location_type Optional New values added to the existing spec:
2 - indicates an entrance.  The stop entry must also specify a parent_station value referencing the stop id of the parent station for the entrance.

Station platforms

For agencies using the stop-station hierarchy feature, it is useful to define platforms within those stations.  We propose an extension to the stops.txt to allow the specification of these features.

stops.txt

Field Name Required Details
platform_code Optional Indicates the platform identifier for a platform stop. This should be just the platform identifier (eg. "G" or "3"). Words like “platform” or "track" (or the feed’s language-specific equivalent) should not be included.  This allows feed consumers to more easily internationalize and localize the platform identifier into other languages.

Translations

In regions that have multiple official languages, transit agencies/operators typically have language-specific names and web pages.  In order to best serve riders in those regions, it is useful for the GTFS feed to include these language-dependent values.

translations.txt

Field Name Required Details
trans_id Required

This is used to match values in any URL or
human-readable text field in the feed.  The fields that qualify for translation typically end in "_name", "_desc", "_headsign", and "_url".

lang Required

A BCP 47 code for the language of the
translated value.  Please refer to Language Tags in HTML and XML and Picking the Right Language Code for more guidance on specifying a language code.

translation Required The translated value in the specifed language.  Whenever the contents of the feed are
displayed in the language specified in the "lang" field, values
matching "trans_id" will be replaced with the value specified here.

Here's a brief example:

trans_id,               lang, translation

Hospital,                 fr, Hôpital

stopname-3618321864,      en, Eiffel Tower

stopname-3618321864,      fr, Tour Eiffel

http://www.example.com/,  fr, http://www.example.com/fr.html

The first row demonstrates how the file can be used to translate a human readable name in the default language of the feed (defined in agency_lang in agency.txt) into a name in an alternate language. Note that this only translates entire values; it would match a stop named "Hospital" but not one named "Central Hospital".

The second and third rows show how abstract values can be used in the feed for greater precision. In this case, there would presumably be a stop_name value of "stopname-3618321864" in the feed's stops.txt file. When viewed in an English interface, that stop would be shown as "Eiffel Tower", and when viewed in French, it would be shown as "Tour Eiffel".

The final row shows how the translated version of a URL can be provided. Multilingual agencies tend to offer their landing pages in multiple languages, so we want to be able to give the rider the appropriate page when they click through for more information about a stop or route.


Route-to-route and trip-to-trip transfers

Right now, the GTFS specification allows an agency to define transfer semantics using the transfers.txt file, supporting features such as preferred transfers, timed transfers, and restricted transfers. Currently, those transfers only apply to stops. Google has received feedback from a number of agencies that they'd like to be able to specify more detailed transfer information at a route or even a trip level. Working with these agencies, we've come up for a proposal for modelling route-to-route and trip-to-trip transfers and we are looking for feedback from the GTFS community.

Motivation

We want to be able to specify transfers between specific routes or even specific trips for a given stop pair, without having to specify the same transfer for all the trips of that stop pair.

For example:

  • If two trips arrive at the same platform and wait for each other, we want to specify a timed transfer between these two trips. But we do not want all the transfers at this train station to be timed transfers.

  • If a train is know to be often late by up to 30 minutes, we want to disallow the transfers from this train to any other train if there is less than 35 minutes between the scheduled arrival and the departure.

Details

Add 4 optional fields to transfers.txt:

  • from_route_id
  • to_route_id
  • from_trip_id
  • to_trip_id

The from_route_id and to_route_id fields can contain a route_id (as specified by routes.txt), reducing the scope to which the given transfer applies. If from_route_id is specified, the transfer will only apply to the arriving trip with the given route id, at the given from_stop_id. If to_route_id is specified, the transfer will only apply to the departing trip with given route id, at the given to_stop_id.

The from_trip_id and to_trip_id fields can contain a trip_id, as specified by trips.txt. If from_trip_id is given, from_route_id is ignored, and if to_trip_id is given, to_route_id is ignored. If from_trip_id is specified, the transfer will only apply to the arriving trip with the given trip id, at the given from_stop_id. If to_trip_id is specified, the transfer will only apply to the departing trip with the given trip id, at the given to_stop_id.

Specificity of a transfer

Some transfers are more specific than others. We want to define a simple ranking mechanism to determine when a transfer should be applied. We thus define the "specificity" of a transfer.

The specificity of the source of the transfer is 0 if only from_stop_id is given, 1 if from_route_id is specified, and 2 if from_trip_id is specified. The same applies for target: 0 if only to_stop_id is given, 1 if to_route_id is specified, and 2 if to_trip_id is specified. The sum of these 2 values gives the specificity of the transfer, between 0 and 4 inclusive. For a given ordered pair of arriving trip and departing trip, the transfer with the greatest specificity that applies between these 2 trips is chosen. So for any pair of trips, there should NOT be two transfers with equally maximal specificity that could apply.

Example of an ambiguous rule:

from_stop_id,to_stop_id,from_route_id,to_route_id,transfer_type
stopFrom,stopTo,routeFrom,,0
stopFrom,stopTo,,routeTo,1

These two transfers both have a specificity of 1. But for transfers between a trip with id route id "routeFrom" arriving at stop "stopFrom", to a trip with route id "routeTo" arriving at stop "stopTo", either of these two rules can apply.