GTFS Best Practices

Understanding GTFS Concepts

The General Transit Feed Specification (GTFS) uses a number of terms to mean very specific things. These may not always be obvious and it can be confusing if you are not sure of the difference between a Route, Calendar, and Trip, for example.

This section tries to help explain the terms used in the GTFS specification to make it easier for you to produce your GTFS feed. For more information, refer to the GTFS specification or other Help Center articles.

Agency

An Agency is an operator of a public transit network, often a public authority. Agencies are defined in the file agency.txt, and can have URLs, phone numbers, and language indicators. If you are providing a feed that includes vehicles operated by different agencies, you can define multiple agencies in this file and associate them with each Trip

Route

GTFS Routes are equivalent to "Lines" in public transportation systems.  Routes are defined in the file routes.txt, and are made up of one or more Trips - remember that a Trip occurs at a specific time and so a Route is time independent.

Trip

A Trip represents a journey taken by a vehicle through Stops. Trips are time-specific - they are defined as a sequence of StopTimes, so a single Trip represents one journey along a transit line or route.

In addition to StopTimes, Trips use Calendars to define the days when a Trip is available to passengers.

StopTime

A StopTime defines when a vehicle arrives at a location, how long it stays there, and when it departs. StopTimes define the path and schedule of Trips.

Stop

A stop is a location where vehicles stop to pick up or drop off passengers. Stops are defined in the file stops.txt.

Stops can be grouped together, such as when there are multiple stops within a single station. This is done by defining one Stop for the station, and defining it as a parent for all the Stops it contains.

Stops may also have zone identifiers, to group them together into zones. This can be used together with FareAttributes and FareRules for zone-based ticketing.

Service

Services define a range of dates between which a Trip is available, the days of the week when it is available (e.g., Monday to Friday), and are defined in the calendar.txt file.

A single Service can be applied to multiple different Trips.

If a given vehicle has different schedules, such as one schedule on weekdays and a different one on weekends, you should define two Trips with the same stops but different Services and different StopTimes.

CalendarExceptions

If there are specific days when a trip is not available, such as holidays, you should define these in the calendar_dates.txt file. You can use this to define exceptional days when the Trip is operated, as well as when it is not operated.

For example, you may have special services that are only operated on a public holiday, and they would be defined as unavailable (in calendar.txt) and as available on the holiday (in calendar_dates.txt).

Frequency

Frequencies are used when a line does not have set arrival and departure times, but instead services run with a set interval. Frequencies are defined in the file frequencies.txt, and are associated with a Trip definition.

Shape

Shapes describe the physical path that a vehicle takes, and are defined in the file shapes.txt. Shapes belong to Trips, and consist of a sequence of points. Tracing the points in order provides the path of the vehicle. The points do not need to match stop locations.

Transfer

Transfers are used to define where passengers can transfer between different lines, and optionally, how long it takes. Transfers are defined in transfers.txt.

FareAttribute

A FareAttribute (defined in fare_attributes.txt) defines a fare class. A FareAttribute has a price, currency and whether it must be purchased on board the service or before boarding. It also defines the number of transfers it can be used for, and the duration it is valid.

FareRule

FareRules (defined in fare_rules.txt) specify how FareAttributes apply to your transit network. It associates FareAttributes with Routes, or with zones (via the zone identifier of Stops).

Transit Object Relationships

The following diagram illustrates the public GTFS attributes and relationships between the objects as a UML diagram.


You can see a larger version of the image here if desired.