On this page
- Unidirectional vs. bidirectional
- When to use stop_headsign
- branch codes
Unidirectional vs. bidirectional
A GTFS route can be either unidirectional or bidirectional. Although a bus run often consists of a vehicle heading outbound on a street and taking the same path to return, a GTFS trip with this behaviour should terminate at each end of the route. A trip should only be unidirectional if it is a true loop.
One way to determine whether a route is a true loop is to put yourself in the shoes of a rider along the route. If, along most of the route, the rider can walk across the street, or a block away (in the case of one-way streets), to catch the same bus going in the opposite direction, it is not a loop. (An exception: bi-directional loops, which offer clockwise and counter-clockwise service.) Lasso routes are more challenging to define as either unidirectional or bidirectional. If it is unfeasible that a rider takes the bus to get from one part of the lasso to another, the trip should be split in two directions (see direction_id).
When to use stop_headsign
When trips are split into two directions, a
trip_headsign distinguishes the directions. The route shown below, however, is unidirectional in the GTFS. Seen in the app, the user cannot determine the direction without a
stop_headsign because there is only one
trip_headsign ("Loop"). This is a case where the
stop_headsign should be used to specify direction if a lasso route is defined as unidirectional. Learn more about stop_headsign here.
This field should not contain any information that is already defined elsewhere in the GTFS, such as the
trip_headsign should contain only enough information for a rider to distinguish directions on a route, or distinct services in the same direction (i.e. when a route has multiple itineraries or branches in a single direction).
trip_headsign should not contain the trip's origin, or simply list waypoints with commas. In order to fit on most phone screens,
trip_headsign should be less than 40 characters. If no
trip_headsign is provided to Transit, the field is populated with the
stop_name of the last stop on the trip.
|Good Examples ✅||Bad Examples ❌|
|Fairway Station||Downtown Albany to Colonie Center|
|Fairway Station via Mill||Colonie Center to Downtown Albany|
|Northbound||Sat/Sun - Beltrone trips|
|Northbound to Fairway Station||Downtown Transit Center Bay 7|
|Outbound to Fairway via Mill||RED ROUTE|
trip_headsign is in the form
<cardinal direction> to <destination> and the next three departures do not have the same headsign, Transit's Nearby display splits headsigns, arranging destinations underneath the direction (if it exists). In the example below, the trips are also branded with letter branch codes, which are displayed to the left of the
Branch codes are letter designations assigned to distinct itineraries on a route. If two routes share a numeral but are distinct in agency publications, such as routes 71, 71A, 71B, 71C, and 71D in Pittsburgh, the routes should be given distinct
If a letter is used to denote a distinct itinerary for a route, such as Route 54 in Pittsburgh, this information should be included in the
Transit will automatically recognize letter branch codes if
trip_headsign begins with a single letter character followed by a hyphen. Either of the formats below are acceptable.
|A-St. Jacobs Market|
|W - 242nd Street Subway Station|
| C - Westchester Medical Center
This field should only be used when numbers are commonly used by riders to identify unique trips, typically for commuter rail. Transit cannot display both
trip_short_name and branch codes
Unless the route operates as a true unidirectional loop, each trip should operate in a distinct direction, denoted by
direction_id. If an agency's routes follow a direction (cardinal, in/outbound, or counter/clockwise), the value for
direction_id should remain consistent. Using
direction_id for a bidirectional route will allow the user to swipe on a route cell to switch directions at any point along the route. Without this field, the app cannot organize trips by direction. The example below uses a
direction_id that is consistent with the direction (Inferred from the headsign).
|Downtown via 4th St||1|
|Outbound to Elm Rd||0|
This field should be used to denote whether a trip is accessible. This usually refers to the accessibility features of the vehicle operating the trip. In the screenshot below, all trips on orange line are accessible (denoted by the symbol next to the arrival times), but two of the five stations are inaccessible (a property of stops.txt). This value is also used by the trip planner to determine the accessibility of a trip.