diff --git a/gtfs-realtime/CHANGES.md b/gtfs-realtime/CHANGES.md
index 8579e854a..1c81cf94b 100644
--- a/gtfs-realtime/CHANGES.md
+++ b/gtfs-realtime/CHANGES.md
@@ -19,30 +19,30 @@ When a producer or consumer is interested in adding a new field to the GTFS Real
1. Create a git branch with update of all relevant parts of protocol definition, specification and documentation files (except for translations).
1. Create pull request on https://github.com/google/transit. Pull request must contain an extended description of the patch. The creator of the pull request becomes the _advocate_.
1. Once pull request is registered, it must be announced by its advocate in the [GTFS Realtime mailing list](https://groups.google.com/forum/#!forum/gtfs-realtime). Once announced, the pull request is considered a proposal.
- - Since the advocate is a contributor, they must sign the [Contributor License Agreement](../CONTRIBUTING.md) before pull request can be accepted.
+ - Since the advocate is a contributor, they must sign the [Contributor License Agreement](../CONTRIBUTING.md) before pull request can be accepted.
1. The discussion of the proposal follows. Pull request comments should be used as the sole discussion forum.
- - The discussion lasts for as long as the advocate feels necessary, but must be at least 7 calendar days.
- - The advocate is responsible for timely update of the proposal (i.e. pull request) based on the comments for which they agree to.
- - At any point in time the advocate can claim proposal abandoned.
+ - The discussion lasts for as long as the advocate feels necessary, but must be at least 7 calendar days.
+ - The advocate is responsible for timely update of the proposal (i.e. pull request) based on the comments for which they agree to.
+ - At any point in time the advocate can claim proposal abandoned.
1. The advocate can call for a vote on a version of the proposal at any point in time following the initial 7-day interval required for discussion.
1. Vote lasts the minimum period sufficient to cover 7 full calendar days and 5 full Swiss business days. Vote ends at 23:59:59 UTC.
- - The advocate should announce the specific end time at the start of the vote.
- - During voting period only editorial changes to the proposal are allowed (typos, wording may change as long as it does not change the meaning).
- - Anyone is allowed to vote yes/no in a form of comment to the pull request, and votes can be changed until the end of the voting period.
+ - The advocate should announce the specific end time at the start of the vote.
+ - During voting period only editorial changes to the proposal are allowed (typos, wording may change as long as it does not change the meaning).
+ - Anyone is allowed to vote yes/no in a form of comment to the pull request, and votes can be changed until the end of the voting period.
If a voter changes her vote, it is recommended to do it by updating the original vote comment by striking through the vote and writing the new vote.
- - Votes before the start of the voting period are not considered.
+ - Votes before the start of the voting period are not considered.
1. The proposal is accepted if there is a unanimous consensus yes with at least 3 votes.
- - The proposer's vote does not count towards the 3 vote total. For example, if Proposer X creates a pull request and votes yes, and User Y and Z vote yes, this is counted as 2 total yes votes.
- - Votes against shall be motivated, and ideally provide actionable feedback.
- - If the vote has failed, then the advocate may choose to continue work on the proposal, or to abandon the proposal.
+ - The proposer's vote does not count towards the 3 vote total. For example, if Proposer X creates a pull request and votes yes, and User Y and Z vote yes, this is counted as 2 total yes votes.
+ - Votes against shall be motivated, and ideally provide actionable feedback.
+ - If the vote has failed, then the advocate may choose to continue work on the proposal, or to abandon the proposal.
Either decision of the advocate must be announced in the mailing list.
- - If the advocate continues the work on proposal then a new vote can be called for at any point in time but no later than 30 calendar days after the end of the previous vote.
- - If a vote was not called within 30 calendar days from the original proposal or 30 calendar days since end of the previous vote, then the proposal is abandoned.
+ - If the advocate continues the work on proposal then a new vote can be called for at any point in time but no later than 30 calendar days after the end of the previous vote.
+ - If a vote was not called within 30 calendar days from the original proposal or 30 calendar days since end of the previous vote, then the proposal is abandoned.
1. If the proposal is abandoned, the corresponding pull request is closed. Note that the advocate may choose to implement the feature as an [custom extension](#extensions) instead of part of the official spec.
1. If the proposal is accepted:
- - Google is committed to merging the voted upon version of the pull request (provided that the contributors have signed the [CLA](../CONTRIBUTING.md)), and performing the pull request within 5 business days.
- - Google is committed to timely updating https://github.com/google/gtfs-realtime-bindings repository. Commits to gtfs-realtime-bindigs that are a result of a proposal, should reference the pull request of the proposal.
- - Translations must not be included into the original pull request.
+ - Google is committed to merging the voted upon version of the pull request (provided that the contributors have signed the [CLA](../CONTRIBUTING.md)), and performing the pull request within 5 business days.
+ - Google is committed to timely updating https://github.com/google/gtfs-realtime-bindings repository. Commits to gtfs-realtime-bindigs that are a result of a proposal, should reference the pull request of the proposal.
+ - Translations must not be included into the original pull request.
Google is responsible for eventually updating relevant translations into supported languages, but pure translation pull requests from the community are welcome and will be accepted as soon as all editorial comments are addressed.
### Guiding Principles
@@ -96,3 +96,4 @@ extend transit_realtime.TripDescriptor {
|1007|NSW TrainLink|[Gregory Nicholls](mailto:gregory.nicholls@transport.nsw.gov.au)|[Group discussion](https://groups.google.com/d/msg/gtfs-realtime/G75O1zyQS_Q/VtNmTJvSAwAJ)|
|1008|SEPTA - Southeastern Pennsylvania Transportation Authority|[Gregory Apessos](mailto:GApessos@septa.org)|https://github.com/septadev|
|1009|Swiftly|[mike@goswift.ly](mailto:mike@goswift.ly)|[Group Discussion](https://groups.google.com/forum/#!msg/gtfs-realtime/mmnZV6L-2ls/wVWdknhLBwAJ)|
+|1010|IBI Group|[Ritesh Warade](mailto:transitrealtime@ibigroup.com)|[GitHub proposal for new timestamps in Service Alerts](https://github.com/google/transit/pull/134)|
diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto
index 76057b9d4..627010e81 100644
--- a/gtfs-realtime/proto/gtfs-realtime.proto
+++ b/gtfs-realtime/proto/gtfs-realtime.proto
@@ -51,7 +51,7 @@ message FeedMessage {
// Metadata about a feed, included in feed messages.
message FeedHeader {
// Version of the feed specification.
- // The current version is 2.0.
+ // The current version is 2.0. Valid versions are "2.0", "1.0".
required string gtfs_realtime_version = 1;
// Determines whether the current fetch is incremental. Currently,
@@ -415,6 +415,7 @@ message Alert {
OTHER_EFFECT = 7;
UNKNOWN_EFFECT = 8;
STOP_MOVED = 9;
+ NO_EFFECT = 10;
}
optional Effect effect = 7 [default = UNKNOWN_EFFECT];
@@ -427,6 +428,25 @@ message Alert {
// Full description for the alert as plain-text. The information in the
// description should add to the information of the header.
optional TranslatedString description_text = 11;
+
+ // Text for alert header to be used in text-to-speech implementations. This field is the text-to-speech version of header_text.
+ // This field is still experimental, and subject to change. It may be formally adopted in the future.
+ optional TranslatedString tts_header_text = 12;
+
+ // Text for full description for the alert to be used in text-to-speech implementations. This field is the text-to-speech version of description_text.
+ // This field is still experimental, and subject to change. It may be formally adopted in the future.
+ optional TranslatedString tts_description_text = 13;
+
+ // Severity of this alert.
+ // This field is still experimental, and subject to change. It may be formally adopted in the future.
+ enum SeverityLevel {
+ UNKNOWN_SEVERITY = 1;
+ INFO = 2;
+ WARNING = 3;
+ SEVERE = 4;
+ }
+
+ optional SeverityLevel severity_level = 14 [default = UNKNOWN_SEVERITY];
// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features
diff --git a/gtfs-realtime/spec/en/examples/alerts.asciipb b/gtfs-realtime/spec/en/examples/alerts.asciipb
index 601bfd061..b30316e54 100644
--- a/gtfs-realtime/spec/en/examples/alerts.asciipb
+++ b/gtfs-realtime/spec/en/examples/alerts.asciipb
@@ -1,6 +1,6 @@
# header information
header {
- # version of speed specification. Currently "2.0"
+ # version of speed specification. Currently "2.0". Valid versions are "2.0", "1.0".
gtfs_realtime_version: "2.0"
# determines whether dataset is incremental or full
diff --git a/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb b/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb
index 3dd58a988..fe0755c68 100644
--- a/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb
+++ b/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb
@@ -1,6 +1,6 @@
# header information
header {
- # version of speed specification. Currently "2.0"
+ # version of speed specification. Currently "2.0". Valid versions are "2.0", "1.0".
gtfs_realtime_version: "2.0"
# determines whether dataset is incremental or full
incrementality: FULL_DATASET
diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md
index a4a918809..3fca21224 100644
--- a/gtfs-realtime/spec/en/reference.md
+++ b/gtfs-realtime/spec/en/reference.md
@@ -1,6 +1,6 @@
A GTFS Realtime feed lets transit agencies provide consumers with realtime information about disruptions to their service (stations closed, lines not operating, important delays, etc.) location of their vehicles, and expected arrival times.
-Version 2.0 of the feed specification is discussed and documented on this site.
+Version 2.0 of the feed specification is discussed and documented on this site. Valid versions are "2.0", "1.0".
### Term Definitions
@@ -66,6 +66,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad
* [Effect](#enum-effect)
* [TranslatedString](#message-translatedstring)
* [Translation](#message-translation)
+ * [SeverityLevel](#enum-severitylevel)
# Elements
@@ -265,6 +266,9 @@ An alert, indicating some sort of incident in the public transit network.
| **url** | [TranslatedString](#message-translatedstring) | Optional | One | The URL which provides additional information about the alert. |
| **header_text** | [TranslatedString](#message-translatedstring) | Required | One | Header for the alert. This plain-text string will be highlighted, for example in boldface. |
| **description_text** | [TranslatedString](#message-translatedstring) | Required | One | Description for the alert. This plain-text string will be formatted as the body of the alert (or shown on an explicit "expand" request by the user). The information in the description should add to the information of the header. |
+| **tts_header_text** | [TranslatedString](#message-translatedstring) | Optional | One | Text containing the alert's header to be used for text-to-speech implementations. This field is the text-to-speech version of header_text. It should contain the same information as header_text but formatted such that it can read as text-to-speech (for example, abbreviations removed, numbers spelled out, etc.) **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
+| **tts_description_text** | [TranslatedString](#message-translatedstring) | Optional | One | Text containing a description for the alert to be used for text-to-speech implementations. This field is the text-to-speech version of description_text. It should contain the same information as description_text but formatted such that it can be read as text-to-speech (for example, abbreviations removed, numbers spelled out, etc.) **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
+| **severity_level** | [SeverityLevel](#enum-severitylevel) | Optional | One | Severity of the alert.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
## _enum_ Cause
@@ -304,6 +308,21 @@ The effect of this problem on the affected entity.
| **OTHER_EFFECT** |
| **UNKNOWN_EFFECT** |
| **STOP_MOVED** |
+| **NO_EFFECT** |
+
+## _enum_ SeverityLevel
+
+The severity of the alert.
+
+**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
+
+#### Values
+| _**Value**_ |
+|-------------|
+| **UNKNOWN_SEVERITY** |
+| **INFO** |
+| **WARNING** |
+| **SEVERE** |
## _message_ TimeRange
diff --git a/gtfs-realtime/spec/en/service-alerts.md b/gtfs-realtime/spec/en/service-alerts.md
index bc6f58d28..37c2e30bc 100644
--- a/gtfs-realtime/spec/en/service-alerts.md
+++ b/gtfs-realtime/spec/en/service-alerts.md
@@ -54,7 +54,8 @@ What effect does this problem have on the specified entity? You may specify one
* Significant delays (insignificant delays should only be provided through [Trip updates](trip-updates.md)).
* Detour
* Additional service
-* Modified service
+* Modified service: Operations are different from what the rider would normally expect. An example is an alert that reminds riders of an upcoming holiday schedule that is different from normal service on that day of the week.
* Stop moved
* Other effect (not represented by any of these options)
* Unknown effect
+* No effect: The alert provides information to riders but does not affect operations. Examples include advertising public meetings and soliciting feedback via surveys.
diff --git a/gtfs/CHANGES.md b/gtfs/CHANGES.md
index f5a808390..b967fdd60 100644
--- a/gtfs/CHANGES.md
+++ b/gtfs/CHANGES.md
@@ -6,30 +6,30 @@ The official specification, reference and documentation are written in English.
1. Create a git branch with update of all relevant parts of protocol definition, specification and documentation files (except for translations).
1. Create pull request on https://github.com/google/transit. Pull request must contain an extended description of the patch. The creator of the pull request becomes the _advocate_.
1. Once pull request is registered, it must be announced by its advocate in the [GTFS Changes mailing list](https://groups.google.com/forum/#!forum/gtfs-changes), including a link to the pull request. Once announced, the pull request is considered a proposal. The pull request should also be edited to contain a link to the Google Groups announcement so they can easily be cross-referenced.
- - Since the advocate is a contributor, they must sign the [Contributor License Agreement](../CONTRIBUTING.md) before pull request can be accepted.
+ - Since the advocate is a contributor, they must sign the [Contributor License Agreement](../CONTRIBUTING.md) before pull request can be accepted.
1. The discussion of the proposal follows. Pull request comments should be used as the sole discussion forum.
- - The discussion lasts for as long as the advocate feels necessary, but must be at least 7 calendar days.
- - The advocate is responsible for timely update of the proposal (i.e. pull request) based on the comments for which they agree to.
- - At any point in time the advocate can claim proposal abandoned.
+ - The discussion lasts for as long as the advocate feels necessary, but must be at least 7 calendar days.
+ - The advocate is responsible for timely update of the proposal (i.e. pull request) based on the comments for which they agree to.
+ - At any point in time the advocate can claim proposal abandoned.
1. The advocate can call for a vote on a version of the proposal at any point in time following the initial 7-day interval required for discussion.
- - Before calling for a vote, at least one GTFS producer and one GTFS consumer should implement the proposed change. It is expected that the GTFS producer(s) include the change in a public-facing GTFS feed and provide a link to that data within the pull request comments, and that the GTFS consumer(s) provides a link in the pull request comments to an application that is utilizing the change in a non-trivial manner (i.e, it is supporting new or improved functionality).
+ - Before calling for a vote, at least one GTFS producer and one GTFS consumer should implement the proposed change. It is expected that the GTFS producer(s) include the change in a public-facing GTFS feed and provide a link to that data within the pull request comments, and that the GTFS consumer(s) provides a link in the pull request comments to an application that is utilizing the change in a non-trivial manner (i.e, it is supporting new or improved functionality).
1. Vote lasts the minimum period sufficient to cover 7 full calendar days and 5 full Swiss business days. Vote ends at 23:59:59 UTC.
- - The advocate should announce the specific end time at the start of the vote.
- - During voting period only editorial changes to the proposal are allowed (typos, wording may change as long as it does not change the meaning).
- - Anyone is allowed to vote yes/no in a form of comment to the pull request, and votes can be changed until the end of the voting period.
+ - The advocate should announce the specific end time at the start of the vote.
+ - During voting period only editorial changes to the proposal are allowed (typos, wording may change as long as it does not change the meaning).
+ - Anyone is allowed to vote yes/no in a form of comment to the pull request, and votes can be changed until the end of the voting period.
If a voter changes her vote, it is recommended to do it by updating the original vote comment by striking through the vote and writing the new vote.
- - Votes before the start of the voting period are not considered.
+ - Votes before the start of the voting period are not considered.
1. The proposal is accepted if there is a unanimous consensus yes with at least 3 votes.
- - The proposer's vote does not count towards the 3 vote total. For example, if Proposer X creates a pull request and votes yes, and User Y and Z vote yes, this is counted as 2 total yes votes.
- - Votes against shall be motivated, and ideally provide actionable feedback.
- - If the vote has failed, then the advocate may choose to continue work on the proposal, or to abandon the proposal.
+ - The proposer's vote does not count towards the 3 vote total. For example, if Proposer X creates a pull request and votes yes, and User Y and Z vote yes, this is counted as 2 total yes votes.
+ - Votes against shall be motivated, and ideally provide actionable feedback.
+ - If the vote has failed, then the advocate may choose to continue work on the proposal, or to abandon the proposal.
Either decision of the advocate must be announced in the mailing list.
- - If the advocate continues the work on proposal then a new vote can be called for at any point in time but no later than 30 calendar days after the end of the previous vote.
- - If a vote was not called within 30 calendar days from the original proposal or 30 calendar days since end of the previous vote, then the proposal is abandoned.
+ - If the advocate continues the work on proposal then a new vote can be called for at any point in time but no later than 30 calendar days after the end of the previous vote.
+ - If a vote was not called within 30 calendar days from the original proposal or 30 calendar days since end of the previous vote, then the proposal is abandoned.
1. If the proposal is abandoned, the corresponding pull request is closed.
1. If the proposal is accepted:
- - Google is committed to merging the voted upon version of the pull request (provided that the contributors have signed the [CLA](../CONTRIBUTING.md)), and performing the pull request within 5 business days.
- - Translations must not be included into the original pull request.
+ - Google is committed to merging the voted upon version of the pull request (provided that the contributors have signed the [CLA](../CONTRIBUTING.md)), and performing the pull request within 5 business days.
+ - Translations must not be included into the original pull request.
Google is responsible for eventually updating relevant translations into supported languages, but pure translation pull requests from the community are welcome and will be accepted as soon as all editorial comments are addressed.
1. The final result of the pull request (accepted or abandoned) should be announced on the same Google Groups thread where the pull request was originally announced.
@@ -50,6 +50,10 @@ Every new feature adds complexity to the creation and reading of feeds. Therefor
### Revision History
+#### January 17, 2019
+
+* Editorial and formatting changes for clarity. See [pull request](https://github.com/google/transit/pull/120).
+
#### August 22, 2018
* Added `feed_contact_email` and `feed_contact_url` fields in the `feed_info.txt` file. See [discussion](https://github.com/google/transit/pull/31).
diff --git a/gtfs/spec/en/examples/GoogleTransitExamples.md b/gtfs/spec/en/examples/GoogleTransitExamples.md
new file mode 100644
index 000000000..c6c58e370
--- /dev/null
+++ b/gtfs/spec/en/examples/GoogleTransitExamples.md
@@ -0,0 +1,211 @@
+## Introduction
+The fare\_attributes.txt and fare_rules.txt files in the [Google Transit Feed Specification](https://github.com/MobilityData/transit/blob/master/gtfs/spec/en/reference.md) can be confusing. The following examples work through different kinds of fare structures and show how to represent them in a Google transit feed.
+
+### Fare Examples
+
+* Example 1: All trips have the same fare, unlimited transfers
+* Example 2: All trips have the same fare, no transfers
+* Example 3: All trips have the same fare, transfers allowed
+* Example 4: Different pricing for local and express routes
+* Example 5: Buying a transfer increases the fare
+* Example 6: Fare depends on station pairs, how you get there doesn't matter
+* Example 7: Fare depends on zones
+
+### Example 1: All trips have the same fare, unlimited transfers
+
+
+Suppose Demo Transit Agency has the following fare structure:
+
+* riders pay $1.00 on boarding (`price`=`1.00`, `currency`=`USD`, `payment_method`=`0`)
+* a ticket is good for all vehicles and doesn't expire (`transfers` is empty)
+* passengers can ride as long as they like. (`transfer_duration` is omitted)
+
+Since all trips have the same fare, Demo Transit can omit fare_rules.txt.
+
+fare_attributes.txt
+
+| fare_id | price | currency_type | payment_method |transfers |
+|:-----|:-----|:-----|:-----|:-----|
+| only_fare | 1.00 | USD | 0 | |
+
+#### Calculating an adult fare
+The trip planner calculates a fare of $1.00 for each leg of the itinerary that includes a change of vehicle. However, unlimited transfers are permitted, so the trip planner only displays the lowest charge. Adult fare: $1.00
+
+
+
+### Example 2: All trips have the same fare, no transfers
+Suppose Demo Transit Agency has the following fare structure:
+
+* riders pay $1.00 on boarding (`price`=`1.00`, `currency`=`USD`, `payment_method`=`0`)
+* passengers can ride as long as they like. (`transfer_duration` is omitted)
+* any change in vehicles requires a new fare. (`transfers`=`0`)
+
+Since all trips have the same fare, Demo Transit can omit fare_rules.txt.
+
+fare_attributes.txt
+
+| fare_id | price | currency_type | payment_method | transfers |
+|:--------------|:----------|:-------------------|:--------------------|:--------------|
+| only_fare | 1.00 | USD | 0 | 0 |
+
+#### Calculating an adult fare
+The trip planner calculates a fare of $1.00 for each leg of the itinerary that includes a change of vehicle. So an itinerary that requires a change of buses would be $2.00.
+
+
+
+### Example 3: All trips have the same fare, transfers allowed
+Suppose Demo Transit Agency has the following fare structure:
+
+* riders pay $1 on boarding (`price`=`1.00`, `currency`=`USD`, `payment_method`=`0`)
+* unlimited transfers are allowed within 90 minutes (`transfers` is empty,`transfer_duration`=`5400`)
+
+Since all trips have the same fare, Demo Transit can omit fare_rules.txt.
+
+fare_attributes.txt
+
+| fare_id | price | currency_type | payment_method | transfers | transfer_duration |
+|:--------------|:----------|:-------------------|:--------------------|:--------------|:-----------------------|
+| only_fare | 1.00 | USD | 0 | | 5400 |
+
+#### Calculating an adult fare
+The trip planner calculates a fare of $1.00 for each leg of the itinerary that includes a change of vehicle. Then it calculates the time for the itinerary. If the itinerary time is less than 90 minutes, the fare is $1.00.
+
+
+
+### Example 4: Different pricing for local and express routes
+Suppose Demo Transit Agency has the following fare structure:
+
+* riders pay $1.75 on boarding local buses (route 1)
+* riders pay $5.00 on boarding express buses (routes 2 and 3)
+* transfers aren't allowed.
+
+Since some trips cost more than others, Demo Transit must include fare_rules.txt, and each route must have an entry to associate it with a fare.
+
+fare_attributes.txt
+
+| fare_id | price | currency_type | payment_method | transfers |
+|:--------------|:----------|:-------------------|:----------------|:--------------|
+| local_fare | 1.75 | USD | 0 | 0 | | express_fare | 5.00 | USD | 0 | 0 |
+
+fare_rules.txt
+
+| fare_id | route_id |
+|:-------------|:--------------|
+| local_fare | Route_1 |
+| express_fare | Route_2 |
+| express_fare | Route_3 |
+
+#### Calculating an adult fare
+The $5.00 fare is only applicable if you ride routes 2 or 3. The $1.75 fare only applies on route 1. If an itinerary uses routes 1 and 2, the fare is $6.75.
+
+
+
+### Example 5: Buying a transfer increases the fare
+Suppose Demo Transit Agency has the following fare structure:
+
+* riders pay $1.75 on boarding local buses
+* riders can pay an extra $0.25 on boarding to purchase a transfer
+* transfers purchased are valid for 90 minutes
+
+Since these rules apply to all trips, Demo Transit can omit fare_rules.txt.
+
+fare_attributes.txt
+
+| fare_id | price | currency_type | payment_method | transfers | transfer_duration |
+|:--------------|:----------|:-------------------|:--------------------|:--------------|:-----------------------|
+| simple_fare | 1.75 | USD | 0 | 0 | |
+| plustransfer_fare | 2.00 | USD | 0 | | 5400 |
+
+#### Calculating an adult fare
+Technically, both fares apply on itinerary that has no transfers. However, the trip planner always chooses the least expensive applicable fare:
+
+* For an itinerary with one transfer, `simple_fare` is $3.50 vs. $2.00 when a transfer is purchased. So the trip planner will report $2.00 fare on all itineraries that require a change of vehicle.
+* For an itinerary with no transfers, $1.75 fare is less than `plustransfer_fare` of $2.00. So if an itinerary doesn't require a change of vehicle, the fare is $1.75.
+
+
+
+### Example 6: Fare depends on station pairs, how you get there doesn't matter
+In this example only the entry and exit points from the system matter.
+
+To define this fare structure for the feed, each station must have its own unique zone ID defined in stops.txt. Each station is considered a single zone.
+
+The fare\_attributes.txt and fare\_rules.txt files define one row for each pair of stations.
+In fare\_attributes.txt, the `origin_id` and `destination_id` fields identify station pairs by zone ID.
+
+fare_attributes.txt
+
+| fare_id | price | currency_type | payment_method | transfers |
+|:--------------|:----------|:-------------------|:--------------------|:--------------|
+| S1\_to\_S2 | 1.75 | USD | 0 | |
+| S1\_to\_S3 | 3.25 | USD | 0 | |
+| S1\_to\_S4 | 4.55 | USD | 0 | |
+| ... | | | | |
+| S10\_to\_S1 | 5.65 | USD | 0 | |
+
+fare_rules.txt
+
+| fare_id | origin_id | destination_id |
+|:-------------|:---------------|:--------------------|
+| S1\_to\_S2 | S1 | S2 |
+| S1\_to\_S3 | S1 | S3 |
+| S1\_to\_S4 | S1 | S4 |
+| ... | | |
+| S10\_to\_S1 | S10 | S1 |
+
+#### Calculating an adult fare
+The trip planner calculates an itinerary, and then looks up the fare rules until it finds a matching origin/destination station pair.
+
+The public feed from [SF Bay Area BART](https://www.bart.gov/schedules/developers/gtfs) provides a real-world illustration of this type of fare structure.
+
+
+
+### Example 7: Fare depends on zones
+Suppose Demo Transit Agency has a concentric three-zone system, where fares depend on which zones a rider passes through during an itinerary.
+
+To define this fare structure for the feed, fare\_attributes.txt and fare\_rules.txt must contain a line for each possible combination of zones. For very complex cross-zone fare structures, it may be simpler to programmatically output fare\_rules.txt using origin and destination to define fares.
+
+fare_attributes.txt
+
+| fare_id | price | currency_type | payment_method | transfers |
+|:--------------|:----------|:-------------------|:--------------------|:--------------| | F1 | 4.15 | USD | 0 | |
+| F2 | 2.20 | USD | 0 | |
+| F3 | 2.20 | USD | 0 | |
+| F4 | 2.95 | USD | 0 | |
+| F5 | 1.25 | USD | 0 | |
+| F6 | 1.95 | USD | 0 | |
+| F7 | 1.95 | USD | 0 | |
+
+fare_rules.txt
+
+| fare_id | contains_id |
+|:-------------|:-----------------|
+| F1 | 1 |
+| F1 | 2 |
+| F1 | 3 |
+| F2 | 1 |
+| F2 | 2 |
+| F3 | 1 |
+| F3 | 3 |
+| F4 | 2 |
+| F4 | 3 |
+| F5 | 1 |
+| F6 | 2 |
+| F7 | 3 |
+
+
+#### Calculating an adult fare
+Let's look more closely at the definitions in fare_rules.txt.
+
+* F1 applies to any trip that passes through zones (1,2,3).
+* F2 applies to any trip that passes through zones (1,2).
+* F3 applies to any trip that passes through zones (1,3).
+* F4 applies to any trip that passes through zones (2,3).
+* F5 applies to any trip that passes through zone 1 only.
+* F6 applies to any trip that passes through zone 2 only.
+* F7 applies to any trip that passes through zone 3 only.
+
+The trip planner calculates an itinerary, and then looks up the fare rules to determine the fares that apply based on zone. Since F1 also includes travel in zone 1, only F4 ($2.95) applies to a trip from zone 2 to zone 3.
+
+A fare rule only applies when the set of zones passed through in an itinerary exactly matches the set specified by the fare rule. For a trip between zones 2 and 3, the trip planner reports $2.95 as the adult fare.
+
+The public feed from [Portland TriMet](http://developer.trimet.org/GTFS.shtml) provides a real-world illustration of this type of fare structure.
\ No newline at end of file
diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md
index bbe09d868..e8a225b6b 100644
--- a/gtfs/spec/en/reference.md
+++ b/gtfs/spec/en/reference.md
@@ -1,14 +1,14 @@
## General Transit Feed Specification Reference
-**Revised August 22, 2018. See [Revision History](../../CHANGES.md) for more details.**
+**Revised January 17, 2019. See [Revision History](../../CHANGES.md) for more details.**
-This document explains the types of files that comprise a GTFS transit feed and defines the fields used in all of those files.
+This document defines the format and structure of the files that comprise a GTFS dataset.
## Table of Contents
1. [Term Definitions](#term-definitions)
2. [Field Types](#field-types)
-3. [Feed Files](#feed-files)
+3. [Dataset Files](#dataset-files)
4. [File Requirements](#file-requirements)
5. [Field Definitions](#field-definitions)
- [agency.txt](#agencytxt)
@@ -29,67 +29,72 @@ This document explains the types of files that comprise a GTFS transit feed and
This section defines terms that are used throughout this document.
-* **Field required** - The field column must be included in your feed, and a value must be provided for each record. Some required fields permit an empty string as a value. To enter an empty string, just omit any text between the commas for that field. Note that 0 is interpreted as "a string of value 0", and is not an empty string. Please see the field definition for details.
-* **Field optional** - The field column may be omitted from your feed. If you choose to include an optional column, each record in your feed must have a value for that column. You may include an empty string as a value for records that do not have values for the column. Some optional fields permit an empty string as a value. To enter an empty string, just omit any text between the commas for that field. Note that 0 is interpreted as "a string of value 0", and is not an empty string.
-* **Field conditionally required** - This field or file is **required** under certain conditions, which are outlined in the field or file *Details*. Outside of these conditions, this field or file is optional.
-* **Dataset unique** - The field contains a value that maps to a single distinct entity within the column. For example, if a route is assigned the ID **1A**, then no other route may use that route ID. However, you may assign the ID **1A** to a location because locations are a different type of entity than routes.
+
+* **Dataset** - A complete set of files defined by this specification reference. Altering the dataset creates a new version of the dataset. Datasets should be published at a public, permanent URL, including the zip file name. (e.g., https://www.agency.org/gtfs/gtfs.zip).
+* **Record** - A basic data structure comprised of a number of different field values describing a single entity (e.g. transit agency, stop, route, etc.). Represented, in a table, as a row.
+* **Field** - A property of an object or entity. Represented, in a table, as a column.
+* **Field Value** - An individual entry in a field. Represented, in a table, as a single cell.
+* **Required** - The field must be included in the dataset, and a value must be provided in that field for each record. Some required fields permit an empty string as a value (denoted in this specification as empty). To enter an empty string, just omit any text between the commas for that field.
+* **Optional** - The field may be omitted from the dataset. If an optional column is included, some of the entries in that field may be empty strings. To enter an empty string, just omit any text between the commas for that field. Note that an omitted field is equivalent to a field that is entirely empty.
+* **Conditionally required** - The field or file is required under certain conditions, which are outlined in the field or file description. Outside of these conditions, this field or file is optional.
+* **Service day** - A service day is a time period used to indicate route scheduling. The exact definition of service day varies from agency to agency but service days often do not correspond with calendar days. A service day may exceed 24:00:00 if service begins on one day and ends on a following day. For example, service that runs from 08:00:00 on Friday to 02:00:00 on Saturday, could be denoted as running from 08:00:00 to 26:00:00 on a single service day.
## Field Types
-- **Color** - The field contains a color encoded as a six-digit hexadecimal number. Refer to https://htmlcolorcodes.com/ to generate a valid value (the leading "#" is not included). For example: "FFFFFF" for white, "000000" for black or "0039A6" for the A,C,E lines in NYMTA.
-- **Currency Code** - The field contains an ISO 4217 alphabetical currency code. For the list of current currency, please refer to http://en.wikipedia.org/wiki/ISO_4217. For example: "CAD" for Canadian dollars, "EUR" for euros or "JPY" for Japanese yen.
-- **Email** - The field contains an email address. For example: example@example.com.
-- **Enum** - The field contains a value from a set of predefined constants defined in the "Details" column. For example: the route_type field contains a "0" for tram, a "1" for subway...
-- **ID** - The field contains an identifier which uniquely identifies an entity (therefore is dataset unique). Its value is not aimed to be displayed to the user, and is a sequence of any UTF-8 characters, but using only printable ASCII characters is recommended.
-- **Language Code** - The field contains a IETF BCP 47 language code. For an introduction to IETF BCP 47, please refer to http://www.rfc-editor.org/rfc/bcp/bcp47.txt and http://www.w3.org/International/articles/language-tags/. For example: "en" for English, "en-US" for American English or "de" for German.
-- **Latitude** - The field contains the WGS84 latitude in decimal degrees. The value must be greater than or equal to -90.0 and less than or equal to 90.0. For example: "41.890169" for the Colosseum in Rome.
-- **Longitude** - The field contains the WGS84 longitude in decimal degrees. The value must be greater than or equal to -180.0 and less than or equal to 180.0. For example: "12.492269" for the Colosseum in Rome.
-- **Non-negative Float** - The field contains a non-negative floating point number (which includes 0).
-- **Non-negative Integer** - The field contains a non-negative whole number (which includes 0).
-- **Phone number** - The field contains a phone number.
-- **Date** - The field contains the service day in the YYYYMMDD format. E.g "20180913" for September 13th, 2018. Since time within a service day can be above 24:00:00, a service day often contains information for the subsequent day(s).
-- **Time** - The field contains the time in the HH:MM:SS format (H:MM:SS is also accepted). For example: "14:30:00" for 2:30PM or "25:35:00" for 1:35AM on the next day. The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.
-- **Text** - The field contains a string of UTF-8 characters, which is aimed to be displayed and which must therefore be human readable.
-- **Timezone** - The field contains a TZ timezone from the [TZ database](https://www.iana.org/time-zones). Timezone names never contain the space character but may contain an underscore. Refer to http://en.wikipedia.org/wiki/List_of_tz_zones for a list of valid values. For example: "Asia/Tokyo", "America/Los_Angeles" or "Africa/Cairo".
-- **URL** - The field contains a fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See http://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URL values.
-
-## Feed Files
-
-This specification defines the following files along with their associated content:
+- **Color** - A color encoded as a six-digit hexadecimal number. Refer to [https://htmlcolorcodes.com](https://htmlcolorcodes.com) to generate a valid value (the leading "#" is not included).
*Example: `FFFFFF` for white, `000000` for black or `0039A6` for the A,C,E lines in NYMTA.*
+- **Currency Code** - An ISO 4217 alphabetical currency code. For the list of current currency, refer to [https://en.wikipedia.org/wiki/ISO_4217#Active\_codes](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
*Example: `CAD` for Canadian dollars, `EUR` for euros or `JPY` for Japanese yen.*
+- **Date** - Service day in the YYYYMMDD format. Since time within a service day can be above 24:00:00, a service day often contains information for the subsequent day(s).
*Example: `20180913` for September 13th, 2018.*
+- **Email** - An email address.
*Example: `example@example.com`*
+- **Enum** - An option from a set of predefined constants defined in the "Description" column.
*Example: The `route_type` field contains a `0` for tram, a `1` for subway...*
+- **ID** - A sequence of any UTF-8 characters which uniquely identifies an entity, but does not necessarily identify a specific record in a table. IDs defined in one .txt file are often referenced in another .txt file. An ID field value is not aimed to be displayed to the user, and is a sequence of any UTF-8 characters, but using only printable ASCII characters is recommended.
*Example: The `stop_id` field in [stops.txt](#stopstxt) is a ID. The `stop_id` field in [stop_times.txt](#stop_timestxt) is an ID referencing `stops.stop_id`.*
+- **Language Code** - An IETF BCP 47 language code. For an introduction to IETF BCP 47, refer to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt](http://www.rfc-editor.org/rfc/bcp/bcp47.txt) and [http://www.w3.org/International/articles/language-tags/](http://www.w3.org/International/articles/language-tags/).
*Example: `en` for English, `en-US` for American English or `de` for German.*
+- **Latitude** - WGS84 latitude in decimal degrees. The value must be greater than or equal to -90.0 and less than or equal to 90.0. *
Example: `41.890169` for the Colosseum in Rome.*
+- **Longitude** - WGS84 longitude in decimal degrees. The value must be greater than or equal to -180.0 and less than or equal to 180.0.
*Example: `12.492269` for the Colosseum in Rome.*
+- **Non-negative Float** - A floating point number greater than or equal to 0.
+- **Non-negative Integer** - A integer greater than or equal to 0.
+- **Phone number** - A phone number.
+- **Time** - Time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.
*Example: `14:30:00` for 2:30PM or `25:35:00` for 1:35AM on the next day.*
+- **Text** - A string of UTF-8 characters, which is aimed to be displayed and which must therefore be human readable.
+- **Timezone** - TZ timezone from the [https://www.iana.org/time-zones](https://www.iana.org/time-zones). Timezone names never contain the space character but may contain an underscore. Refer to [http://en.wikipedia.org/wiki/List\_of\_tz\_zones](http://en.wikipedia.org/wiki/List\_of\_tz\_zones) for a list of valid values.
*Example: `Asia/Tokyo`, `America/Los_Angeles` or `Africa/Cairo`.*
+- **URL** - A fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See the following [http://www.w3.org/Addressing/URL/4\_URI\_Recommentations.html](http://www.w3.org/Addressing/URL/4\_URI\_Recommentations.html) for a description of how to create fully qualified URL values.
+
+## Dataset Files
+
+This specification defines the following files:
| Filename | Required | Defines |
| ------ | ------ | ------ |
-| [agency.txt](#agencytxt) | **Required** | One or more transit agencies that provide the data in this feed. |
-| [stops.txt](#stopstxt) | **Required** | Individual locations where vehicles pick up or drop off passengers. |
+| [agency.txt](#agencytxt) | **Required** | Transit agencies with service represented in this dataset. |
+| [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 occurs at specific time. |
-| [stop_times.txt](#stop_timestxt) | **Required** | Times that a vehicle arrives at and departs from individual stops for each trip. |
-| [calendar.txt](#calendartxt) | **Conditionally required** | Dates for service IDs using a weekly schedule. Specify when service starts and ends, as well as days of the week where service is available. This file is required unless all dates of service are defined in [calendar_dates.txt](#calendar_datestxt). |
-| [calendar_dates.txt](#calendar_datestxt) | **Conditionally required** | Exceptions for the service IDs defined in the [calendar.txt](#calendartxt) file. If [calendar.txt](#calendartxt) is omitted, then [calendar_dates.txt](#calendar_datestxt) is required and must contain all dates of service. |
-| [fare_attributes.txt](#fare_attributestxt) | Optional | Fare information for a transit organization's routes. |
-| [fare_rules.txt](#fare_rulestxt) | Optional | Rules for applying fare information for a transit organization's routes. |
-| [shapes.txt](#shapestxt) | Optional | Rules for drawing lines on a map to represent a transit organization's routes. |
-| [frequencies.txt](#frequenciestxt) | Optional | Headway (time between trips) for routes with variable frequency of 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. |
+| [calendar.txt](#calendartxt) | **Conditionally required** | Service dates specified using a weekly schedule with start and end dates. This file is required unless all dates of service are defined in [calendar_dates.txt](#calendar_datestxt). |
+| [calendar_dates.txt](#calendar_datestxt) | **Conditionally required** | Exceptions for the services defined in the [calendar.txt](#calendartxt). If [calendar.txt](#calendartxt) is omitted, then [calendar_dates.txt](#calendar_datestxt) is required and must contain all dates of service. |
+| [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. |
+| [shapes.txt](#shapestxt) | Optional | Rules for mapping vehicle travel paths, sometimes referred to as route alignments. |
+| [frequencies.txt](#frequenciestxt) | Optional | Headway (time between trips) for headway-based service or a compressed representation of fixed-schedule service. |
| [transfers.txt](#transferstxt) | Optional | Rules for making connections at transfer points between routes. |
-| [feed_info.txt](#feed_infotxt) | Optional | Additional information about the feed itself, including publisher, version, and expiration information. |
+| [feed_info.txt](#feed_infotxt) | Optional | Dataset metadata, including publisher, version, and expiration information. |
## File Requirements
-The following requirements apply to the format and contents of your files:
+The following requirements apply to the format and contents of the dataset files:
-* All files in a General Transit Feed Spec (GTFS) feed must be saved as comma-delimited text.
-* The first line of each file must contain field names. Each subsection of the [Field Definitions](#Field-Definitions) section corresponds to one of the files in a transit feed and lists the field names you may use in that file.
+* All files must be saved as comma-delimited text.
+* The first line of each file must contain field names. Each subsection of the [Field Definitions](#field-definitions) section corresponds to one of the files in a GTFS dataset and lists the field names that may be used in that file.
* All field names are case-sensitive.
* Field values may not contain tabs, carriage returns or new lines.
-* Field values that contain quotation marks or commas must be enclosed within quotation marks. In addition, each quotation mark in the field value must be preceded with a quotation mark. This is consistent with the manner in which Microsoft Excel outputs comma-delimited (CSV) files. For more information on the CSV file format, see http://tools.ietf.org/html/rfc4180.
+* Field values that contain quotation marks or commas must be enclosed within quotation marks. In addition, each quotation mark in the field value must be preceded with a quotation mark. This is consistent with the manner in which Microsoft Excel outputs comma-delimited (CSV) files. For more information on the CSV file format, see [http://tools.ietf.org/html/rfc4180](http://tools.ietf.org/html/rfc4180).
The following example demonstrates how a field value would appear in a comma-delimited file:
* **Original field value:** `Contains "quotes", commas and text`
* **Field value in CSV file:** `"Contains ""quotes"", commas and text"`
* Field values must not contain HTML tags, comments or escape sequences.
* Remove any extra spaces between fields or field names. Many parsers consider the spaces to be part of the value, which may cause errors.
* Each line must end with a CRLF or LF linebreak character.
-* Files should be encoded in UTF-8 to support all Unicode characters. Files that include the Unicode byte-order mark (BOM) character are acceptable. Please see the [Unicode FAQ](http://unicode.org/faq/utf_bom.html#BOM) for more information on the BOM character and UTF-8.
-* Zip the files in your feed.
+* Files should be encoded in UTF-8 to support all Unicode characters. Files that include the Unicode byte-order mark (BOM) character are acceptable. See [http://unicode.org/faq/utf_bom.html#BOM](http://unicode.org/faq/utf_bom.html#BOM) for more information on the BOM character and UTF-8.
+* All dataset files must be zipped together.
## Field Definitions
@@ -97,106 +102,71 @@ The following example demonstrates how a field value would appear in a comma-del
File: **Required**
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| agency_id | ID | Optional | The **agency_id** field contains an ID that uniquely identifies a transit agency. A transit feed may represent data from more than one agency. This field is optional for transit feeds that only contain data for a single agency. |
-| agency_name | Text | **Required** | The **agency_name** field contains the full name of the transit agency. Google Maps will display this name. |
-| agency_url | URL | **Required** | The **agency_url** field contains the URL of the transit agency. |
-| agency_timezone | Timezone | **Required** | The **agency_timezone** field contains the timezone where the transit agency is located. If multiple agencies are specified in the feed, each must have the same agency_timezone. |
-| agency_lang | Language code | Optional | The **agency_lang** field contains a language code specifying the primary language used by this transit agency. This setting helps GTFS consumers choose capitalization rules and other language-specific settings for the feed. |
-| agency_phone | Phone number | Optional | The **agency_phone field** contains a single voice telephone number for the specified agency. This field is a string value that presents the telephone number as typical for the agency's service area. It can and should contain punctuation marks to group the digits of the number. Dialable text (for example, TriMet's "503-238-RIDE") is permitted, but the field must not contain any other descriptive text. |
-| agency_fare_url | URL | Optional | The **agency_fare_url** specifies the URL of a web page that allows a rider to purchase tickets or other fare instruments for that agency online. |
-| agency_email | Email | Optional | Contains a single valid email address actively monitored by the agency’s customer service department. This email address will be considered a direct contact point where transit riders can reach a customer service representative at the agency. |
+| `agency_id` | ID | **Conditionally Required** | Identifies a transit brand which is often synonymous with a transit agency. Note that in some cases, such as when a single agency operates multiple separate services, agencies and brands are distinct. This document uses the term "agency" in place of "brand". A dataset may contain data from multiple agencies. This field is required when the dataset contains data for multiple transit agencies, otherwise it is optional. |
+| `agency_name` | Text | **Required** | Full name of the transit agency. |
+| `agency_url` | URL | **Required** | URL of the transit agency. |
+| `agency_timezone` | Timezone | **Required** | Timezone where the transit agency is located. If multiple agencies are specified in the dataset, each must have the same `agency_timezone`. |
+| `agency_lang` | Language code | Optional | Primary language used by this transit agency. This field helps GTFS consumers choose capitalization rules and other language-specific settings for the dataset. |
+| `agency_phone` | Phone number | Optional | A voice telephone number for the specified agency. This field is a string value that presents the telephone number as typical for the agency's service area. It can and should contain punctuation marks to group the digits of the number. Dialable text (for example, TriMet's "503-238-RIDE") is permitted, but the field must not contain any other descriptive text. |
+| `agency_fare_url` | URL | Optional | URL of a web page that allows a rider to purchase tickets or other fare instruments for that agency online. |
+| `agency_email` | Email | Optional | Email address actively monitored by the agency’s customer service department. This email address should be a direct contact point where transit riders can reach a customer service representative at the agency. |
### stops.txt
File: **Required**
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| stop_id | ID | **Required** | The **stop_id** field contains an ID that uniquely identifies a stop, station, or station entrance. Multiple routes may use the same stop. |
-| stop_code | Text | Optional | The **stop_code** field contains short text or a number that uniquely identifies the stop for passengers. Stop codes are often used in phone-based transit information systems or printed on stop signage to make it easier for riders to get a stop schedule or real-time arrival information for a particular stop. The **stop_code** field contains short text or a number that uniquely identifies the stop for passengers. The **stop_code** can be the same as **stop_id** if it is passenger-facing. This field should be left blank for stops without a code presented to passengers. |
-| stop_name | Text | **Required** | The **stop_name** field contains the name of a stop, station, or station entrance. Please use a name that people will understand in the local and tourist vernacular. |
-| stop_desc | Text | Optional | The **stop_desc** field contains a description of a stop. Please provide useful, quality information. Do not simply duplicate the name of the stop. |
-| stop_lat | Latitude | **Required** | The **stop_lat** field contains the latitude of a stop, station, or station entrance. |
-| stop_lon | Longitude | **Required** | The **stop_lon** field contains the longitude of a stop, station, or station entrance. |
-| zone_id | ID | Optional | The **zone_id** field defines the fare zone for a stop ID. Zone IDs are required if you want to provide fare information using [fare_rules.txt](#fare_rulestxt). If this stop ID represents a station, the zone ID is ignored. |
-| stop_url | URL | Optional | The **stop_url** field contains the URL of a web page about a particular stop. This should be different from the agency_url and the route_url fields. |
-| location_type | Enum | Optional | The **location_type** field identifies whether this stop ID represents a stop, station, or station entrance. If no location type is specified, or the location_type is blank, stop IDs are treated as stops. Stations may have different properties from stops when they are represented on a map or used in trip planning. The location type field can have the following values: |
-| | | | * **0** or blank - Stop. A location where passengers board or disembark from a transit vehicle. |
-| | | | * **1** - Station. A physical structure or area that contains one or more stop. |
-| | | | * **2** - Station Entrance/Exit. A location where passengers can enter or exit a station from the street. The stop entry must also specify a parent_station value referencing the stop ID of the parent station for the entrance. |
-| parent_station | Enum | Optional | For stops that are physically located inside stations, the **parent_station** field identifies the station associated with the stop. To use this field, stops.txt must also contain a row where this stop ID is assigned location type=1. |
-| | | | • If this stop ID represents **a stop located inside a station**, this entry's location type must be **0 or blank**, and this entry's parent_station field contains **the stop ID of the station where this stop is located and the stop referenced by parent_station must have location_type=1.** |
-| | | | • If this stop ID represents **a stop located outside a station**, this entry's location type must be **0 or blank**, and this entry's parent_station field contains **a blank value (the parent_station field doesn't apply to this stop).** |
-| | | | • If this stop ID represents **a station**, this entry's location type must be **1**, and this entry's parent_station field contains **a blank value (stations can't contain other stations).** |
-| stop_timezone | Timezone | Optional | The **stop_timezone** field contains the timezone in which this stop, station, or station entrance is located. If omitted, the stop should be assumed to be located in the timezone specified by **agency_timezone** in [agency.txt](#agencytxt). When a stop has a parent station, the stop is considered to be in the timezone specified by the parent station's **stop_timezone** value. If the parent has no stop_timezone value, the stops that belong to that station are assumed to be in the timezone specified by **agency_timezone**, even if the stops have their own **stop_timezone** values. In other words, if a given stop has a **parent_station** value, any **stop_timezone** value specified for that stop must be ignored. Even if **stop_timezone** values are provided in stops.txt, the times in [stop_times.txt](#stop_timestxt) should continue to be specified as time since midnight in the timezone specified by **agency_timezone** in agency.txt. This ensures that the time values in a trip always increase over the course of a trip, regardless of which timezones the trip crosses. |
-| wheelchair_boarding | Enum | Optional | The **wheelchair_boarding field** identifies whether wheelchair boardings are possible from the specified stop, station, or station entrance. The field can have the following values: |
-| | | | * **0** (or empty) - indicates that there is no accessibility information for the stop |
-| | | | * **1** - indicates that at least some vehicles at this stop can be boarded by a rider in a wheelchair |
-| | | | * **2** - wheelchair boarding is not possible at this stop |
-| | | | When a stop is part of a larger station complex, as indicated by a stop with a **parent_station** value, the stop's **wheelchair_boarding** field has the following additional semantics: |
-| | | | * **0** (or empty) - the stop will inherit its **wheelchair_boarding** value from the parent station, if specified in the parent |
-| | | | * **1** - there exists some accessible path from outside the station to the specific stop / platform |
-| | | | * **2** - there exists no accessible path from outside the station to the specific stop / platform |
-| | | | For station entrances, the **wheelchair_boarding** field has the following additional semantics: |
-| | | | * **0** (or empty) - the station entrance will inherit its **wheelchair_boarding** value from the parent station, if specified in the parent |
-| | | | * **1** - the station entrance is wheelchair accessible (e.g. an elevator is available to platforms if they are not at-grade) |
-| | | | * **2** - there exists no accessible path from the entrance to station platforms |
+| `stop_id` | ID | **Required** | Identifies a stop, station, or station entrance. The term "station entrance" refers to both station entrances and station exits. Stops, stations or station entrances are collectively referred to as locations. Multiple routes may use the same stop. |
+| `stop_code` | Text | Optional | Short text or a number that identifies the location for riders. These codes are often used in phone-based transit information systems or printed on signage to make it easier for riders to get information for a particular location. The `stop_code` can be the same as `stop_id` if it is public facing. This field should be left empty for locations without a code presented to riders. |
+| `stop_name` | Text | **Required** | Name of the location. Use a name that people will understand in the local and tourist vernacular. |
+| `stop_desc` | Text | Optional | Description of the location that provides useful, quality information. Do not simply duplicate the name of the location. |
+| `stop_lat` | Latitude | **Required** | Latitude of the location. |
+| `stop_lon` | Longitude | **Required** | Longitude of the location. |
+| `zone_id` | ID | **Conditionally Required** | Identifies the fare zone for a stop. This field is required if providing fare information using [fare_rules.txt](#fare_rulestxt), otherwise it is optional. If this record represents a station or station entrance, the `zone_id` is ignored. |
+| `stop_url` | URL | Optional | URL of a web page about the location. This should be different from the `agency.agency_url` and the `routes.route_url` field values. |
+| `location_type` | Enum | Optional | Indicates whether this `stop_id` represents a stop, station, or station entrance/exit (denoted as station entrance in this document). If `location_type` is omitted, all locations are treated as stops. Valid options are:
`0` or empty - Stop. A location where riders board or disembark from a transit vehicle.
`1` - Station. A physical structure or area that contains one or more stop.
`2` - Station entrance. A point where riders can enter or exit a station from the street. The record must also specify a parent station by setting `parent_station` equal to the relevant `stop_id`. |
+| `parent_station` | ID referencing `stops.stop_id` | Optional | Identifies the station that a stop or station entrance is part of. This station-stop relationship, called a parent-child relationship, can only exist between a station (as the parent) and a stop or station entrance (as the child). These types are defined by location_type. If the stop or station identified in this record does not have a parent, leave `parent_station` empty. A station can never have a parent and a station entrance must always have a parent. |
+| `stop_timezone` | Timezone | Optional | Timezone of the location. If the location has a parent station, it inherits the parent station’s timezone instead of applying its own. Stations and parentless stops with empty `stop_timezone` inherit the timezone specified by `agency.agency_timezone`. If `stop_timezone` values are provided, the times in [stop_times.txt](#stop_timetxt) should be entered as the time since midnight in the timezone specified by `agency.agency_timezone`. This ensures that the time values in a trip always increase over the course of a trip, regardless of which timezones the trip crosses. |
+| `wheelchair_boarding` | Enum | Optional | Indicates whether wheelchair boardings are possible from the location. Valid options are:
For parentless stops:
`0` or empty - No accessibility information for the stop.
`1` - Some vehicles at this stop can be boarded by a rider in a wheelchair.
`2` - Wheelchair boarding is not possible at this stop.
For child stops:
`0` or empty - Stop will inherit its `wheelchair_boarding` behavior from the parent station, if specified in the parent.
`1` - There exists some accessible path from outside the station to the specific stop/platform.
`2` - There exists no accessible path from outside the station to the specific stop/platform.
For station entrances/exits:
`0` or empty - Station entrance will inherit its `wheelchair_boarding` behavior from the parent station, if specified for the parent.
`1` - Station entrance is wheelchair accessible.
`2` - No accessible path from station entrance to stops/platforms. |
### routes.txt
File: **Required**
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| route_id | ID | **Required** | The **route_id** field contains an ID that uniquely identifies a route. |
-| agency_id | ID | Optional | The **agency_id** field defines an agency for the specified route. This value is referenced from the [agency.txt](#agencytxt) file. Use this field when you are providing data for routes from more than one agency. |
-| route_short_name | Text | **Conditionally required** | The **route_short_name** contains the short name of a route. This will often be a short, abstract identifier like "32", "100X", or "Green" that riders use to identify a route, but which doesn't give any indication of what places the route serves. At least one of *route_short_name* or *route_long_name* must be specified, or potentially both if appropriate. If the route does not have a short name, please specify a *route_long_name* and use an empty string as the value for this field. |
-| route_long_name | Text | **Conditionally required** | The **route_long_name** contains the full name of a route. This name is generally more descriptive than the *route_short_name* and will often include the route's destination or stop. At least one of *route_short_name* or *route_long_name* must be specified, or potentially both if appropriate. If the route does not have a long name, please specify a *route_short_nam*e and use an empty string as the value for this field. |
-| route_desc | Text | Optional | The **route_desc** field contains a description of a route. Please provide useful, quality information. Do not simply duplicate the name of the route. For example, "**A** trains operate between Inwood-207 St, Manhattan and Far Rockaway-Mott Avenue, Queens at all times. Also from about 6AM until about midnight, additional **A** trains operate between Inwood-207 St and Lefferts Boulevard (trains typically alternate between Lefferts Blvd and Far Rockaway)." |
-| route_type | Enum | **Required** | The **route_type** field describes the type of transportation used on a route. Valid values for this field are: |
-| | | | * **0** - Tram, Streetcar, Light rail. Any light rail or street level system within a metropolitan area. |
-| | | | * **1** - Subway, Metro. Any underground rail system within a metropolitan area. |
-| | | | * **2** - Rail. Used for intercity or long-distance travel. |
-| | | | * **3** - Bus. Used for short- and long-distance bus routes. |
-| | | | * **4** - Ferry. Used for short- and long-distance boat service. |
-| | | | * **5** - Cable car. Used for street-level cable cars where the cable runs beneath the car. |
-| | | | * **6** - Gondola, Suspended cable car. Typically used for aerial cable cars where the car is suspended from the cable. |
-| | | | * **7** - Funicular. Any rail system designed for steep inclines. |
-| route_url | URL | Optional | The **route_url** field contains the URL of a web page about that particular route. This should be different from the agency_url. |
-| route_color | Color | Optional | In systems that have colors assigned to routes, the **route_color** field defines a color that corresponds to a route. If no color is specified, the default route color is white (FFFFFF). The color difference between **route_color** and **route_text_color** should provide sufficient contrast when viewed on a black and white screen. The [W3C Techniques for Accessibility Evaluation And Repair Tools document](https://www.w3.org/TR/AERT#color-contrast) offers a useful algorithm for evaluating color contrast. There are also helpful online tools for choosing contrasting colors, including the [snook.ca Color Contrast Check application](http://snook.ca/technical/colour_contrast/colour.html#fg=33FF33,bg=333333). |
-| route_text_color | Color | Optional | The **route_text_color** field can be used to specify a legible color to use for text drawn against a background of route_color. If no color is specified, the default text color is black (000000). The color difference between **route_color** and **route_text_color** should provide sufficient contrast when viewed on a black and white screen. |
-| route_sort_order | Non-negative integer | Optional | The **route_sort_order** field can be used to order the routes in a way which is ideal for presentation to customers. It must be a non-negative integer. Routes with smaller **route_sort_order** values should be displayed before routes with larger **route_sort_order** values. |
+| `route_id` | ID | **Required** | Identifies a route. |
+| `agency_id` | ID referencing `agency.agency_id` | **Conditionally required** | Agency for the specified route. This field is required when the dataset provides data for routes from more than one agency in [agency.txt](#agency), otherwise it is optional. |
+| `route_short_name` | Text | **Conditionally required** | Short name of a route. This will often be a short, abstract identifier like "32", "100X", or "Green" that riders use to identify a route, but which doesn't give any indication of what places the route serves. Either `route_short_name` or `route_long_name` must be specified, or potentially both if appropriate. |
+| `route_long_name` | Text | **Conditionally required** | Full name of a route. This name is generally more descriptive than the `route_short_name` and often includes the route's destination or stop. Either `route_short_name` or `route_long_name` must be specified, or potentially both if appropriate. |
+| `route_desc` | Text | Optional | Description of a route that provides useful, quality information. Do not simply duplicate the name of the route.
_Example: "A" trains operate between Inwood-207 St, Manhattan and Far Rockaway-Mott Avenue, Queens at all times. Also from about 6AM until about midnight, additional "A" trains operate between Inwood-207 St and Lefferts Boulevard (trains typically alternate between Lefferts Blvd and Far Rockaway)._ |
+| `route_type` | Enum | **Required** | Indicates the type of transportation used on a route. Valid options are:
`0` - Tram, Streetcar, Light rail. Any light rail or street level system within a metropolitan area.
`1` - Subway, Metro. Any underground rail system within a metropolitan area.
`2` - Rail. Used for intercity or long-distance travel.
`3` - Bus. Used for short- and long-distance bus routes.
`4` - Ferry. Used for short- and long-distance boat service.
`5` - Cable car. Used for street-level cable cars where the cable runs beneath the car.
`6` - Gondola, Suspended cable car. Typically used for aerial cable cars where the car is suspended from the cable.
`7` - Funicular. Any rail system designed for steep inclines. |
+| `route_url` | URL | Optional | URL of a web page about the particular route. Should be different from the `agency.agency_url` value. |
+| `route_color` | Color | Optional | Route color designation that matches public facing material. Defaults to white (`FFFFFF`) when omitted or left empty. The color difference between `route_color` and `route_text_color` should provide sufficient contrast when viewed on a black and white screen. |
+| `route_text_color` | Color | Optional | Legible color to use for text drawn against a background of `route_color`. Defaults to black (`000000`) when omitted or left empty. The color difference between `route_color` and `route_text_color` should provide sufficient contrast when viewed on a black and white screen. |
+| `route_sort_order` | Non-negative integer | Optional | Orders the routes in a way which is ideal for presentation to customers. Routes with smaller `route_sort_order` values should be displayed first. |
### trips.txt
File: **Required**
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| route_id | ID | **Required** | The **route_id** field contains an ID that uniquely identifies a route. This value is referenced from the [routes.txt](#routestxt) file. |
-| service_id | ID | **Required** | The **service_id** contains an ID that uniquely identifies a set of dates when service is available for one or more routes. This value is referenced from the [calendar.txt](#calendartxt) or [calendar_dates.txt](#calendar_datestxt) file. |
-| trip_id | ID | **Required** | The **trip_id** field contains an ID that uniquely identifies a trip. |
-| trip_headsign | Text | Optional | The **trip_headsign** field contains the text that appears on a sign that identifies the trip's destination to passengers. Use this field to distinguish between different patterns of service in the same route. If the headsign changes during a trip, you can override the **trip_headsign** by specifying values for the **stop_headsign** field in [stop_times.txt](#stop_timestxt). |
-| trip_short_name | Text | Optional | The **trip_short_name** field contains the text that appears in schedules and sign boards to identify the trip to passengers, for example, to identify train numbers for commuter rail trips. If riders do not commonly rely on trip names, please leave this field blank. A **trip_short_name** value, if provided, should uniquely identify a trip within a service day; it should not be used for destination names or limited/express designations. |
-| direction_id | Enum | Optional | The **direction_id** field contains a binary value that indicates the direction of travel for a trip. Use this field to distinguish between bi-directional trips with the same **route_id**. This field is not used in routing; it provides a way to separate trips by direction when publishing time tables. You can specify names for each direction with the **trip_headsign** field. |
-| | | | * 0 - travel in one direction (e.g. outbound travel) |
-| | | | * 1 - travel in the opposite direction (e.g. inbound travel) |
-| | | | For example, you could use the *trip_headsign* and *direction_id* fields together to assign a name to travel in each direction for a set of trips. A [trips.txt](#tripstxt) file could contain these rows for use in time tables: |
-| | | | * `trip_id,...,trip_headsign,direction_id` |
-| | | | * `1234,...,Airport,0` |
-| | | | * `1505,...,Downtown,1` |
-| block_id | ID | Optional | The **block_id** field identifies the block to which the trip belongs. A block consists of a single trip or many sequential trips made using the same vehicle, defined by shared service day and block_id. A block_id can have trips with different service days, making distinct blocks. (See [example below](#example-showing-blocks-and-service-day)) |
-| shape_id | ID | Optional | The **shape_id** field contains an ID that defines a shape for the trip. This value is referenced from the [shapes.txt](#shapestxt) file. The shapes.txt file allows you to define how a line should be drawn on the map to represent a trip. |
-| wheelchair_accessible | Enum | Optional | * **0** (or empty) - indicates that there is no accessibility information for the trip |
-| | | | * **1** - indicates that the vehicle being used on this particular trip can accommodate at least one rider in a wheelchair |
-| | | | * **2** - indicates that no riders in wheelchairs can be accommodated on this trip |
-| bikes_allowed | Enum | Optional | 0 (or empty) - indicates that there is no bike information for the trip |
-| | | | * **1** - indicates that the vehicle being used on this particular trip can accommodate at least one bicycle |
-| | | | * **2** - indicates that no bicycles are allowed on this trip |
-
-#### Example showing blocks and service day
+| `route_id` | ID referencing `routes.route_id` | **Required** | Identifies a route. |
+| `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | **Required** | Identifies a set of dates when service is available for one or more routes. |
+| `trip_id` | ID | **Required** | Identifies a trip. |
+| `trip_headsign` | Text | Optional | Text that appears on signage identifying the trip's destination to riders. Use this field to distinguish between different patterns of service on the same route. If the headsign changes during a trip, `trip_headsign` can be overridden by specifying values for the `stop_times.stop_headsign`. |
+| `trip_short_name` | Text | Optional | Public facing text used to identify the trip to riders, for instance, to identify train numbers for commuter rail trips. If riders do not commonly rely on trip names, leave this field empty. A `trip_short_name` value, if provided, should uniquely identify a trip within a service day; it should not be used for destination names or limited/express designations. |
+| `direction_id` | Enum | Optional | Indicates the direction of travel for a trip. This field is not used in routing; it provides a way to separate trips by direction when publishing time tables. Valid options are:
`0` - Travel in one direction (e.g. outbound travel).
`1` - Travel in the opposite direction (e.g. inbound travel).
*Example: The `trip_headsign` and `direction_id` fields could be used together to assign a name to travel in each direction for a set of trips. A [trips.txt](#tripstxt) file could contain these records for use in time tables:*
`trip_id,...,trip_headsign,direction_id`
`1234,...,Airport,0`
`1505,...,Downtown,1` |
+| `block_id` | ID | Optional | Identifies the block to which the trip belongs. A block consists of a single trip or many sequential trips made using the same vehicle, defined by shared service days and `block_id`. A `block_id` can have trips with different service days, making distinct blocks. See the [example below](#example-showing-blocks-and-service-day) |
+| `shape_id` | ID referencing `shapes.shape_id` | Optional | Identifies a geospatial shape describing the vehicle travel path for a trip. |
+| `wheelchair_accessible` | Enum | Optional | Indicates wheelchair accessibility. Valid options are:
`0` or empty - No accessibility information for the trip.
`1` - Vehicle being used on this particular trip can accommodate at least one rider in a wheelchair.
`2` - No riders in wheelchairs can be accommodated on this trip. |
+| `bikes_allowed` | Enum | Optional | Indicates whether bikes are allowed. Valid options are:
`0` or empty - No bike information for the trip.
`1` - Vehicle being used on this particular trip can accommodate at least one bicycle.
`2` - No bicycles are allowed on this trip. |
+
+#### Example: Blocks and service day
The example below is valid, with distinct blocks every day of the week.
@@ -209,244 +179,152 @@ The example below is valid, with distinct blocks every day of the week.
| red | trip_5 | mon-tues-wed-thurs | red_loop | 21:00:00 | 21:50:00 |
Notes on above table:
-* On Friday into Saturday morning, for example, a single vehicle operates trip_1, trip_2, and trip_3 (10:00 PM through 12:55 AM). Note that the last trip occurs on Saturday, 12:00 AM to 12:55 AM, but is part of the Friday “service day” because the times are 24:00:00 to 24:55:00.
-* On Monday, Tuesday, Wednesday, and Thursday, a single vehicle operates trip_1, trip_4, and trip_5 in a block from 8:00 PM to 10:55 PM.
+
+* On Friday into Saturday morning, for example, a single vehicle operates `trip_1`, `trip_2`, and `trip_3` (10:00 PM through 12:55 AM). Note that the last trip occurs on Saturday, 12:00 AM to 12:55 AM, but is part of the Friday “service day” because the times are 24:00:00 to 24:55:00.
+* On Monday, Tuesday, Wednesday, and Thursday, a single vehicle operates `trip_1`, `trip_4`, and `trip_5` in a block from 8:00 PM to 10:55 PM.
### stop_times.txt
File: **Required**
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| trip_id | ID | **Required** | The **trip_id** field contains an ID that identifies a trip. This value is referenced from the [trips.txt](#tripstxt) file. |
-| arrival_time | Time | **Required** | The **arrival_time** specifies the arrival time at a specific stop for a specific trip on a route. The time is measured from "noon minus 12h" (effectively midnight, except for days on which daylight savings time changes occur) at the beginning of the service day. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. If you don't have separate times for arrival and departure at a stop, enter the same value for **arrival_time** and **departure_time**.
Scheduled stops where the vehicle strictly adheres to the specified arrival and departure times are timepoints. For example, if a transit vehicle arrives at a stop before the scheduled departure time, it will hold until the departure time. If this stop is not a timepoint, use either an empty string value for the **arrival_time** field or provide an interpolated time. Further, indicate that interpolated times are provided via the **timepoint** field with a value of zero. If interpolated times are indicated with **timepoint**=0, then time points must be indicated with a value of 1 for the **timepoint** field. Provide arrival times for all stops that are time points.
An arrival time must be specified for the first and the last stop in a trip. Times must be eight digits in HH:MM:SS format (H:MM:SS is also accepted, if the hour begins with 0). Do not pad times with spaces. The following columns list stop times for a trip and the proper way to express those times in the **arrival_time** field: | |
-| | | | **Time** => **arrival_time value** |
-| | | | 08:10:00 A.M. => 08:10:00 or 8:10:00 |
-| | | | 01:05:00 P.M. => 13:05:00 |
-| | | | 07:40:00 P.M. => 19:40:00 |
-| | | | 01:55:00 A.M. => 25:55:00 |
-| | | | **Note:** Trips that span multiple dates will have stop times greater than 24:00:00. For example, if a trip begins at 10:30:00 p.m. and ends at 2:15:00 a.m. on the following day, the stop times would be 22:30:00 and 26:15:00. Entering those stop times as 22:30:00 and 02:15:00 would not produce the desired results. |
-| departure_time | Time | **Required** | The **departure_time** specifies the departure time from a specific stop for a specific trip on a route. The time is measured from "noon minus 12h" (effectively midnight, except for days on which daylight savings time changes occur) at the beginning of the service day. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. If you don't have separate times for arrival and departure at a stop, enter the same value for **arrival_time** and **departure_time**.
Scheduled stops where the vehicle strictly adheres to the specified arrival and departure times are timepoints. For example, if a transit vehicle arrives at a stop before the scheduled departure time, it will hold until the departure time. If this stop is not a timepoint, use either an empty string value for the **departure_time** field or provide an interpolated time (further, indicate that interpolated times are provided via the **timepoint** field with a value of zero). If interpolated times are indicated with **timepoint**=0, then time points must be indicated with a value of 1 for the **timepoint** field. Provide departure times for all stops that are time points.
A departure time must be specified for the first and the last stop in a trip even if the vehicle does not allow boarding at the last stop. Times must be eight digits in HH:MM:SS format (H:MM:SS is also accepted, if the hour begins with 0). Do not pad times with spaces. The following columns list stop times for a trip and the proper way to express those times in the **departure_time** field: |
-| | | | **Time** => **departure_time value** |
-| | | | 08:10:00 A.M. => 08:10:00 or 8:10:00 |
-| | | | 01:05:00 P.M. => 13:05:00 |
-| | | | 07:40:00 P.M. => 19:40:00 |
-| | | | 01:55:00 A.M. => 25:55:00 |
-| | | | **Note:** Trips that span multiple dates will have stop times greater than 24:00:00. For example, if a trip begins at 10:30:00 p.m. and ends at 2:15:00 a.m. on the following day, the stop times would be 22:30:00 and 26:15:00. Entering those stop times as 22:30:00 and 02:15:00 would not produce the desired results. |
-| stop_id | ID | **Required** | The **stop_id** field contains an ID that uniquely identifies a stop. Multiple routes may use the same stop. The **stop_id** is referenced from the [stops.txt](#stopstxt) file. If **location_type** is used in [stops.txt](#stopstxt), all stops referenced in [stop_times.txt](#stop_timestxt) must have **location_type** of 0. Where possible, **stop_id** values should remain consistent between feed updates. In other words, stop A with **stop_id 1** should have **stop_id 1** in all subsequent data updates. If a stop is not a time point, enter blank values for **arrival_time** and **departure_time**. |
-| stop_sequence | Non-negative integer | **Required** | The **stop_sequence** field identifies the order of the stops for a particular trip. The values must increase along the trip. For example, the first stop on the trip could have a **stop_sequence** of 1, the second stop on the trip could have a **stop_sequence** of 23, the third stop could have a **stop_sequence** of 40, and so on. |
-| stop_headsign | Text | Optional | The **stop_headsign** field contains the text that appears on a sign that identifies the trip's destination to passengers. Use this field to override the default **trip_headsign** when the headsign changes between stops. If this headsign is associated with an entire trip, use **trip_headsign** instead. |
-| pickup_type | Enum | Optional | The **pickup_type** field indicates whether passengers are picked up at a stop as part of the normal schedule or whether a pickup at the stop is not available. This field also allows the transit agency to indicate that passengers must call the agency or notify the driver to arrange a pickup at a particular stop. Valid values for this field are: |
-| | | | * **0** - Regularly scheduled pickup |
-| | | | * **1** - No pickup available |
-| | | | * **2** - Must phone agency to arrange pickup |
-| | | | * **3** - Must coordinate with driver to arrange pickup |
-| | | | The default value for this field is **0**. |
-| drop_off_type | Enum | Optional | The **drop_off_type** field indicates whether passengers are dropped off at a stop as part of the normal schedule or whether a drop off at the stop is not available. This field also allows the transit agency to indicate that passengers must call the agency or notify the driver to arrange a drop off at a particular stop. Valid values for this field are: |
-| | | | * **0** - Regularly scheduled drop off |
-| | | | * **1** - No drop off available |
-| | | | * **2** - Must phone agency to arrange drop off |
-| | | | * **3** - Must coordinate with driver to arrange drop off |
-| | | | The default value for this field is **0**. |
-| shape_dist_traveled | Non-negative float | Optional | When used in the [stop_times.txt](#stop_timestxt) file, the **shape_dist_traveled** field positions a stop as a distance from the first shape point. The **shape_dist_traveled** field represents a real distance traveled along the route in units such as feet or kilometers. For example, if a bus travels a distance of 5.25 kilometers from the start of the shape to the stop, the **shape_dist_traveled** for the stop ID would be entered as "5.25". This information allows the trip planner to determine how much of the shape to draw when showing part of a trip on the map. The values used for **shape_dist_traveled** must increase along with **stop_sequence**: they cannot be used to show reverse travel along a route. The units used for **shape_dist_traveled** in the [stop_times.txt](#stop_timestxt) file must match the units that are used for this field in the shapes.txt file. |
-| timepoint | Enum | Optional | The timepoint field can be used to indicate if the specified arrival and departure times for a stop are strictly adhered to by the transit vehicle or if they are instead approximate and/or interpolated times. The field allows a GTFS producer to provide interpolated stop times that potentially incorporate local knowledge, but still indicate if the times are approximate. For stop-time entries with specified arrival and departure times, valid values for this field are: |
-| | | | * **empty** - Times are considered exact. |
-| | | | * **0** - Times are considered approximate. |
-| | | | * **1** - Times are considered exact. |
-| | | | For stop-time entries without specified arrival and departure times, feed consumers must interpolate arrival and departure times. Feed producers may optionally indicate that such an entry is not a timepoint (value=0) but it is an error to mark a entry as a timepoint (value=1) without specifying arrival and departure times. |
+| `trip_id` | ID referencing `trips.trip_id` | **Required** | Identifies a trip. |
+| `arrival_time` | Time | **Conditionally required** | Arrival time at a specific stop for a specific trip on a route. If there are not separate times for arrival and departure at a stop, enter the same value for `arrival_time` and `departure_time`. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.
Scheduled stops where the vehicle strictly adheres to the specified arrival and departure times are timepoints. If this stop is not a timepoint, use leave `arrival_time` empty or provide an interpolated time. Further, indicate that interpolated times are provided with `timepoint`=`0`. If interpolated times are indicated with `timepoint`=`0`, then time points must be indicated with `timepoint`=`1`. Provide arrival times for all stops that are time points. An arrival time must be specified for the first and the last stop in a trip. |
+| `departure_time` | Time | **Conditionally required** | Departure time from a specific stop for a specific trip on a route. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. If there are not separate times for arrival and departure at a stop, enter the same value for `arrival_time` and `departure_time`. See the `arrival_time` description for more details about using timepoints correctly. |
+| `stop_id` | ID referencing `stops.stop_id` | **Required** | Identifies the serviced stop. All stops serviced during a trip must have a record in [stop_times.txt](#stop_timestxt). Referenced locations must be stops, not stations or station entrances. A stop may be serviced multiple times in the same trip, and multiple trips and routes may service the same stop. |
+| `stop_sequence` | Non-negative integer | **Required** | Order of stops for a particular trip. The values must increase along the trip but do not need to be consecutive.
*Example: The first location on the trip could have a `stop_sequence`=`1`, the second location on the trip could have a `stop_sequence`=`23`, the third location could have a `stop_sequence`=`40`, and so on.* |
+| `stop_headsign` | Text | Optional | Text that appears on signage identifying the trip's destination to riders. This field overrides the default `trips.trip_headsign` when the headsign changes between stops. If the headsign is displayed for an entire trip, use `trips.trip_headsign` instead. |
+| `pickup_type` | Enum | Optional | Indicates drop off method. Valid options are:
`0` or empty - Regularly scheduled pickup.
`1` - No pickup available.
`2` - Must phone agency to arrange pickup.
`3` - Must coordinate with driver to arrange pickup. |
+| `drop_off_type` | Enum | Optional | Indicates pick up method. Valid options are:
`0` or empty - Regularly scheduled drop off.
`1` - No drop off available.
`2` - Must phone agency to arrange drop off.
`3` - Must coordinate with driver to arrange drop off. |
+| `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the associated shape, from the first stop to the stop specified in this record. This field specifies how much of the shape to draw between any two stops during a trip. Must be in the same units used in [shapes.txt](#shapestxt). Values used for `shape_dist_traveled` must increase along with `stop_sequence`; they cannot be used to show reverse travel along a route.
*Example: If a bus travels a distance of 5.25 kilometers from the start of the shape to the stop,`shape_dist_traveled`=`5.25`.*|
+| `timepoint` | Enum | Optional | Indicates if arrival and departure times for a stop are strictly adhered to by the vehicle or if they are instead approximate and/or interpolated times. This field allows a GTFS producer to provide interpolated stop-times, while indicating that the times are approximate. Valid options are:
`0` - Times are considered approximate.
`1` or empty - Times are considered exact. |
+
### calendar.txt
File: **Conditionally required**
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ |------ |
-| service_id | ID | **Required** | The **service_id** contains an ID that uniquely identifies a set of dates when service is available for one or more routes. Each service_id value can appear at most once in a calendar.txt file. This value is dataset unique. It is referenced by the [trips.txt](#tripstxt) file. |
-| monday | Enum | **Required** | The monday field contains a binary value that indicates whether the service is valid for all Mondays. |
-| | | | * A value of **1** indicates that service is available for all Mondays in the date range. (The date range is specified using the **start_date** and **end_date** fields.) |
-| | | | * A value of **0** indicates that service is not available on Mondays in the date range. |
-| | | | **Note:** You may list exceptions for particular dates, such as holidays, in the [calendar_dates.txt](#calendar_datestxt) file. |
-| tuesday | Enum | **Required** | The tuesday field contains a binary value that indicates whether the service is valid for all Tuesdays. |
-| | | | A value of **1** indicates that service is available for all Tuesdays in the date range. (The date range is specified using the **start_date** and **end_date** fields.) |
-| | | | A value of **0** indicates that service is not available on Tuesdays in the date range. |
-| | | | **Note:** You may list exceptions for particular dates, such as holidays, in the [calendar_dates.txt](#calendar_datestxt) file. |
-| wednesday | Enum | **Required** | The wednesday field contains a binary value that indicates whether the service is valid for all Wednesdays. |
-| | | | A value of **1** indicates that service is available for all Wednesdays in the date range. (The date range is specified using the **start_date** and **end_date** fields.) |
-| | | | A value of **0** indicates that service is not available on Wednesdays in the date range. |
-| | | | **Note:** You may list exceptions for particular dates, such as holidays, in the [calendar_dates.txt](#calendar_datestxt) file. |
-| thursday | Enum | **Required** | The thursday field contains a binary value that indicates whether the service is valid for all Thursdays. |
-| | | | A value of **1** indicates that service is available for all Thursdays in the date range. (The date range is specified using the **start_date** and **end_date** fields.) |
-| | | | A value of **0** indicates that service is not available on Thursdays in the date range. |
-| | | | **Note:** You may list exceptions for particular dates, such as holidays, in the [calendar_dates.txt](#calendar_datestxt) file. |
-| friday | Enum | **Required** | The friday field contains a binary value that indicates whether the service is valid for all Fridays. |
-| | | | A value of **1** indicates that service is available for all Fridays in the date range. (The date range is specified using the **start_date** and **end_date** fields.) |
-| | | | A value of **0** indicates that service is not available on Fridays in the date range. |
-| | | | **Note:** You may list exceptions for particular dates, such as holidays, in the [calendar_dates.txt](#calendar_datestxt) file |
-| saturday | Enum | **Required** | The saturday field contains a binary value that indicates whether the service is valid for all Saturdays. |
-| | | | A value of **1** indicates that service is available for all Saturdays in the date range. (The date range is specified using the **start_date** and **end_date** fields.) |
-| | | | A value of **0** indicates that service is not available on Saturdays in the date range. |
-| | | | **Note:** You may list exceptions for particular dates, such as holidays, in the [calendar_dates.txt](#calendar_datestxt) file. |
-| sunday | Enum | **Required** | The sunday field contains a binary value that indicates whether the service is valid for all Sundays. |
-| | | | A value of **1** indicates that service is available for all Sundays in the date range. (The date range is specified using the **start_date** and **end_date** fields.) |
-| | | | A value of **0** indicates that service is not available on Sundays in the date range. |
-| | | | **Note:** You may list exceptions for particular dates, such as holidays, in the [calendar_dates.txt](#calendar_datestxt) file. |
-| start_date | Date | **Required** | The **start_date** field contains the start date for the service. The start_date field's value should be in YYYYMMDD format. |
-| end_date | Date | **Required** | The **end_date** field contains the end date for the service. This date is included in the service interval. The **end_date** field's value should be in YYYYMMDD format. |
+| `service_id` | ID | **Required** | Uniquely identifies a set of dates when service is available for one or more routes. Each `service_id` value can appear at most once in a [calendar.txt](#calendartxt) file. |
+| `monday` | Enum | **Required** | Indicates whether the service operates on all Mondays in the date range specified by the `start_date` and `end_date` fields. Note that exceptions for particular dates may be listed in [calendar_dates.txt](#calendar_datestxt). Valid options are:
`1` - Service is available for all Mondays in the date range.
`0` - Service is not available for Mondays in the date range. |
+| `tuesday` | Enum | **Required** | Functions in the same way as `monday` except applies to Tuesdays |
+| `wednesday` | Enum | **Required** | Functions in the same way as `monday` except applies to Wednesdays |
+| `thursday` | Enum | **Required** | Functions in the same way as `monday` except applies to Thursdays |
+| `friday` | Enum | **Required** | Functions in the same way as `monday` except applies to Fridays |
+| `saturday` | Enum | **Required** | Functions in the same way as `monday` except applies to Saturdays. |
+| `sunday` | Enum | **Required** | Functions in the same way as `monday` except applies to Sundays. |
+| `start_date` | Date | **Required** | Start service day for the service interval. |
+| `end_date` | Date | **Required** | End service day for the service interval. This service day is included in the interval. |
### calendar_dates.txt
File: **Conditionally required**
-The calendar_dates table allows you to explicitly activate or disable service IDs by date. You can use it in two ways.
+The [calendar_dates.txt](#calender_datestxt) table can explicitly activate or disable service by date. It can be used in two ways.
-* Recommended: Use calendar_dates.txt in conjunction with [calendar.txt](#calendartxt), where calendar_dates.txt defines any exceptions to the default service categories defined in the [calendar.txt](#calendartxt) file. If your service is generally regular, with a few changes on explicit dates (for example, to accommodate special event services, or a school schedule), this is a good approach.
-* Alternate: Omit [calendar.txt](#calendartxt), and include ALL dates of service in calendar_dates.txt. If your schedule varies most days of the month, or you want to programmatically output service dates without specifying a normal weekly schedule, this approach may be preferable.
+* Recommended: Use [calendar_dates.txt](#calender_datestxt) in conjunction with [calendar.txt](#calendartxt) to define exceptions to the default service patterns defined in [calendar.txt](#calendartxt). If service is generally regular, with a few changes on explicit dates (for instance, to accommodate special event services, or a school schedule), this is a good approach. In this case `calendar_dates.service_id` is an ID referencing `calendar.service_id`.
+* Alternate: Omit [calendar.txt](#calendartxt), and specify each date of service in [calendar_dates.txt](#calenderdatestxt). This allows for considerable service variation and accommodates service without normal weekly schedules. In this case `service_id` is an ID.
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| service_id | ID | **Required** | The **service_id** contains an ID that uniquely identifies a set of dates when a service exception is available for one or more routes. Each (service_id, date) pair can only appear once in calendar_dates.txt. If the a service_id value appears in both the calendar.txt and calendar_dates.txt files, the information in calendar_dates.txt modifies the service information specified in [calendar.txt](#calendartxt). This field is referenced by the [trips.txt](#tripstxt) file. |
-| date | Date | **Required** | The **date** field specifies a particular date when service availability is different than the norm. You can use the **exception_type** field to indicate whether service is available on the specified date. The **date** field's value should be in YYYYMMDD format. |
-| exception_type | Enum | **Required** | The **exception_type** indicates whether service is available on the date specified in the date field. |
-| | | | * A value of **1** indicates that service has been added for the specified date. |
-| | | | * A value of **2** indicates that service has been removed for the specified date. |
-| | | | For example, suppose a route has one set of trips available on holidays and another set of trips available on all other days. You could have one **service_id** that corresponds to the regular service schedule and another **service_id** that corresponds to the holiday schedule. For a particular holiday, you would use the calendar_dates.txt file to add the holiday to the holiday **service_id** and to remove the holiday from the regular **service_id** schedule. |
+| `service_id` | ID referencing `calendar.service_id` or ID | **Required** | Identifies a set of dates when a service exception occurs for one or more routes. Each (`service_id`, `date`) pair can only appear once in [calendar_dates.txt](#calender_datestxt) if using [calendar.txt](#calendartxt) and [calendar_dates.txt](#calender_datestxt) in conjunction. If a `service_id` value appears in both [calendar.txt](#calendartxt) and [calendar_dates.txt](#calender_datestxt), the information in [calendar_dates.txt](#calenderdatestxt) modifies the service information specified in [calendar.txt](#calendartxt). |
+| `date` | Date | **Required** | Date when service exception occurs. |
+| `exception_type` | Enum | **Required** | Indicates whether service is available on the date specified in the date field. Valid options are:
`1` - Service has been added for the specified date.
`2` - Service has been removed for the specified date.
*Example: Suppose a route has one set of trips available on holidays and another set of trips available on all other days. One `service_id` could correspond to the regular service schedule and another `service_id` could correspond to the holiday schedule. For a particular holiday, the [calendar_dates.txt](#calender_datestxt) file could be used to add the holiday to the holiday `service_id` and to remove the holiday from the regular `service_id` schedule.* |
### fare_attributes.txt
File: **Optional**
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| fare_id | ID | **Required** | The **fare_id** field contains an ID that uniquely identifies a fare class. The **fare_id** is dataset unique. |
-| price | Non-negative float | **Required** | The **price** field contains the fare price, in the unit specified by **currency_type**. |
-| currency_type | Currency code | **Required** | The **currency_type** field defines the currency used to pay the fare. |
-| payment_method | Enum | **Required** | The **payment_method** field indicates when the fare must be paid. Valid values for this field are: |
-| | | | * **0** - Fare is paid on board. |
-| | | | * **1** - Fare must be paid before boarding. |
-| transfers | Enum | **Required** | The transfers field specifies the number of transfers permitted on this fare. Valid values for this field are: |
-| | | | * **0** - No transfers permitted on this fare. |
-| | | | * **1** - Passenger may transfer once. |
-| | | | * **2** - Passenger may transfer twice. |
-| | | | * **(empty)** - If this field is empty, unlimited transfers are permitted. |
-| agency_id | ID | Optional | Required for feeds with multiple agencies defined in the agency.txt file. Each fare attribute must specify an agency_id value to indicate which agency the fare applies to. |
-| transfer_duration | Non-negative integer | Optional | The **transfer_duration** field specifies the length of time in seconds before a transfer expires. When used with a **transfers** value of 0, the **transfer_duration** field indicates how long a ticket is valid for a fare where no transfers are allowed. Unless you intend to use this field to indicate ticket validity, **transfer_duration** should be omitted or empty when **transfers** is set to 0. |
+| `fare_id` | ID | **Required** | Identifies a fare class. |
+| `price` | Non-negative float | **Required** | Fare price, in the unit specified by `currency_type`. |
+| `currency_type` | Currency code | **Required** | Currency used to pay the fare. |
+| `payment_method` | Enum | **Required** | Indicates when the fare must be paid. Valid options are:
`0` - Fare is paid on board.
`1` - Fare must be paid before boarding. |
+| `transfers` | Enum | **Required** | Indicates the number of transfers permitted on this fare. The fact that this field can be left empty is an exception to the requirement that a Required field must not be empty. Valid options are:
`0` - No transfers permitted on this fare.
`1` - Riders may transfer once.
`2` - Riders may transfer twice.
empty - Unlimited transfers are permitted. |
+| `agency_id` | ID referencing `agency.agency_id` | **Conditionally Required** | Identifies the relevant agency for a fare. This field is required for datasets with multiple agencies defined in [agency.txt](#agencytxt), otherwise it is optional. |
+| `transfer_duration` | Non-negative integer | Optional | Length of time in seconds before a transfer expires. When `transfers`=`0` this field can be used to indicate how long a ticket is valid for or it can can be left empty. |
### fare_rules.txt
File: **Optional**
-The fare_rules table allows you to specify how fares in fare_attributes.txt apply to an itinerary. Most fare structures use some combination of the following rules:
+The [fare_rules.txt](#farerulestxt) table specifies how fares in [fare_attributes.txt](#fare_attributestxt) apply to an itinerary. Most fare structures use some combination of the following rules:
* Fare depends on origin or destination stations.
* Fare depends on which zones the itinerary passes through.
* Fare depends on which route the itinerary uses.
-For examples that demonstrate how to specify a fare structure with fare_rules.txt and fare_attributes.txt, see [FareExamples](https://code.google.com/p/googletransitdatafeed/wiki/FareExamples) in the GoogleTransitDataFeed open source project wiki.
+For examples that demonstrate how to specify a fare structure with [fare_rules.txt](#farerulestxt) and [fare_attributes.txt](#fareattributestxt), see [https://code.google.com/p/googletransitdatafeed/wiki/FareExamples](https://code.google.com/p/googletransitdatafeed/wiki/FareExamples) in the GoogleTransitDataFeed open source project wiki.
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| fare_id | ID | **Required** | The **fare_id** field contains an ID that uniquely identifies a fare class. This value is referenced from the [fare_attributes.txt](#fare_attributestxt) file. |
-| route_id | ID | Optional | The **route_id** field associates the fare ID with a route. Route IDs are referenced from the [routes.txt](#routestxt) file. If you have several routes with the same fare attributes, create a row in fare_rules.txt for each route. |
-| | | | For example, if fare class "b" is valid on route "TSW" and "TSE", the fare_rules.txt file would contain these rows for the fare class: |
-| | | | `b,TSW` |
-| | | | `b,TSE` |
-| origin_id | ID | Optional | The **origin_id** field associates the fare ID with an origin zone ID. Zone IDs are referenced from the [stops.txt](#stopstxt) file. If you have several origin IDs with the same fare attributes, create a row in fare_rules.txt for each origin ID. |
-| | | | For example, if fare class "b" is valid for all travel originating from either zone "2" or zone "8", the fare_rules.txt file would contain these rows for the fare class: |
-| | | | `b, , 2` |
-| | | | `b, , 8` |
-| destination_id | ID | Optional | The **destination_id** field associates the fare ID with a destination zone ID. Zone IDs are referenced from the [stops.txt](#stopstxt) file. If you have several destination IDs with the same fare attributes, create a row in fare_rules.txt for each destination ID. |
-| | | | For example, you could use the origin_ID and destination_ID fields 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 file would contain these rows for the fare class: |
-| | | | `b, , 3,4` |
-| | | | `b, , 3,5` |
-| contains_id | ID | Optional | The **contains_id** field associates the fare ID with a zone ID, referenced from the [stops.txt](#stopstxt) file. The fare ID is then associated with itineraries that pass through every contains_id zone. |
-| | | | For 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 would contain these rows: |
-| | | | `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 [FareExamples](https://code.google.com/p/googletransitdatafeed/wiki/FareExamples) in the GoogleTransitDataFeed project wiki. |
+| `fare_id` | ID referencing `fare_attributes.fare_id` | **Required** | Identifies a fare class. |
+| `route_id` | ID referencing `routes.routes_id` | Optional | Identifies a route associated with the fare class. If several routes with the same fare attributes exist, create a record in [fare_rules.txt](#fare_rules.txt) for each route.
*Example: If fare class "b" is valid on route "TSW" and "TSE", the [fare_rules.txt](#fare_rules.txt) file would contain these records for the fare class:*
` fare_id,route_id`
`b,TSW`
`b,TSE`|
+| `origin_id` | ID referencing `stops.zone_id` | Optional | Identifies an origin zone. If a fare class has multiple origin zones, create a record in [fare_rules.txt](#fare_rules.txt) for each `origin_id`.
*Example: If fare class "b" is valid for all travel originating from either zone "2" or zone "8", the [fare_rules.txt](#fare_rules.txt) file would contain these records for the fare class:*
`fare_id,...,origin_id`
`b,...,2`
`b,...,8` |
+| `destination_id` | 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` | 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:*
`zone_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.* |
### shapes.txt
File: **Optional**
-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.
+Shapes describe the physical path that a vehicle takes as a set of ordered latitude and longitude coordinates. Tracing the coordinates in order provides the vehicle's path. Coordinates do not need to match stop locations.
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| shape_id | ID | **Required** | The **shape_id** field contains an ID that uniquely identifies a shape. |
-| shape_pt_lat | Latitude | **Required** | The **shape_pt_lat** field associates a shape point's latitude with a shape ID. Each row in shapes.txt represents a shape point in your shape definition. |
-| | | | For example, if the shape "A_shp" has three points in its definition, the shapes.txt file might contain these rows to define the shape: |
-| | | | `A_shp,37.61956,-122.48161,0` |
-| | | | `A_shp,37.64430,-122.41070,6` |
-| | | | `A_shp,37.65863,-122.30839,11` |
-| shape_pt_lon | Longitude | **Required** | The **shape_pt_lon** field associates a shape point's longitude with a shape ID. Each row in shapes.txt represents a shape point in your shape definition. |
-| | | | For example, if the shape "A_shp" has three points in its definition, the shapes.txt file might contain these rows to define the shape: |
-| | | | `A_shp,37.61956,-122.48161,0` |
-| | | | `A_shp,37.64430,-122.41070,6` |
-| | | | `A_shp,37.65863,-122.30839,11` |
-| shape_pt_sequence | Non-negative integer | **Required** | The **shape_pt_sequence** field associates the latitude and longitude of a shape point with its sequence order along the shape. The values for **shape_pt_sequence** must increase along the trip. |
-| | | | For example, if the shape "A_shp" has three points in its definition, the shapes.txt file might contain these rows to define the shape: |
-| | | | `A_shp,37.61956,-122.48161,0` |
-| | | | `A_shp,37.64430,-122.41070,6` |
-| | | | `A_shp,37.65863,-122.30839,11` |
-| shape_dist_traveled | Non-negative float | Optional | When used in the shapes.txt file, the **shape_dist_traveled** field positions a shape point as a distance traveled along a shape from the first shape point. The **shape_dist_traveled** field represents a real distance traveled along the route in units such as feet or kilometers. This information allows the trip planner to determine how much of the shape to draw when showing part of a trip on the map. The values used for **shape_dist_traveled** must increase along with shape_pt_sequence: they cannot be used to show reverse travel along a route. |
-| | | | The units used for **shape_dist_traveled** in the shapes.txt file must match the units that are used for this field in the [stop_times.txt](#stop_timestxt) file. |
-| | | | For example, if a bus travels along the three points defined above for A_shp, the additional **shape_dist_traveled** values (shown here in kilometers) would look like this: |
-| | | | `A_shp,37.61956,-122.48161,0,0` |
-| | | | `A_shp,37.64430,-122.41070,6,6.8310` |
-| | | | `A_shp,37.65863,-122.30839,11,15.8765` |
+| `shape_id` | ID | **Required** | Identifies a shape. |
+| `shape_pt_lat` | Latitude | **Required** | Latitude of a shape point. Each record in [shapes.txt](#shapestxt) represents a shape point used to define the shape. |
+| `shape_pt_lon` | Longitude | **Required** | Longitude of a shape point. |
+| `shape_pt_sequence` | Non-negative integer | **Required** | Sequence in which the shape points connect to form the shape. Values must increase along the trip but do not need to be consecutive.
*Example: If the shape "A_shp" has three points in its definition, the [shapes.txt](#shapestxt) file might contain these records to define the shape:*
`shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence`
`A_shp,37.61956,-122.48161,0`
`A_shp,37.64430,-122.41070,6`
`A_shp,37.65863,-122.30839,11` |
+| `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the shape from the first shape point to the point specified in this record. Used by trip planners to show the correct portion of the shape on a map. Values must increase along with `shape_pt_sequence`; they cannot be used to show reverse travel along a route. Distance units must be consistent with those used in [stop_times.txt](#stop_timestxt).
*Example: If a bus travels along the three points defined above for A_shp, the additional `shape_dist_traveled` values (shown here in kilometers) would look like this:*
`shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled`
`A_shp,37.61956,-122.48161,0,0`
`A_shp,37.64430,-122.41070,6,6.8310`
`A_shp,37.65863,-122.30839,11,15.8765` |
### frequencies.txt
File: **Optional**
-This table is intended to represent schedules that don't have a fixed list of stop times. When trips are defined in frequencies.txt, the trip planner ignores the absolute values of the **arrival_time** and **departure_time** fields for those trips in [stop_times.txt](#stop_timestxt). Instead, the **stop_times** table defines the sequence of stops and the time difference between each stop.
+[Frequencies.txt](#frequenciestxt) represents trips that operate on regular headways (time between trips). This file can be used to represent two different types of service.
+
+* Frequency-based service (`exact_times`=`0`) in which service does not follow a fixed schedule throughout the the day. Instead, operators attempt to strictly maintain predetermined headways for trips.
+* A compressed representation of schedule-based service (`exact_times`=`1`) that has the exact same headway for trips over specified time period(s). In schedule-based service operators try to strictly adhere to a schedule.
+
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| trip_id | ID | **Required** | The **trip_id** contains an ID that identifies a trip on which the specified frequency of service applies. Trip IDs are referenced from the [trips.txt](#tripstxt) file. |
-| start_time | Time | **Required** | The **start_time** field specifies the time at which the first vehicle departs from the first stop of the trip with the specified frequency. The time is measured from "noon minus 12h" (effectively midnight, except for days on which daylight savings time changes occur) at the beginning of the service day. For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. E.g. 25:35:00. |
-| end_time | Time | **Required** | The **end_time** field indicates the time at which service changes to a different frequency (or ceases) at the first stop in the trip. The time is measured from "noon minus 12h" (effectively midnight, except for days on which daylight savings time changes occur) at the beginning of the service day. For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. E.g. 25:35:00. |
-| headway_secs | Non-negative integer | **Required** | The **headway_secs** field indicates the time between departures from the same stop (headway) for this trip type, during the time interval specified by **start_time** and **end_time**. The headway value must be entered in seconds. |
-| | | | Periods in which headways are defined (the rows in frequencies.txt) shouldn't overlap for the same trip, since it's hard to determine what should be inferred from two overlapping headways. However, a headway period may begin at the exact same time that another one ends, for instance: |
-| | | | `A, 05:00:00, 07:00:00, 600` |
-| | | | `B, 07:00:00, 12:00:00, 1200` |
-| exact_times | Enum | Optional | The **exact_times** field determines if frequency-based trips should be exactly scheduled based on the specified headway information. Valid values for this field are: |
-| | | | * **0** or **(empty)** - Frequency-based trips are not exactly scheduled. This is the default behavior. |
-| | | | * **1** - Frequency-based trips are exactly scheduled. For a frequencies.txt row, trips are scheduled starting with trip_start_time = start_time + x * headway_secs for all x in (0, 1, 2, ...) where trip_start_time < end_time. |
-| | | | The value of **exact_times** must be the same for all frequencies.txt rows with the same **trip_id**. If **exact_times** is 1 and a frequencies.txt row has a **start_time** equal to **end_time**, no trip must be scheduled. When **exact_times** is 1, care must be taken to choose an **end_time** value that is greater than the last desired trip start time but less than the last desired trip start time + **headway_secs**. |
+| `trip_id` | ID referencing `trips.trip_id` | **Required** | Identifies a trip to which the specified headway of service applies. |
+| `start_time` | Time | **Required** | Time at which the first vehicle departs from the first stop of the trip with the specified headway. |
+| `end_time` | Time | **Required** | Time at which service changes to a different headway (or ceases) at the first stop in the trip. |
+| `headway_secs` | Non-negative integer | **Required** | Time, in seconds, between departures from the same stop (headway) for the trip, during the time interval specified by `start_time` and `end_time`. Multiple headways for the same trip are allowed, but may not overlap. New headways may start at the exact time the previous headway ends. |
+| `exact_times` | Enum | Optional | Indicates the type of service for a trip. See the file description for more information. Valid options are:
`0` or empty - Frequency-based trips.
`1` - Schedule-based trips with the exact same headway throughout the day. In this case the `end_time` value must be greater than the last desired trip `start_time` but less than the last desired trip start_time + `headway_secs`. |
### transfers.txt
File: **Optional**
-Trip planners normally calculate transfer points based on the relative proximity of stops in each route. For potentially ambiguous stop pairs, or transfers where you want to specify a particular choice, use transfers.txt to define additional rules for making connections between routes.
+When calculating an itinerary, GTFS-consuming applications interpolate transfers based on allowable time and stop proximity. [Transfers.txt](#transferstxt) specifies additional rules and overrides for selected transfers.
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| from_stop_id | ID | **Required** | The **from_stop_id** field contains a stop ID that identifies a stop or station where a connection between routes begins. Stop IDs are referenced from the [stops.txt](#stopstxt) file. If the stop ID refers to a station that contains multiple stops, this transfer rule applies to all stops in that station. |
-| to_stop_id | ID | **Required** | The **to_stop_id** field contains a stop ID that identifies a stop or station where a connection between routes ends. Stop IDs are referenced from the [stops.txt](#stopstxt) file. If the stop ID refers to a station that contains multiple stops, this transfer rule applies to all stops in that station. |
-| transfer_type | Enum | **Required** | The **transfer_type** field specifies the type of connection for the specified (from_stop_id, to_stop_id) pair. Valid values for this field are: |
-| | | | * **0** or **(empty)** - This is a recommended transfer point between routes. |
-| | | | * **1** - This is a timed transfer point between two routes. The departing vehicle is expected to wait for the arriving one, with sufficient time for a passenger to transfer between routes. |
-| | | | * **2** - This transfer requires a minimum amount of time between arrival and departure to ensure a connection. The time required to transfer is specified by **min_transfer_time**. |
-| | | | * **3** - Transfers are not possible between routes at this location. |
-| min_transfer_time | Non-negative integer | Optional | When a connection between routes requires an amount of time between arrival and departure (transfer_type=2), the **min_transfer_time** field defines the amount of time that must be available in an itinerary to permit a transfer between routes at these stops. The min_transfer_time must be sufficient to permit a typical rider to move between the two stops, including buffer time to allow for schedule variance on each route. |
-| | | | The min_transfer_time value must be entered in seconds, and must be a non-negative integer. |
+| `from_stop_id` | ID referencing `stops.stop_id` | **Required** | Identifies a stop or station where a connection between routes begins. If this field refers to a station, the transfer rule applies to all its child stops. |
+| `to_stop_id` | ID referencing `stops.stop_id` | **Required** | Identifies a stop or station where a connection between routes ends. If this field refers to a station, the transfer rule applies to all child stops. |
+| `transfer_type` | Enum | **Required** | Indicates the type of connection for the specified (`from_stop_id`, `to_stop_id`) pair. Valid options are:
`0` or empty - Recommended transfer point between routes.
`1` - Timed transfer point between two routes. The departing vehicle is expected to wait for the arriving one and leave sufficient time for a rider to transfer between routes.
`2` - Transfer requires a minimum amount of time between arrival and departure to ensure a connection. The time required to transfer is specified by `min_transfer_time`.
`3` - Transfers are not possible between routes at the location. |
+| `min_transfer_time` | Non-negative integer | Optional | Amount of time, in seconds, that must be available to permit a transfer between routes at the specified stops. The `min_transfer_time` should be sufficient to permit a typical rider to move between the two stops, including buffer time to allow for schedule variance on each route. |
### feed_info.txt
File: **Optional**
-The file contains information about the feed itself, rather than the services that the feed describes. GTFS currently has an [agency.txt](#agencytxt) file to provide information about the agencies that operate the services described by the feed. However, the publisher of the feed is sometimes a different entity than any of the agencies (in the case of regional aggregators). In addition, there are some fields that are really feed-wide settings, rather than agency-wide.
+The file contains information about the dataset itself, rather than the services that the dataset describes. Note that, in some cases, the publisher of the dataset is a different entity than any of the agencies.
-| Field Name | Type | Required | Details |
+| Field Name | Type | Required | Description |
| ------ | ------ | ------ | ------ |
-| feed_publisher_name | Text | **Required** | The **feed_publisher_name** field contains the full name of the organization that publishes the feed. (This may be the same as one of the **agency_name** values in [agency.txt](#agencytxt).) GTFS-consuming applications can display this name when giving attribution for a particular feed's data. |
-| feed_publisher_url | URL | **Required** | The **feed_publisher_url** field contains the URL of the feed publishing organization's website. (This may be the same as one of the **agency_url** values in [agency.txt](#agencytxt)). |
-| feed_lang | Language code | **Required** | The **feed_lang** field contains a language code specifying the default language used for the text in this feed. This setting helps GTFS consumers choose capitalization rules and other language-specific settings for the feed. |
-| feed_start_date | Date | Optional | The feed provides complete and reliable schedule information for service in the period from the beginning of the **feed_start_date** day to the end of the **feed_end_date** day. Both days can be left empty if unavailable. The **feed_end_date** date must not precede the **feed_start_date** date if both are given. Feed providers are encouraged to give schedule data outside this period to advise of likely future service, but feed consumers should treat it mindful of its non-authoritative status. If **feed_start_date** or **feed_end_date** extend beyond the active calendar dates defined in [calendar.txt](#calendartxt) and [calendar_dates.txt](#calendar_datestxt), the feed is making an explicit assertion that there is no service for dates within the **feed_start_date** or **feed_end_date** range but not included in the active calendar dates. |
-| feed_end_date | Date | Optional | (see above) |
-| feed_version | Text | Optional | The feed publisher can specify a string here that indicates the current version of their GTFS feed. GTFS-consuming applications can display this value to help feed publishers determine whether the latest version of their feed has been incorporated. |
-| feed_contact_email | Email | Optional | An email address for communication regarding the GTFS dataset and data publishing practices. **feed_contact_email** is for a technical contact for GTFS-consuming applications. Provide customer service contact information through **agency.txt**. |
-| feed_contact_url | URL | Optional | A URL for contact information, a web-form, support desk, or other tools for communication regarding the GTFS dataset and data publishing practices. **feed_contact_url** is for a technical contact for GTFS-consuming applications. Provide customer service contact information through **agency.txt**. |
+| `feed_publisher_name` | Text | **Required** | Full name of the organization that publishes the dataset. This may be the same as one of the `agency.agency_name` values. |
+| `feed_publisher_url` | URL | **Required** | URL of the dataset publishing organization's website. This may be the same as one of the `agency.agency_url` values. |
+| `feed_lang` | Language code | **Required** | Default language used for the text in this dataset. This setting helps GTFS consumers choose capitalization rules and other language-specific settings for the dataset. |
+| `feed_start_date` | Date | Optional | The dataset provides complete and reliable schedule information for service in the period from the beginning of the `feed_start_date` day to the end of the `feed_end_date` day. Both days can be left empty if unavailable. The `feed_end_date` date must not precede the `feed_start_date` date if both are given. Dataset providers are encouraged to give schedule data outside this period to advise of likely future service, but dataset consumers should treat it mindful of its non-authoritative status. If `feed_start_date` or `feed_end_date` extend beyond the active calendar dates defined in [calendar.txt](#calendartxt) and [calendar_dates.txt](#calendar_datestxt), the dataset is making an explicit assertion that there is no service for dates within the `feed_start_date` or `feed_end_date` range but not included in the active calendar dates. |
+| `feed_end_date` | Date | Optional | (see above) |
+| `feed_version` | Text | Optional | String that indicates the current version of their GTFS dataset. GTFS-consuming applications can display this value to help dataset publishers determine whether the latest dataset has been incorporated. |
+| `feed_contact_email` | Email | Optional | Email address for communication regarding the GTFS dataset and data publishing practices. `feed_contact_email` is a technical contact for GTFS-consuming applications. Provide customer service contact information through [agency.txt](#agencytxt). |
+| `feed_contact_url` | URL | Optional | URL for contact information, a web-form, support desk, or other tools for communication regarding the GTFS dataset and data publishing practices. `feed_contact_url` is a technical contact for GTFS-consuming applications. Provide customer service contact information through [agency.txt](#agencytxt). |