diff --git a/gtfs/CHANGES.md b/gtfs/CHANGES.md index 9bfe6121a..c537d1f38 100644 --- a/gtfs/CHANGES.md +++ b/gtfs/CHANGES.md @@ -53,21 +53,25 @@ Every new feature adds complexity to the creation and reading of feeds. Therefor ### Revision History +#### March 14, 2023 + +* Added fare media. See [discussion](https://github.com/google/transit/pull/355). + #### July 26, 2022 -* Added trip-to-trip transfers with in-seat option. See [discussion](https://github.com/google/transit/pull/303) +* Added trip-to-trip transfers with in-seat option. See [discussion](https://github.com/google/transit/pull/303). #### May 17, 2022 -* GTFS-Fares v2 base implementation. See [discussion](https://github.com/google/transit/pull/286) +* GTFS-Fares v2 base implementation. See [discussion](https://github.com/google/transit/pull/286). #### Oct 22, 2021 -* Added Primary and Foreign ID fields. See [discussion](https://github.com/google/transit/pull/278) +* Added Primary and Foreign ID fields. See [discussion](https://github.com/google/transit/pull/278). #### Oct 05, 2021 -* Added Trip-to-trip and route-to-route transfers. See [discussion](https://github.com/google/transit/pull/284) +* Added Trip-to-trip and route-to-route transfers. See [discussion](https://github.com/google/transit/pull/284). #### September 15, 2021 diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 453ead1e7..a917e6012 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -19,6 +19,7 @@ This document defines the format and structure of the files that comprise a GTFS - [calendar\_dates.txt](#calendar_datestxt) - [fare\_attributes.txt](#fare_attributestxt) - [fare\_rules.txt](#fare_rulestxt) + - [fare\_media.txt](#fare_mediatxt) - [fare\_products.txt](#fare_productstxt) - [fare\_leg\_rules.txt](#fare_leg_rulestxt) - [fare\_transfer\_rules.txt](#fare_transfer_rulestxt) @@ -104,11 +105,12 @@ This specification defines the following files: | [stops.txt](#stopstxt) | **Required** | Stops where vehicles pick up or drop off riders. Also defines stations and station entrances. | | [routes.txt](#routestxt) | **Required** | Transit routes. A route is a group of trips that are displayed to riders as a single service. | | [trips.txt](#tripstxt) | **Required** | Trips for each route. A trip is a sequence of two or more stops that occur during a specific time period. | -| [stop_times.txt](#stop_timestxt) | **Required** | Times that a vehicle arrives at and departs from stops for each trip. | +| [stop_times.txt](#stop_timestxt) | **Required** | Times that a vehicle arrives at and departs from stops for each trip. | | [calendar.txt](#calendartxt) | **Conditionally Required** | Service dates specified using a weekly schedule with start and end dates.

Conditionally Required:
- **Required** unless all dates of service are defined in [calendar_dates.txt](#calendar_datestxt).
- Optional otherwise. | | [calendar_dates.txt](#calendar_datestxt) | **Conditionally Required** | Exceptions for the services defined in the [calendar.txt](#calendartxt).

Conditionally Required:
- **Required** if [calendar.txt](#calendartxt) is omitted. In which case [calendar_dates.txt](#calendar_datestxt) must contain all dates of service.
- Optional otherwise. | | [fare_attributes.txt](#fare_attributestxt) | Optional | Fare information for a transit agency's routes. | -| [fare_rules.txt](#fare_rulestxt) | Optional | Rules to apply fares for itineraries. | +| [fare_rules.txt](#fare_rulestxt) | Optional | Rules to apply fares for itineraries. | +| [fare_media.txt](#fare_mediatxt) | Optional | To describe the fare media that can be employed to use fare products.

File [fare_media.txt](#fare_mediatxt) describes concepts that are not represented in [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). As such, the use of [fare_media.txt](#fare_mediatxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). | | [fare_products.txt](#fare_productstxt) | Optional | To describe the different types of tickets or fares that can be purchased by riders.

File [fare_products.txt](#fare_productstxt) describes fare products that are not represented in [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). As such, the use of [fare_products.txt](#fare_productstxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). | | [fare_leg_rules.txt](#fare_leg_rulestxt) | Optional | Fare rules for individual legs of travel.

File [fare_leg_rules.txt](#fare_leg_rulestxt) provides a more detailed method for modeling fare structures. As such, the use of [fare_leg_rules.txt](#fare_leg_rulestxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). | | [fare_transfer_rules.txt](#fare_transfer_rulestxt) | Optional | Fare rules for transfers between legs of travel.

Along with [fare_leg_rules.txt](#fare_leg_rulestxt), file [fare_transfer_rules.txt](#fare_transfer_rulestxt) provides a more detailed method for modeling fare structures. As such, the use of [fare_transfer_rules.txt](#fare_transfer_rulestxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). | @@ -307,7 +309,7 @@ File: **Optional** Primary key (`fare_id`) **Versions**
-There are two modelling options for describing fares. GTFS-Fares V1 is the legacy option for describing minimal fare information. GTFS-Fares V2 is an updated method that allows for a more detailed account of an agency's fare structure. Both are allowed to be present in a dataset, but only one method should be used by a data consumer for a given dataset. It is recommended that GTFS-Fares V2 takes precedence over GTFS-Fares V1.

The files associated with GTFS-Fares V1 are:
- [fare_attributes.txt](#fare_attributestxt)
- [fare_rules.txt](#fare_rulestxt)

The files associated with GTFS-Fares V2 are:
- [fare_products.txt](#fare_productstxt)
- [fare_leg_rules.txt](#fare_leg_rulestxt)
- [fare_transfer_rules.txt](#fare_transfer_rulestxt) +There are two modelling options for describing fares. GTFS-Fares V1 is the legacy option for describing minimal fare information. GTFS-Fares V2 is an updated method that allows for a more detailed account of an agency's fare structure. Both are allowed to be present in a dataset, but only one method should be used by a data consumer for a given dataset. It is recommended that GTFS-Fares V2 takes precedence over GTFS-Fares V1.

The files associated with GTFS-Fares V1 are:
- [fare_attributes.txt](#fare_attributestxt)
- [fare_rules.txt](#fare_rulestxt)

The files associated with GTFS-Fares V2 are:
- [fare_media.txt](#fare_mediatxt)
- [fare_products.txt](#fare_productstxt)
- [fare_leg_rules.txt](#fare_leg_rulestxt)
- [fare_transfer_rules.txt](#fare_transfer_rulestxt)
@@ -343,21 +345,37 @@ For examples that demonstrate how to specify a fare structure with [fare_rules.t | `destination_id` | Foreign ID referencing `stops.zone_id` | Optional | Identifies a destination zone. If a fare class has multiple destination zones, create a record in [fare_rules.txt](#fare_rules.txt) for each `destination_id`.
*Example: The `origin_id` and `destination_id` fields could be used together to specify that fare class "b" is valid for travel between zones 3 and 4, and for travel between zones 3 and 5, the [fare_rules.txt](#fare_rules.txt) file would contain these records for the fare class:*
`fare_id,...,origin_id,destination_id`
`b,...,3,4`
`b,...,3,5` | | `contains_id` | Foreign ID referencing `stops.zone_id` | Optional | Identifies the zones that a rider will enter while using a given fare class. Used in some systems to calculate correct fare class.
*Example: If fare class "c" is associated with all travel on the GRT route that passes through zones 5, 6, and 7 the [fare_rules.txt](#fare_rules.txt) would contain these records:*
`fare_id,route_id,...,contains_id`
`c,GRT,...,5`
`c,GRT,...,6`
`c,GRT,...,7`
*Because all `contains_id` zones must be matched for the fare to apply, an itinerary that passes through zones 5 and 6 but not zone 7 would not have fare class "c". For more detail, see [https://code.google.com/p/googletransitdatafeed/wiki/FareExamples](https://code.google.com/p/googletransitdatafeed/wiki/FareExamples) in the GoogleTransitDataFeed project wiki.* | +### fare_media.txt + +File: **Optional** + +Primary Key (`fare_media_id`) + +To describe the different fare media that can be employed to use fare products. Fare media are physical or virtual holders used for the representation and/or validation of a fare product. + +| Field Name | Type | Presence | Description | +| ------ | ------ | ------ | ------ | +| `fare_media_id` | Unique ID | **Required** | Identifies a fare media. | +| `fare_media_name` | Text | Optional | Name of the fare media.

For fare media which are transit cards (`fare_media_type =2`) or mobile apps (`fare_media_type =4`), the `fare_media_name` should be included and should match the rider-facing name used by the organizations delivering them. | +| `fare_media_type` | Enum | **Required** | The type of fare media. Valid options are:

`0` - None. Used when there is no fare media involved in purchasing or validating a fare product, such as paying cash to a driver or conductor with no physical ticket provided.
`2` - Physical transit card that has stored tickets, passes or monetary value.
`3` - cEMV (contactless Europay, Mastercard and Visa) as an open-loop token container for account-based ticketing.
`4` - Mobile app that have stored virtual transit cards, tickets, passes, or monetary value.| + ### fare_products.txt File: **Optional** -Primary Key (`fare_product_id`) +Primary Key (`fare_product_id`, `fare_media_id`) To describe the different types of tickets or fares that can be purchased by riders. | Field Name | Type | Presence | Description | | ------ | ------ | ------ | ------ | -| `fare_product_id` | ID | **Required** | Identifies a fare product. | +| `fare_product_id` | ID | **Required** | Identifies a fare product. | | `fare_product_name` | Text | Optional | The name of the fare product as displayed to riders. | +| `fare_media_id` | Foreign ID referencing `fare_media.fare_media_id` | Optional | Identifies a fare media that can be employed to use the fare product during the trip. When `fare_media_id` is empty, it is considered that the fare media is unknown.| | `amount` | Currency amount | **Required** | The cost of the fare product. May be negative to represent transfer discounts. May be zero to represent a fare product that is free.| | `currency` | Currency code | **Required** | The currency of the cost of the fare product. | + ### fare_leg_rules.txt File: **Optional**