Fares v2 is a GTFS extension project that aims to address the limitations of Fares v1. This extension project is being adopted in iterations. The below examples outline how to model basic concepts, including fare products and how riders can use their fare for transfers. See more information about the Fares v2 extension project here.
In the interim, producers may implement Fares v2 alongside implementation of Fares v1 in the same dataset as there exists no technical conflict between the two. Consumers will have the choice on which implementation to consume independently from the other. With adoption and sufficient endorsement of Fares v2, Fares v1 may be deprecated in the future.
Define a transit fare¶
There are several ways to pay fares to use the Maryland Transit Administration system. There are four types of regular full price fare options:
- One-way ticket that costs $2.00 USD
- Day pass that costs $4.60 USD
- Weekly pass that costs $22 USD
- A monthly pass that costs $77 USD
Transit tickets or fares are referred to as fare products in GTFS. They can be described using the fare_products.txt file. Each entry corresponds to a specific fare.
|core_local_oneway_fare||One Way Full Fare||2.00||USD|
|core_local_1_day_fare||1-Day Pass - Core Service||4.60||USD|
|core_local_31_day_fare||31-Day Pass - Core Service||77.00||USD|
|core_local_7_day_fare||7-Day Pass - Core Service||22.00||USD|
Create rules for single leg journeys¶
In GTFS, a fare leg corresponds to a trip that a rider makes without transferring between different modes, routes, networks, or agencies. In the Maryland Transit Administration's feed, a single fare allows riders to travel within any pair of stops and subway stations within the
core network of BaltimoreLink buses, Light RailLink and Metro SubwayLink routes.
Leg groups define trips within a network from an origin to a destination (or a set of origins to a set of destinations if the area IDs correspond to grouped stops). The file below describes rules to travel anywhere within the Maryland Transit Administration’s core network. Each rule corresponds to one of the regular fare products in the Define a transit fare example.
Create rules for transfers¶
There is a 90 minute transfer for riders who purchase a one-way fare to ride BaltimoreLink local buses, Metro SubwayLink, or Light RailLink. This means that they can transfer an unlimited number of times between the local buses, subway, and light rail within the 90 minute timeframe.
The file above represents this in GTFS with the following fields:
- A transfer is possible to and from legs that are a one way trip (
transfer_countis set to
-1since there is no limit on the number of transfers permitted
duration_limitis set to
5400seconds, which is equivalent to 90 minutes
duration_limit_typeis set to
1since the transfer time starts when the rider departs on any route in the
core_local_one_way_tripfare leg and ends when they depart on a different fare leg.
fare_transfer_typeis set to
0since riders only pay for the first fare only. There is no transfer fee or a second fare for transferring within the 90 minute window. Hence, the cost can be modeled as the sum of the first fare and the sums of the transfer fees.
transfer_countis set to
-1as the rider can transfer an unlimited number of times within the 90 minute
After defining the fare, creating the appropriate
fare_leg_rule, and defining the
fare_transfer_rule, you can see the $2.00 USD
core_local_oneway_fare appear in trip planners. Here is an example from Transit:
Describe service locations in the same fare zone¶
Some transit agencies operate a zone-based fare structure. Fare zones are divided geographic areas associated with different fare prices. In Bay Area’s BART system, fares are different depending on the origin and destination (BART fare differences), and transit riders will need to know the right fare. Fare areas can be described using the stops_areas.txt file, which assigns stops from stops.txt to areas.txt.
First, identify the area in areas.txt . It is acceptable to leave
area_name blank if there is no area name. In the table below, there are three
stop_id from the stops.txt file, group stops together to its respective identified area (fare zone).
stop_id to each
area_id. In the BART example, each area contains only 1
stop_id. For instance, only stop
ASHB (Ashby Station) is included in the area
ASHB However, if an area includes multiple stops, multiple
stop_id should be listed.
fare_leg_rules.txt, different fare products can be identified based on different departure and arrival areas. For example, the first entry shows:
- Departure area is
- Arrival area is
- The fare product for the departure/arrival area is
The fare is identified in
Describe what fare media is accepted¶
San Francisco Muni riders can use several different types of fare media to pay for their trip and validate their fare:
These validation methods are referred to as
fare_media in GTFS-Fares v2 and can be described using
Below is an example snippet from the San Francisco Bay Area Regional Feed that can be accessed with the 511 SF Bay API.
Clipper is described as a physical transit card with
SFMTA Munimobile is described as a mobile app with
Cash has no fare media, since it is given directly to the driver without a ticket. As a result,
Additionally, producers who want to describe a physical ticket as a fare media can use
The Massachusetts Bay Transportation Authority (MBTA) allows users to pay for trips and passes using a physical paper ticket called CharlieTicket. To reflect this, there is a
charlieticket fare media in MBTA’s feed with a
|mticket||m Ticket app||4|
Define price differences based on fare media¶
Muni's fare price is different based on the fare media the rider uses. This example will cover how the adult local fare price changes when using cash or Clipper card. An adult local fare paid for with cash costs $3 USD and the same fare paid for with the Clipper card costs $2.50, 50 cents less.
Each entry below describes a fare media.
fare_products.txt file snippet below shows how the amount of the
Muni single local fare product varies depending on the fare media that the rider uses.
|SF:local:single||Muni single local fare||3||USD||cash|
|SF:local:single||Muni single local fare||2.5||USD||clipper|
In Apple Maps, riders can see how their fare price changes. You can compare fare prices under the "Board the Muni J Church train" instruction:
Describe a contactless fare media option¶
The Clean Air Express in Northern Santa Barbara County accepts contactless payment by credit card, Google Pay and Apple Pay.
In the Clean Air Express feed, there is a
tap_to_ride fare media with a
fare_media_type=3, since it’s a cEMV (contactless Europay, Mastercard and Visa) option.
|tap_to_ride||Tap to Ride||3|
The single ride fare product shown below has both
tap-to-ride fare media options. When the single ride is paid for with the
tap-to-ride fare media, it is one USD dollar cheaper.
Define price differences based on time and day of trip¶
Certain transit agencies vary their fares based on the time and/or day of the week. This means that fares are associated with a time period where the trip is made, such as peak, off-peak hours, or weekends.
Washington DC’s Metrorail fares vary based on multiple factors, including the day and time of the trip. Variable time fares in GTFS can be defined using
timeframes.txt, in which it is possible to designate specific time periods that then can be associated in
fare_leg_rules.txt to assign the applicable fare product that corresponds to the time when the trip is made. The following is a fictional example, based on WMATA's fares as of spring 2023.
First, service days are defined using
Afterwards, the desired timeframes are defined in
timeframes.txt, providing an id, the applicable days via a reference to
calendar.service_id, and if applicable, the start time and end time for each time period.
Next, the corresponding time specific fares in
fare_products.txt are created (e.g. Peak fare)
|weekend_fare||Weekend Metrorail one-way fare||2||USD|
|late_night_fare||Late Night flat fare (Mon - Fri after 9:30pm)||2||USD|
Lastly, timeframes are associated with fare products in
fare_leg_rules.txt using the fields
to_timeframe_group_id. These fields determine whether a fare applies solely to the start of the leg or both the start and end of the leg.
For this example, based on WMATA fares, the fare depends only on the leg's departure timeframe, so
to_timeframe_group_id is left blank.
network_id references the foreign ID
routes.network_id, and that the selection of the correct fare product for each trip will be a combination of arrival and departure times from
stop_times.txt along with the times defined in
In this case, a user paying for a trip that departs at 7:30 AM would have to pay 5.00 USD (Peak fare) while another user departing at 11:30 AM would only have to pay a 3.00 USD fare (Off-peak fare).
Define time-variable fares along with zone based fares¶
In New York's MTA Metro-North railroad network, fares vary based on both the time of the day of the trip, as well as the trip’s origin and destination areas. The following example illustrates the fare rules applicable to a trip from Grand Central Station to Cold Spring (NY, USA).
Service days for train services 3 and 13 are defined using
calendar.txt. Notably, other records with generic days (i.e. weekdays, weekends, and anyday) that aren't associated with any trips are defined, and these will be associated with timeframes in order to model
Records are created in
timeframes.txt, including cases where the time covers the 24-hour range period (
weekends), and peak and off-peak periods:
- AM Peak: from 6 am to 10 am on weekdays
- AM2PM Peak: from 6 AM to 9 AM and from 4 pm to 8 pm on weekdays
- Not AM Peak: weekday time not included in AM Peak
- Not AM2PM Peak: weekday time not included in AM2PM Peak
Each individual fare product is defined in
fare_products.txt. Since Cold Spring is located in zone 7, this example only lists trips between zone 1 and 7. The full dataset would include a record for each price defined by a time and zone combination. Additionally, the example only displays one fare media (
paper), but additional combinations could be created if prices would also vary based on the fare media.
|mnr_1:HUD-7_adult_peak||Outbound Adult Peak Zonal Fare||paper||20.00||USD|
|mnr_1:HUD-7_adult||Outbound Adult Off Peak Zonal Fare||paper||15.00||USD|
|mnr_HUD-7:1_adult_peak||Inbound Adult Peak Zonal Fare||paper||20.00||USD|
|mnr_HUD-7:1_adult||Inbound Adult Off Peak Zonal Fare||paper||15.00||USD|
Lastly, the combinations of origin and destination areas, along with their respective timeframes are associated with the corresponding fare product in
fare_leg_rules.txt. Here, trips starting or arriving in Zone 1 (i.e.
area_id=mnr_1) during peak times are subject to a specific peak fare corresponding to the arrival and departure zones of the trip (i.e.
Using this dataset, a user boarding train #869 (
service_id=3) scheduled to depart from Grand Central (zone
mnr_1) at 6:45 pm would have to pay an Outbound Adult Peak Zonal Fare of 20.00 USD, since the trip is originated in the
mnr_am2pmpeak period and from
Alternatively, a user traveling in train #883 (
service_id=13) would pay an Outbound Adult Off Peak Zonal Fare of only 15.00 USD, as this train is scheduled to depart Grand Central (zone
mnr_1) at 9:04 pm.
In Apple Maps, riders can see how their fare price changes and compare fare prices next to the train scheduled departure: