From b7bb2f6800b548d18e15cc628780a5a996332fca Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Tue, 11 Jul 2017 13:55:06 +1000 Subject: [PATCH 01/10] whatevs --- gtfs-realtime/proto/gtfs-realtime.proto | 106 +++++++++++++++++++++++- gtfs-realtime/spec/en/reference.md | 80 ++++++++++++++++++ 2 files changed, 185 insertions(+), 1 deletion(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 5766bc576..575c47707 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -215,7 +215,7 @@ message TripUpdate { NO_DATA = 2; } optional ScheduleRelationship schedule_relationship = 5 - [default = SCHEDULED]; + [default = SCHEDULED]; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features @@ -574,6 +574,110 @@ message VehicleDescriptor { // The license plate of the vehicle. optional string license_plate = 3; + // Contains amenities and other information about an individual carriage that + // is part of a vehicle. + message CarriageDescriptor { + // Internal system identification of the carriage. Should be unique per + // vehicle, and can be used for tracking the carriage as it proceeds through + // the system. + optional string id = 1; + + // User visible label that may be shown to the passenger to help identify + // the carriage. + optional string label = 2; + + // The degree of passenger occupancy of the carriage. + optional VehiclePosition.OccupancyStatus occupancy_status = 3; + + // Whether the carriage is wheelchair accessible. + enum WheelchairAccessible { + // It is unknown if the carriage is wheelchair accessible. This is the + // default case. + UNKNOWN = 0; + + // The carriage is wheelchair accessible. + WHEELCHAIR_ACCESSIBLE = 1; + + // The carriage is not wheelchair accessible. + NOT_WHEELCHAIR_ACCESSIBLE = 2; + } + + optional WheelchairAccessible wheelchair_accessible = 4 [default = UNKNOWN]; + + // Whether the carriage has toilet facilities onboard. + enum ToiletFacilities { + // It is unknown if the carriage has toilet facilities. This is the + // default case. + UNKNOWN = 0; + + // The carriage has toilet facilities onboard. + TOILET_ONBOARD = 1; + + // The carriage does not have toilet facilities onboard. + NO_TOILET_ONBOARD = 2; + } + + optional ToiletFacilities toilet_facilities = 5 [default = UNKNOWN]; + + // Whether the carriage has WiFi onboard. + enum WifiAvailability { + // It is unknown if the carriage has WiFi. This is the default case. + UNKNOWN = 0; + + // The carriage has free WiFi available for passengers to use. + FREE_WIFI = 1; + + // The carriage has WiFi available for passengers to purchase. + PAID_WIFI = 2; + + // The carriage has no WiFi available for passengers to use. + NO_WIFI = 3; + } + + optional WifiAvailability wifi_availability = 6 [default = UNKNOWN]; + + // Whether the carriage is air conditioned. + enum AirConditioning { + // It is unknown if the carriage is air conditioned. This is the default + // case. + UNKNOWN = 0; + + // The carriage has air conditioning. + AIR_CONDITIONED = 1; + + // The carriage does not have air conditioning. + NOT_AIR_CONDITIONED = 2; + } + + optional AirConditioning air_conditioning = 7 [default = UNKNOWN]; + + // Whether bicycles are allowed in the carriage. + enum BicyclesAllowed { + // It is unknown if the carriage allows bicycles. This is the default + // case. + UNKNOWN = 0; + + // Bicycles are allowed to be transported, but must be stored outside of + // the carriage. + ALLOWED_OUTSIDE_CARRIAGE = 1; + + // Bicycles are allowed to be transported, and can be stored inside the + // carriage. + ALLOWED_INSIDE_CARRIAGE = 2; + + // Bicycles are not allowed to be transported in this carriage. + NOT_ALLOWED = 3; + } + + optional BicyclesAllowed bicycles_allowed = 8 [default = UNKNOWN]; + } + + // An ordered set of CarriageDescriptor. The first element maps to the first + // carriage a user will encounter if the vehicle is travelling in the + // direction of travel. Vehicles with only one compartment/carriage + // (e.g. a bus) will only have one CarriageDescriptor. + repeated CarriageDescriptor carriage_descriptor = 4; + // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and // modifications to the spec. diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index aa03be1ee..096f14be5 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -343,6 +343,86 @@ Identification information for the vehicle performing the trip. | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle. | | **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The license plate of the vehicle. | +| **carriage_descriptor** | [CarriageDescriptor](#message-carriagedescriptor) | repeated | An ordered list of carriage information. | + +## _message_ CarriageDescriptor + +Information for a carriage that is part of a vehicle. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the carriage. Should be **unique** per vehicle, and is used for tracking the carriage as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field | +| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that can be shown to the passenger to help identify the correct carriage. | +| _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _optional_ |The degree of passenger occupancy of the carriage.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **wheelchair_accessible** | [WheelchairAccessible](#enum-wheelchairaccessible) | optional | Whether the carriage is wheelchair accessible. | +| **toilet_facilities** | [ToiletFacilities](#enum-toiletfacilities) | optional | Whether the carriage has toilet facilities onboard. | +| **wifi_availability** | [WifiAvailability](#enum-wifiavailability) | optional | Whether the carriage has WiFi onboard. | +| **air_conditioning** | [AirConditioning](#enum-airconditioning) | optional | Whether the carriage is air conditioned. | +| **bicycles_allowed** | [BicyclesAllowed](#enum-bicyclesallowed) | optional | Whether bicycles are allowed in the carriage. | + +## _enum_ WheelchairAccessible + +Whether the carriage is wheelchair accessible. The default is UNKNOWN. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **UNKNOWN** | It is unknown if the carriage is wheelchair accessible. This is the default case. | +| **WHEELCHAIR_ACCESSIBLE** | The carriage is wheelchair accessible. | +| **NOT_WHEELCHAIR_ACCESSIBLE** | The carriage is not wheelchair accessible. | + +## _enum_ ToiletFacilities + +Whether the carriage has toilet facilities onboard. The default is UNKNOWN. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **UNKNOWN** | It is unknown if the carriage has toilet facilities. This is the default case. | +| **TOILET_ONBOARD** | The carriage has toilet facilities onboard. | +| **NO_TOILET_ONBOARD** | The carriage does not have toilet facilities onboard. | + +## _enum_ WifiAvailability + +Whether the carriage has WiFi onboard. The default is UNKNOWN. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **UNKNOWN** | It is unknown if the carriage has WiFi. This is the default case. | +| **FREE_WIFI** | The carriage has free WiFi available for passengers to use. | +| **PAID_WIFI** | The carriage has WiFi available for passengers to purchase. | +| **NO_WIFI** | The carriage has no WiFi available for passengers to use. | + +## _enum_ AirConditioning + +Whether the carriage is air conditioned. The default is UNKNOWN. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **UNKNOWN** | It is unknown if the carriage is air conditioned. This is the default case. | +| **AIR_CONDITIONED** | The carriage has air conditioning. | +| **NOT_AIR_CONDITIONED** | The carriage does not have air conditioning. | + +## _enum_ BicyclesAllowed + +Whether bicycles are allowed in the carriage. The default is UNKNOWN. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **UNKNOWN** | It is unknown if the carriage allows bicycles. This is the default case. | +| **ALLOWED_OUTSIDE_CARRIAGE** | Bicycles are allowed to be transported, but must be stored outside of the carriage. | +| **ALLOWED_INSIDE_CARRIAGE** | Bicycles are allowed to be transported, and can be stored inside the carriage. | +| **NOT_ALLOWED** | Bicycles are not allowed to be transported in this carriage. | ## _message_ EntitySelector From 59f7c4c1fe117786aac4e93ed5a693a76e74ed8b Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Tue, 11 Jul 2017 16:42:13 +1000 Subject: [PATCH 02/10] Add CarriageDescriptor. --- transit/AUTHORS | 9 + transit/CONTRIBUTING.md | 25 + transit/CONTRIBUTORS | 16 + transit/LICENSE | 201 ++++++ transit/README.md | 4 + transit/gtfs-realtime/CHANGES.md | 82 +++ transit/gtfs-realtime/README.md | 7 + .../gtfs-realtime/proto/gtfs-realtime.proto | 633 ++++++++++++++++++ transit/gtfs-realtime/spec/en/README.md | 49 ++ .../gtfs-realtime/spec/en/examples/README.md | 4 + .../spec/en/examples/alerts.asciipb | 72 ++ .../en/examples/trip-updates-full.asciipb | 79 +++ .../gtfs-realtime/spec/en/feed-entities.md | 54 ++ transit/gtfs-realtime/spec/en/reference.md | 380 +++++++++++ .../gtfs-realtime/spec/en/service-alerts.md | 56 ++ transit/gtfs-realtime/spec/en/trip-updates.md | 100 +++ .../spec/en/vehicle-positions.md | 59 ++ transit/gtfs-realtime/spec/es/README.md | 50 ++ .../gtfs-realtime/spec/es/examples/README.md | 4 + .../spec/es/examples/alerts.asciipb | 72 ++ .../es/examples/trip-updates-full.asciipb | 79 +++ transit/gtfs-realtime/spec/es/feed-types.md | 36 + .../gtfs-realtime/spec/es/gtfs-realtime.proto | 569 ++++++++++++++++ transit/gtfs-realtime/spec/es/reference.md | 361 ++++++++++ .../gtfs-realtime/spec/es/service-alerts.md | 56 ++ transit/gtfs-realtime/spec/es/trip-updates.md | 56 ++ .../spec/es/vehicle-positions.md | 45 ++ transit/gtfs/CHANGES.md | 199 ++++++ transit/gtfs/README.md | 5 + transit/gtfs/spec/en/README.md | 37 + transit/gtfs/spec/en/community.md | 25 + transit/gtfs/spec/en/examples/README.md | 130 ++++ .../gtfs/spec/en/examples/sample-feed-1.zip | Bin 0 -> 3217 bytes .../spec/en/examples/sample-feed-1/agency.txt | 2 + .../en/examples/sample-feed-1/calendar.txt | 3 + .../examples/sample-feed-1/calendar_dates.txt | 2 + .../sample-feed-1/fare_attributes.txt | 3 + .../en/examples/sample-feed-1/fare_rules.txt | 5 + .../en/examples/sample-feed-1/frequencies.txt | 12 + .../spec/en/examples/sample-feed-1/routes.txt | 6 + .../spec/en/examples/sample-feed-1/shapes.txt | 1 + .../en/examples/sample-feed-1/stop_times.txt | 29 + .../spec/en/examples/sample-feed-1/stops.txt | 10 + .../spec/en/examples/sample-feed-1/trips.txt | 12 + transit/gtfs/spec/en/reference.md | 429 ++++++++++++ transit/gtfs/spec/en/style-guide.md | 33 + transit/gtfs/spec/en/tools.md | 8 + 47 files changed, 4109 insertions(+) create mode 100644 transit/AUTHORS create mode 100644 transit/CONTRIBUTING.md create mode 100644 transit/CONTRIBUTORS create mode 100644 transit/LICENSE create mode 100644 transit/README.md create mode 100644 transit/gtfs-realtime/CHANGES.md create mode 100644 transit/gtfs-realtime/README.md create mode 100644 transit/gtfs-realtime/proto/gtfs-realtime.proto create mode 100644 transit/gtfs-realtime/spec/en/README.md create mode 100644 transit/gtfs-realtime/spec/en/examples/README.md create mode 100644 transit/gtfs-realtime/spec/en/examples/alerts.asciipb create mode 100644 transit/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb create mode 100644 transit/gtfs-realtime/spec/en/feed-entities.md create mode 100644 transit/gtfs-realtime/spec/en/reference.md create mode 100644 transit/gtfs-realtime/spec/en/service-alerts.md create mode 100644 transit/gtfs-realtime/spec/en/trip-updates.md create mode 100644 transit/gtfs-realtime/spec/en/vehicle-positions.md create mode 100644 transit/gtfs-realtime/spec/es/README.md create mode 100644 transit/gtfs-realtime/spec/es/examples/README.md create mode 100644 transit/gtfs-realtime/spec/es/examples/alerts.asciipb create mode 100644 transit/gtfs-realtime/spec/es/examples/trip-updates-full.asciipb create mode 100644 transit/gtfs-realtime/spec/es/feed-types.md create mode 100644 transit/gtfs-realtime/spec/es/gtfs-realtime.proto create mode 100644 transit/gtfs-realtime/spec/es/reference.md create mode 100644 transit/gtfs-realtime/spec/es/service-alerts.md create mode 100644 transit/gtfs-realtime/spec/es/trip-updates.md create mode 100644 transit/gtfs-realtime/spec/es/vehicle-positions.md create mode 100644 transit/gtfs/CHANGES.md create mode 100644 transit/gtfs/README.md create mode 100644 transit/gtfs/spec/en/README.md create mode 100644 transit/gtfs/spec/en/community.md create mode 100644 transit/gtfs/spec/en/examples/README.md create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1.zip create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/agency.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/calendar.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/calendar_dates.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/fare_attributes.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/fare_rules.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/frequencies.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/routes.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/shapes.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/stop_times.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/stops.txt create mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/trips.txt create mode 100644 transit/gtfs/spec/en/reference.md create mode 100644 transit/gtfs/spec/en/style-guide.md create mode 100644 transit/gtfs/spec/en/tools.md diff --git a/transit/AUTHORS b/transit/AUTHORS new file mode 100644 index 000000000..d910fd6cf --- /dev/null +++ b/transit/AUTHORS @@ -0,0 +1,9 @@ +# This is the official list of GTFS Specifications authors for copyright purposes. +# This file is distinct from the CONTRIBUTORS files. +# See the latter for an explanation. + +# Names should be added to this file as: +# Name or Organization +# The email address is not required for organizations. + +Google Inc. diff --git a/transit/CONTRIBUTING.md b/transit/CONTRIBUTING.md new file mode 100644 index 000000000..21e4c711b --- /dev/null +++ b/transit/CONTRIBUTING.md @@ -0,0 +1,25 @@ +Want to contribute? Great! First, read this page (including the small print at the end). + +### Before you contribute +Before we can use your code, you must sign the +[Google Individual Contributor License Agreement](https://cla.developers.google.com/about/google-individual) +(CLA), which you can do online. The CLA is necessary mainly because you own the +copyright to your changes, even after your contribution becomes part of our +codebase, so we need your permission to use and distribute your code. We also +need to be sure of various other things—for instance that you'll tell us if you +know that your code infringes on other people's patents. You don't have to sign +the CLA until after you've submitted your code for review and a member has +approved it, but you must do it before we can put your code into our codebase. +Before you start working on a larger contribution, you should get in touch with +us first through the issue tracker with your idea so that we can help out and +possibly guide you. Coordinating up front makes it much easier to avoid +frustration later on. + +### Code reviews +All submissions, including submissions by project members, require review. We +use Github pull requests for this purpose. + +### The small print +Contributions made by corporations are covered by a different agreement than +the one above, the +[Software Grant and Corporate Contributor License Agreement](https://cla.developers.google.com/about/google-corporate). diff --git a/transit/CONTRIBUTORS b/transit/CONTRIBUTORS new file mode 100644 index 000000000..356d7718d --- /dev/null +++ b/transit/CONTRIBUTORS @@ -0,0 +1,16 @@ +# People who have agreed to one of the CLAs and can contribute patches. +# The AUTHORS file lists the copyright holders; this file +# lists people. For example, Google employees are listed here +# but not in AUTHORS, because Google holds the copyright. +# +# https://developers.google.com/open-source/cla/individual +# https://developers.google.com/open-source/cla/corporate +# +# Names should be added to this file as: +# Name +Brian Ferris +Chiara Micca +Eric Andresen +Ivan Egorov +Ivan Maksimenko +Sean Barbeau diff --git a/transit/LICENSE b/transit/LICENSE new file mode 100644 index 000000000..094d8e444 --- /dev/null +++ b/transit/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/transit/README.md b/transit/README.md new file mode 100644 index 000000000..52fd7cb32 --- /dev/null +++ b/transit/README.md @@ -0,0 +1,4 @@ +The repository contains specification and tools to manipulate General Transit +Feed Specification (GTFS) and GTFS Realtime. + +Please visit https://developers.google.com/transit/ for information. diff --git a/transit/gtfs-realtime/CHANGES.md b/transit/gtfs-realtime/CHANGES.md new file mode 100644 index 000000000..39d7b63ca --- /dev/null +++ b/transit/gtfs-realtime/CHANGES.md @@ -0,0 +1,82 @@ +The GTFS Realtime Specification is not set in stone. Instead, it is an open specification developed and maintained by the community of transit agencies, developers, and other stakeholders who use GTFS Realtime. It is expected that this community of producers and consumers of GTFS Realtime data will have proposals for extending the spec to enable new capabilities. To help manage that process, the following procedures and guidelines have been established. + +### Specification amendment process +The official specification, reference and documentation are written in English. If a translation to a different language differs from the English original, the latter takes precedence. All communication is performed 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 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. +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. +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. + 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. +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. + 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. +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. + - 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 +In order to preserve the original vision of GTFS Realtime, a number of guiding principles have been established to take into consideration when extending the spec: + +#### Feeds should be efficient to produce and consume in realtime. +Realtime information is a continuous, dynamic stream of data that necessarily requires efficient processing. We chose Protocol Buffers as the basis for the specification because they offer a good trade-off in terms of ease of use for developers and in terms of efficiency for transmitting data. Unlike GTFS, we do not imagine many agencies will be editing GTFS Realtime feeds by hand. The choice of Protocol Buffers reflects the conclusion that most GTFS Realtime feeds will be produced and consumed programmatically. + +#### The spec is about passenger information. +Like GTFS before it, GTFS Realtime is primarily concerned with passenger information. That is, the spec should include information that can help power tools for riders, first and foremost. There is potentially a large amount of operations-oriented information that transit agencies might want to transmit internally between systems. GTFS Realtime is not intended for that purpose and there are potentially other operations-oriented data-standards that may be more appropriate. + +#### Changes to the spec should be backwards-compatible. +When adding features to the specification, we want to avoid making changes that will make existing feeds invalid. We don't want to create more work for existing feed publishers until they want to add capabilities to their feeds. Also, whenever possible, we want existing parsers to be able to continue to read the older parts of newer feeds. The conventions for extending Protocol Buffers will enforce backwards-compatibility to a certain extent. However, we wish to avoid semantic changes to existing fields that might break backwards-compatibility as well. + +#### Speculative features are discouraged. +Every new feature adds complexity to creating and reading of feeds. Therefore, we want to take care to only add features that we know to be useful. Ideally, any proposal will have been tested by generating data for a real transit system that uses the new feature and writing software to read and display it. + +We will make use of extensions, described in the following section, to support new features. GTFS Realtime producers and consumers can first test a new feature in the extension space. When the feature is ready for official adoption, we will add the feature to the official GTFS Realtime proto definition itself. + +### Extensions +To facilitate the testing of new features and to allow developers to add extra information to a GTFS Realtime feed, we will take advantage of the [Extensions feature of Protocol Buffers](https://developers.google.com/protocol-buffers/docs/proto#extensions). Extensions allow us to define a namespace in a Protocol Buffer message where third-party developers can define additional fields without the need to modify the original proto definition. + +When a developer is interested in extending the GTFS Realtime Specification, they should contact the [GTFS Realtime mailing list](https://groups.google.com/forum/#!forum/gtfs-realtime) and we will assign them the next available extension id, picked incrementally from a list of numbers starting at 1000 and going up and documented in the Extension Registry section found below. + +These assigned extension ids corresponds to the tag ids available in the "extension" namespace for each GTFS Realtime message definition. Now that the developer has an assigned extension id, they will use that id when extending any and all GTFS Realtime messages. Even if the developer only plans to extend a single message, the assigned extension id will be reserved for ALL messages. + +For a developer extending the spec, instead of adding a single field like a "string" or "int32" with their extension id, the preferred model is to define a new message like "MyTripDescriptorExtension", extend the underlying GTFS Realtime message with your new message, and then put all your new fields in there. This has the nice property that you can manage fields within your extension message however you want, without needing to reserve a new extension id from the master list. + +``` +message MyTripDescriptorExtension { + optional string some_string = 1; + optional bool some_bool = 2; + ... +} +extend transit_realtime.TripDescriptor { + optional MyTripDescriptorExtension my_trip_descriptor = YOUR_EXTENSION_ID; +} +``` + +### Extension Registry + +|Extension ID|Developer|Contact|Details| +|------------|---------|-------|-------| +|1000|OneBusAway|[onebusaway-developers](http://groups.google.com/group/onebusaway-developers)|https://github.com/OneBusAway/onebusaway/wiki/GTFS-Realtime-Resources| +|1001|New York City MTA|[mtadeveloperresources](http://groups.google.com/group/mtadeveloperresources)|http://mta.info/developers/| +|1002|Google|[transit-realtime-partner-support@google.com](mailto:transit-realtime-partner-support@google.com)|Google Maps Live Transit Updates| +|1003|OVapi|gtfs-rt at ovapi.nl|http://gtfs.ovapi.nl| +|1004|Metra|[William Ashbaugh ](mailto:w.l.ashbaugh@gmail.com)| +|1005|Metro-North Railroad|[John Larsen](mailto:mnrappdev@mnr.org)| +|1006|realCity|[David Varga](mailto:transit@realcity.io)|http://realcity.io| diff --git a/transit/gtfs-realtime/README.md b/transit/gtfs-realtime/README.md new file mode 100644 index 000000000..5d1bd01d1 --- /dev/null +++ b/transit/gtfs-realtime/README.md @@ -0,0 +1,7 @@ +This directory contains GTFS Realtime Specification and documentation. + +### Quick links +- [GTFS Realtime protocol buffer definition](proto/gtfs-realtime.proto) +- [Documentation](spec/en) +- [How to change the specification?](CHANGES.md) + diff --git a/transit/gtfs-realtime/proto/gtfs-realtime.proto b/transit/gtfs-realtime/proto/gtfs-realtime.proto new file mode 100644 index 000000000..5766bc576 --- /dev/null +++ b/transit/gtfs-realtime/proto/gtfs-realtime.proto @@ -0,0 +1,633 @@ +// Copyright 2015 The GTFS Specifications Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Protocol definition file for GTFS Realtime. +// +// GTFS Realtime 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. +// +// This protocol is published at: +// https://github.com/google/transit/tree/master/gtfs-realtime + +syntax = "proto2"; +option java_package = "com.google.transit.realtime"; +package transit_realtime; + +// The contents of a feed message. +// A feed is a continuous stream of feed messages. Each message in the stream is +// obtained as a response to an appropriate HTTP GET request. +// A realtime feed is always defined with relation to an existing GTFS feed. +// All the entity ids are resolved with respect to the GTFS feed. +message FeedMessage { + // Metadata about this feed and feed message. + required FeedHeader header = 1; + + // Contents of the feed. + repeated FeedEntity entity = 2; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// Metadata about a feed, included in feed messages. +message FeedHeader { + // Version of the feed specification. + // The current version is 1.0. + required string gtfs_realtime_version = 1; + + // Determines whether the current fetch is incremental. Currently, + // DIFFERENTIAL mode is unsupported and behavior is unspecified for feeds + // that use this mode. There are discussions on the GTFS Realtime mailing + // list around fully specifying the behavior of DIFFERENTIAL mode and the + // documentation will be updated when those discussions are finalized. + enum Incrementality { + FULL_DATASET = 0; + DIFFERENTIAL = 1; + } + optional Incrementality incrementality = 2 [default = FULL_DATASET]; + + // This timestamp identifies the moment when the content of this feed has been + // created (in server time). In POSIX time (i.e., number of seconds since + // January 1st 1970 00:00:00 UTC). + optional uint64 timestamp = 3; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// A definition (or update) of an entity in the transit feed. +message FeedEntity { + // The ids are used only to provide incrementality support. The id should be + // unique within a FeedMessage. Consequent FeedMessages may contain + // FeedEntities with the same id. In case of a DIFFERENTIAL update the new + // FeedEntity with some id will replace the old FeedEntity with the same id + // (or delete it - see is_deleted below). + // The actual GTFS entities (e.g. stations, routes, trips) referenced by the + // feed must be specified by explicit selectors (see EntitySelector below for + // more info). + required string id = 1; + + // Whether this entity is to be deleted. Relevant only for incremental + // fetches. + optional bool is_deleted = 2 [default = false]; + + // Data about the entity itself. Exactly one of the following fields must be + // present (unless the entity is being deleted). + optional TripUpdate trip_update = 3; + optional VehiclePosition vehicle = 4; + optional Alert alert = 5; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// +// Entities used in the feed. +// + +// Realtime update of the progress of a vehicle along a trip. +// Depending on the value of ScheduleRelationship, a TripUpdate can specify: +// - A trip that proceeds along the schedule. +// - A trip that proceeds along a route but has no fixed schedule. +// - A trip that have been added or removed with regard to schedule. +// +// The updates can be for future, predicted arrival/departure events, or for +// past events that already occurred. +// Normally, updates should get more precise and more certain (see +// uncertainty below) as the events gets closer to current time. +// Even if that is not possible, the information for past events should be +// precise and certain. In particular, if an update points to time in the past +// but its update's uncertainty is not 0, the client should conclude that the +// update is a (wrong) prediction and that the trip has not completed yet. +// +// Note that the update can describe a trip that is already completed. +// To this end, it is enough to provide an update for the last stop of the trip. +// If the time of that is in the past, the client will conclude from that that +// the whole trip is in the past (it is possible, although inconsequential, to +// also provide updates for preceding stops). +// This option is most relevant for a trip that has completed ahead of schedule, +// but according to the schedule, the trip is still proceeding at the current +// time. Removing the updates for this trip could make the client assume +// that the trip is still proceeding. +// Note that the feed provider is allowed, but not required, to purge past +// updates - this is one case where this would be practically useful. +message TripUpdate { + // The Trip that this message applies to. There can be at most one + // TripUpdate entity for each actual trip instance. + // If there is none, that means there is no prediction information available. + // It does *not* mean that the trip is progressing according to schedule. + required TripDescriptor trip = 1; + + // Additional information on the vehicle that is serving this trip. + optional VehicleDescriptor vehicle = 3; + + // Timing information for a single predicted event (either arrival or + // departure). + // Timing consists of delay and/or estimated time, and uncertainty. + // - delay should be used when the prediction is given relative to some + // existing schedule in GTFS. + // - time should be given whether there is a predicted schedule or not. If + // both time and delay are specified, time will take precedence + // (although normally, time, if given for a scheduled trip, should be + // equal to scheduled time in GTFS + delay). + // + // Uncertainty applies equally to both time and delay. + // The uncertainty roughly specifies the expected error in true delay (but + // note, we don't yet define its precise statistical meaning). It's possible + // for the uncertainty to be 0, for example for trains that are driven under + // computer timing control. + message StopTimeEvent { + // Delay (in seconds) can be positive (meaning that the vehicle is late) or + // negative (meaning that the vehicle is ahead of schedule). Delay of 0 + // means that the vehicle is exactly on time. + optional int32 delay = 1; + + // Event as absolute time. + // In Unix time (i.e., number of seconds since January 1st 1970 00:00:00 + // UTC). + optional int64 time = 2; + + // If uncertainty is omitted, it is interpreted as unknown. + // If the prediction is unknown or too uncertain, the delay (or time) field + // should be empty. In such case, the uncertainty field is ignored. + // To specify a completely certain prediction, set its uncertainty to 0. + optional int32 uncertainty = 3; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features + // and modifications to the spec. + extensions 1000 to 1999; + } + + // Realtime update for arrival and/or departure events for a given stop on a + // trip. Updates can be supplied for both past and future events. + // The producer is allowed, although not required, to drop past events. + message StopTimeUpdate { + // The update is linked to a specific stop either through stop_sequence or + // stop_id, so one of the fields below must necessarily be set. + // See the documentation in TripDescriptor for more information. + + // Must be the same as in stop_times.txt in the corresponding GTFS feed. + optional uint32 stop_sequence = 1; + // Must be the same as in stops.txt in the corresponding GTFS feed. + optional string stop_id = 4; + + optional StopTimeEvent arrival = 2; + optional StopTimeEvent departure = 3; + + // The relation between this StopTime and the static schedule. + enum ScheduleRelationship { + // The vehicle is proceeding in accordance with its static schedule of + // stops, although not necessarily according to the times of the schedule. + // At least one of arrival and departure must be provided. If the schedule + // for this stop contains both arrival and departure times then so must + // this update. + SCHEDULED = 0; + + // The stop is skipped, i.e., the vehicle will not stop at this stop. + // Arrival and departure are optional. + SKIPPED = 1; + + // No data is given for this stop. The main intention for this value is to + // give the predictions only for part of a trip, i.e., if the last update + // for a trip has a NO_DATA specifier, then StopTimes for the rest of the + // stops in the trip are considered to be unspecified as well. + // Neither arrival nor departure should be supplied. + NO_DATA = 2; + } + optional ScheduleRelationship schedule_relationship = 5 + [default = SCHEDULED]; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features + // and modifications to the spec. + extensions 1000 to 1999; + } + + // Updates to StopTimes for the trip (both future, i.e., predictions, and in + // some cases, past ones, i.e., those that already happened). + // The updates must be sorted by stop_sequence, and apply for all the + // following stops of the trip up to the next specified one. + // + // Example 1: + // For a trip with 20 stops, a StopTimeUpdate with arrival delay and departure + // delay of 0 for stop_sequence of the current stop means that the trip is + // exactly on time. + // + // Example 2: + // For the same trip instance, 3 StopTimeUpdates are provided: + // - delay of 5 min for stop_sequence 3 + // - delay of 1 min for stop_sequence 8 + // - delay of unspecified duration for stop_sequence 10 + // This will be interpreted as: + // - stop_sequences 3,4,5,6,7 have delay of 5 min. + // - stop_sequences 8,9 have delay of 1 min. + // - stop_sequences 10,... have unknown delay. + repeated StopTimeUpdate stop_time_update = 2; + + // Moment at which the vehicle's real-time progress was measured. In POSIX + // time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC). + optional uint64 timestamp = 4; + + // The current schedule deviation for the trip. Delay should only be + // specified when the prediction is given relative to some existing schedule + // in GTFS. + // + // Delay (in seconds) can be positive (meaning that the vehicle is late) or + // negative (meaning that the vehicle is ahead of schedule). Delay of 0 + // means that the vehicle is exactly on time. + // + // Delay information in StopTimeUpdates take precedent of trip-level delay + // information, such that trip-level delay is only propagated until the next + // stop along the trip with a StopTimeUpdate delay value specified. + // + // Feed providers are strongly encouraged to provide a TripUpdate.timestamp + // value indicating when the delay value was last updated, in order to + // evaluate the freshness of the data. + // + // NOTE: This field is still experimental, and subject to change. It may be + // formally adopted in the future. + optional int32 delay = 5; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// Realtime positioning information for a given vehicle. +message VehiclePosition { + // The Trip that this vehicle is serving. + // Can be empty or partial if the vehicle can not be identified with a given + // trip instance. + optional TripDescriptor trip = 1; + + // Additional information on the vehicle that is serving this trip. + optional VehicleDescriptor vehicle = 8; + + // Current position of this vehicle. + optional Position position = 2; + + // The stop sequence index of the current stop. The meaning of + // current_stop_sequence (i.e., the stop that it refers to) is determined by + // current_status. + // If current_status is missing IN_TRANSIT_TO is assumed. + optional uint32 current_stop_sequence = 3; + // Identifies the current stop. The value must be the same as in stops.txt in + // the corresponding GTFS feed. + optional string stop_id = 7; + + enum VehicleStopStatus { + // The vehicle is just about to arrive at the stop (on a stop + // display, the vehicle symbol typically flashes). + INCOMING_AT = 0; + + // The vehicle is standing at the stop. + STOPPED_AT = 1; + + // The vehicle has departed and is in transit to the next stop. + IN_TRANSIT_TO = 2; + } + // The exact status of the vehicle with respect to the current stop. + // Ignored if current_stop_sequence is missing. + optional VehicleStopStatus current_status = 4 [default = IN_TRANSIT_TO]; + + // Moment at which the vehicle's position was measured. In POSIX time + // (i.e., number of seconds since January 1st 1970 00:00:00 UTC). + optional uint64 timestamp = 5; + + // Congestion level that is affecting this vehicle. + enum CongestionLevel { + UNKNOWN_CONGESTION_LEVEL = 0; + RUNNING_SMOOTHLY = 1; + STOP_AND_GO = 2; + CONGESTION = 3; + SEVERE_CONGESTION = 4; // People leaving their cars. + } + optional CongestionLevel congestion_level = 6; + + // The degree of passenger occupancy of the vehicle. This field is still + // experimental, and subject to change. It may be formally adopted in the + // future. + enum OccupancyStatus { + // The vehicle is considered empty by most measures, and has few or no + // passengers onboard, but is still accepting passengers. + EMPTY = 0; + + // The vehicle has a relatively large percentage of seats available. + // What percentage of free seats out of the total seats available is to be + // considered large enough to fall into this category is determined at the + // discretion of the producer. + MANY_SEATS_AVAILABLE = 1; + + // The vehicle has a relatively small percentage of seats available. + // What percentage of free seats out of the total seats available is to be + // considered small enough to fall into this category is determined at the + // discretion of the feed producer. + FEW_SEATS_AVAILABLE = 2; + + // The vehicle can currently accommodate only standing passengers. + STANDING_ROOM_ONLY = 3; + + // The vehicle can currently accommodate only standing passengers + // and has limited space for them. + CRUSHED_STANDING_ROOM_ONLY = 4; + + // The vehicle is considered full by most measures, but may still be + // allowing passengers to board. + FULL = 5; + + // The vehicle is not accepting additional passengers. + NOT_ACCEPTING_PASSENGERS = 6; + + } + optional OccupancyStatus occupancy_status = 9; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// An alert, indicating some sort of incident in the public transit network. +message Alert { + // Time when the alert should be shown to the user. If missing, the + // alert will be shown as long as it appears in the feed. + // If multiple ranges are given, the alert will be shown during all of them. + repeated TimeRange active_period = 1; + + // Entities whose users we should notify of this alert. + repeated EntitySelector informed_entity = 5; + + // Cause of this alert. + enum Cause { + UNKNOWN_CAUSE = 1; + OTHER_CAUSE = 2; // Not machine-representable. + TECHNICAL_PROBLEM = 3; + STRIKE = 4; // Public transit agency employees stopped working. + DEMONSTRATION = 5; // People are blocking the streets. + ACCIDENT = 6; + HOLIDAY = 7; + WEATHER = 8; + MAINTENANCE = 9; + CONSTRUCTION = 10; + POLICE_ACTIVITY = 11; + MEDICAL_EMERGENCY = 12; + } + optional Cause cause = 6 [default = UNKNOWN_CAUSE]; + + // What is the effect of this problem on the affected entity. + enum Effect { + NO_SERVICE = 1; + REDUCED_SERVICE = 2; + + // We don't care about INsignificant delays: they are hard to detect, have + // little impact on the user, and would clutter the results as they are too + // frequent. + SIGNIFICANT_DELAYS = 3; + + DETOUR = 4; + ADDITIONAL_SERVICE = 5; + MODIFIED_SERVICE = 6; + OTHER_EFFECT = 7; + UNKNOWN_EFFECT = 8; + STOP_MOVED = 9; + } + optional Effect effect = 7 [default = UNKNOWN_EFFECT]; + + // The URL which provides additional information about the alert. + optional TranslatedString url = 8; + + // Alert header. Contains a short summary of the alert text as plain-text. + optional TranslatedString header_text = 10; + + // 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; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features + // and modifications to the spec. + extensions 1000 to 1999; +} + +// +// Low level data structures used above. +// + +// A time interval. The interval is considered active at time 't' if 't' is +// greater than or equal to the start time and less than the end time. +message TimeRange { + // Start time, in POSIX time (i.e., number of seconds since January 1st 1970 + // 00:00:00 UTC). + // If missing, the interval starts at minus infinity. + optional uint64 start = 1; + + // End time, in POSIX time (i.e., number of seconds since January 1st 1970 + // 00:00:00 UTC). + // If missing, the interval ends at plus infinity. + optional uint64 end = 2; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// A position. +message Position { + // Degrees North, in the WGS-84 coordinate system. + required float latitude = 1; + + // Degrees East, in the WGS-84 coordinate system. + required float longitude = 2; + + // Bearing, in degrees, clockwise from North, i.e., 0 is North and 90 is East. + // This can be the compass bearing, or the direction towards the next stop + // or intermediate location. + // This should not be direction deduced from the sequence of previous + // positions, which can be computed from previous data. + optional float bearing = 3; + + // Odometer value, in meters. + optional double odometer = 4; + // Momentary speed measured by the vehicle, in meters per second. + optional float speed = 5; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// A descriptor that identifies an instance of a GTFS trip, or all instances of +// a trip along a route. +// - To specify a single trip instance, the trip_id (and if necessary, +// start_time) is set. If route_id is also set, then it should be same as one +// that the given trip corresponds to. +// - To specify all the trips along a given route, only the route_id should be +// set. Note that if the trip_id is not known, then stop sequence ids in +// TripUpdate are not sufficient, and stop_ids must be provided as well. In +// addition, absolute arrival/departure times must be provided. +message TripDescriptor { + // The trip_id from the GTFS feed that this selector refers to. + // For non frequency-based trips, this field is enough to uniquely identify + // the trip. For frequency-based trip, start_time and start_date might also be + // necessary. + optional string trip_id = 1; + + // The route_id from the GTFS that this selector refers to. + optional string route_id = 5; + + // The direction_id from the GTFS feed trips.txt file, indicating the + // direction of travel for trips this selector refers to. This field is + // still experimental, and subject to change. It may be formally adopted in + // the future. + optional uint32 direction_id = 6; + + // The initially scheduled start time of this trip instance. + // When the trip_id corresponds to a non-frequency-based trip, this field + // should either be omitted or be equal to the value in the GTFS feed. When + // the trip_id correponds to a frequency-based trip, the start_time must be + // specified for trip updates and vehicle positions. If the trip corresponds + // to exact_times=1 GTFS record, then start_time must be some multiple + // (including zero) of headway_secs later than frequencies.txt start_time for + // the corresponding time period. If the trip corresponds to exact_times=0, + // then its start_time may be arbitrary, and is initially expected to be the + // first departure of the trip. Once established, the start_time of this + // frequency-based trip should be considered immutable, even if the first + // departure time changes -- that time change may instead be reflected in a + // StopTimeUpdate. + // Format and semantics of the field is same as that of + // GTFS/frequencies.txt/start_time, e.g., 11:15:35 or 25:15:35. + optional string start_time = 2; + // The scheduled start date of this trip instance. + // Must be provided to disambiguate trips that are so late as to collide with + // a scheduled trip on a next day. For example, for a train that departs 8:00 + // and 20:00 every day, and is 12 hours late, there would be two distinct + // trips on the same time. + // This field can be provided but is not mandatory for schedules in which such + // collisions are impossible - for example, a service running on hourly + // schedule where a vehicle that is one hour late is not considered to be + // related to schedule anymore. + // In YYYYMMDD format. + optional string start_date = 3; + + // The relation between this trip and the static schedule. If a trip is done + // in accordance with temporary schedule, not reflected in GTFS, then it + // shouldn't be marked as SCHEDULED, but likely as ADDED. + enum ScheduleRelationship { + // Trip that is running in accordance with its GTFS schedule, or is close + // enough to the scheduled trip to be associated with it. + SCHEDULED = 0; + + // An extra trip that was added in addition to a running schedule, for + // example, to replace a broken vehicle or to respond to sudden passenger + // load. + ADDED = 1; + + // A trip that is running with no schedule associated to it, for example, if + // there is no schedule at all. + UNSCHEDULED = 2; + + // A trip that existed in the schedule but was removed. + CANCELED = 3; + } + optional ScheduleRelationship schedule_relationship = 4; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// Identification information for the vehicle performing the trip. +message VehicleDescriptor { + // Internal system identification of the vehicle. Should be unique per + // vehicle, and can be used for tracking the vehicle as it proceeds through + // the system. + optional string id = 1; + + // User visible label, i.e., something that must be shown to the passenger to + // help identify the correct vehicle. + optional string label = 2; + + // The license plate of the vehicle. + optional string license_plate = 3; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// A selector for an entity in a GTFS feed. +message EntitySelector { + // The values of the fields should correspond to the appropriate fields in the + // GTFS feed. + // At least one specifier must be given. If several are given, then the + // matching has to apply to all the given specifiers. + optional string agency_id = 1; + optional string route_id = 2; + // corresponds to route_type in GTFS. + optional int32 route_type = 3; + optional TripDescriptor trip = 4; + optional string stop_id = 5; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} + +// An internationalized message containing per-language versions of a snippet of +// text or a URL. +// One of the strings from a message will be picked up. The resolution proceeds +// as follows: +// 1. If the UI language matches the language code of a translation, +// the first matching translation is picked. +// 2. If a default UI language (e.g., English) matches the language code of a +// translation, the first matching translation is picked. +// 3. If some translation has an unspecified language code, that translation is +// picked. +message TranslatedString { + message Translation { + // A UTF-8 string containing the message. + required string text = 1; + // BCP-47 language code. Can be omitted if the language is unknown or if + // no i18n is done at all for the feed. At most one translation is + // allowed to have an unspecified language tag. + optional string language = 2; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; + } + // At least one translation must be provided. + repeated Translation translation = 1; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; +} diff --git a/transit/gtfs-realtime/spec/en/README.md b/transit/gtfs-realtime/spec/en/README.md new file mode 100644 index 000000000..dedc70df6 --- /dev/null +++ b/transit/gtfs-realtime/spec/en/README.md @@ -0,0 +1,49 @@ +GTFS Realtime is a feed specification that allows public transportation agencies to provide realtime updates about their fleet to application developers. It is an extension to [GTFS](https://developers.google.com/transit/gtfs/reference) (General Transit Feed Specification), an open data format for public transportation schedules and associated geographic information. GTFS Realtime was designed around ease of implementation, good GTFS interoperability and a focus on passenger information. + +The specification was designed through a partnership of the initial [Live Transit Updates](https://developers.google.com/transit/google-transit#LiveTransitUpdates) partner agencies, a number of transit developers and Google. The specification is published under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html). + +## How do I start? + +1. Continue reading the overview below. +2. Decide which [feed entities](feed-entities.md) you will be providing. +3. Take a look at [example feeds](examples/). +4. Create your own feeds using the [reference](reference.md). +5. Publish your feed. + +## Overview of GTFS Realtime feeds + +The specification currently supports the following types of information: + +* **Trip updates** - delays, cancellations, changed routes +* **Service alerts** - stop moved, unforeseen events affecting a station, route or the entire network +* **Vehicle positions** - information about the vehicles including location and congestion level + +A feed may, although not required to, combine entities of different types. Feeds are served via HTTP and updated frequently. The file itself is a regular binary file, so any type of webserver can host and serve the file (other transfer protocols might be used as well). Alternatively, web application servers could also be used which as a response to a valid HTTP GET request will return the feed. There are no constraints on how frequently nor on the exact method of how the feed should be updated or retrieved. + +Because GTFS Realtime allows you to present the _actual_ status of your fleet, the feed needs to be updated regularly - preferably whenever new data comes in from your Automatic Vehicle Location system. + +[More about feed entities...](feed-entities.md) + +## Data format + +The GTFS Realtime data exchange format is based on [Protocol Buffers](https://developers.google.com/protocol-buffers/) + +Protocol buffers are a language- and platform-neutral mechanism for serializing structured data (think XML, but smaller, faster, and simpler). The data structure is defined in a [gtfs-realtime.proto](../../proto/gtfs-realtime.proto) file, which then is used to generate source code to easily read and write your structured data from and to a variety of data streams, using a variety of languages – e.g. Java, C++ or Python. + +[More about Protocol Buffers...](https://developers.google.com/protocol-buffers/). + +## Data structure + +The hierarchy of elements and their type definitions are specified in the [gtfs-realtime.proto](../../proto/gtfs-realtime.proto) file. + +This text file is used to generate the necessary libraries in your choice of programming language. These libraries provide the classes and functions needed for generating valid GTFS Realtime feeds. The libraries not only make feed creation easier but also ensure that only valid feeds are produced. + +[More about the data structure...](reference.md) + +## Getting Help + +To participate in discussions around GTFS Realtime and suggest changes and additions to the specification, join the [GTFS Realtime mailing list](http://groups.google.com/group/gtfs-realtime). + +## Google Maps and Live Transit Updates + +One of the possible applications that uses GTFS Realtime is [Live Transit Updates](https://developers.google.com/transit/google-transit#LiveTransitUpdates), a feature within Google Maps that provides users with realtime transit information. If you are working for a public transportation agency that is interested in providing realtime updates to Google Maps, please visit the [Google Transit Partner Page](http://maps.google.com/help/maps/transit/partners/live-updates.html). diff --git a/transit/gtfs-realtime/spec/en/examples/README.md b/transit/gtfs-realtime/spec/en/examples/README.md new file mode 100644 index 000000000..d38444d2a --- /dev/null +++ b/transit/gtfs-realtime/spec/en/examples/README.md @@ -0,0 +1,4 @@ +The following examples show a textual representation of feeds. During development it is more convenient to produce ASCII protocol buffer output for easier debugging. You can compare your text output with these examples to check for the validity of data. + +* [Alerts](alerts.asciipb) +* [Trip update (full dataset)](trip-updates-full.asciipb) diff --git a/transit/gtfs-realtime/spec/en/examples/alerts.asciipb b/transit/gtfs-realtime/spec/en/examples/alerts.asciipb new file mode 100644 index 000000000..c304f89bd --- /dev/null +++ b/transit/gtfs-realtime/spec/en/examples/alerts.asciipb @@ -0,0 +1,72 @@ +# header information +header { + # version of speed specification. Currently "1.0" + gtfs_realtime_version: "1.0" + + # determines whether dataset is incremental or full + incrementality: FULL_DATASET + + # the time where this dataset was generated on server + # for determining the sequence of alert feeds + timestamp: 1284457468 +} +# multiple entities can be included in the feed +entity { + # unique identifier for the entity + id: "0" + + # "type" of the entity + alert { + # multiple periods can be defined when alert is active + active_period { + # start time in POSIX epoch format + start: 1284457468 + # end time in POSIX epoch format + end: 1284468072 + } + # selects which GTFS entities will be affected + informed_entity { + # valid parameters: + # agency_id, route_id, route_type, stop_id, trip (see TripDescriptor) + route_id: "219" + } + # multiple selectors (informed_entity) can be given + informed_entity { + stop_id: "16230" + } + + # cause of the alert - see gtfs-realtime.proto for valid values + cause: CONSTRUCTION + # effect of the alert - see gtfs-realtime.proto for valid values + effect: DETOUR + + # the given url provides additional information + url { + # multiple languages/translations supported + translation { + # page hosted outside of Google (at provider/agency, etc.) + text: "http://www.sometransitagency/alerts" + language: "en" + } + } + + # header for the alert will be highlighted + header_text { + # multiple languages/translations supported + translation { + text: "Stop at Elm street is closed, temporary stop at Oak street" + language: "en" + } + } + + # Alert description. Additional info to the header text + description_text { + # multiple languages/translations supported + translation { + text: "Due to construction at Elm street the stop is closed. The temporary stop can be found 300 meters north at Oak street" + language: "en" + } + } + } +} + diff --git a/transit/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb b/transit/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb new file mode 100644 index 000000000..cc245cf75 --- /dev/null +++ b/transit/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb @@ -0,0 +1,79 @@ +# header information +header { + # version of speed specification. Currently "1.0" + gtfs_realtime_version: "1.0" + # determines whether dataset is incremental or full + incrementality: FULL_DATASET + # the moment where this dataset was generated on server + timestamp: 1284457468 +} + +# multiple entities can be included in the feed +entity { + # unique identifier for the entity + id: "simple-trip" + + # "type" of the entity + trip_update { + trip { + # selects which GTFS entity (trip) will be affected + trip_id: "trip-1" + } + # schedule information update + stop_time_update { + # selecting which stop is affected + stop_sequence: 3 + # for the vehicle's arrival time + arrival { + # to be delayed with 5 seconds + delay: 5 + } + } + # ...this vehicle's delay is propagated to its subsequent stops. + + # Next information update on the vehicle's schedule + stop_time_update { + # selected by stop_sequence. It will update + stop_sequence: 8 + # the vehicle's original (scheduled) arrival time with a + arrival { + # 1 second delay. + delay: 1 + } + } + # ...likewise the delay is propagated to subsequent stops. + + # Next information update on the vehicle's schedule + stop_time_update { + # selected by stop_sequence. It will update the vehicle's arrival time + stop_sequence: 10 + # with the default delay of 0 (on time) and propagate this update + # for the rest of the vehicle's stops. + } + } +} + +# second entity containing update information for another trip +entity { + id: "3" + trip_update { + trip { + # frequency based trips are defined by their + # trip_id in GTFS and + trip_id: "frequency-expanded-trip" + # start_time + start_time: "11:15:35" + } + stop_time_update { + stop_sequence: 1 + arrival { + # negative delay means vehicle is 2 seconds ahead of schedule + delay: -2 + } + } + stop_time_update { + stop_sequence: 9 + } + } +} + diff --git a/transit/gtfs-realtime/spec/en/feed-entities.md b/transit/gtfs-realtime/spec/en/feed-entities.md new file mode 100644 index 000000000..43fff457f --- /dev/null +++ b/transit/gtfs-realtime/spec/en/feed-entities.md @@ -0,0 +1,54 @@ +GTFS Realtime supports three distinct types of realtime data, that can be +combined witin a single realtime feed. Summaries are given below, with full +documentation given in the relevant section. + +## Trip Updates + +#### "Bus X is delayed by 5 minutes" + +Trip updates represent fluctuations in the timetable. We would expect to receive +trip updates for all trips you have scheduled that are realtime-capable. These +updates would give a predicted arrival or departure for stops along the route. +Trip updates can also provide for more complex scenarios where trips are +canceled, added to the schedule, or even re-routed. + +[More about Trip Updates...](trip-updates.md) + +## Service Alerts + +#### "Station Y is closed due to construction" + +Service alerts represent higher level problems with a particular entity and are +generally in the form of a textual description of the disruption. + +They could represent problems with: + +* Stations +* Lines +* The whole network +* etc. + +A service alert will usually consist of some text which will describe the +problem, and we also allow for URLs for more information as well as more +structured information to help us understand who this service alert affects. + +[More about Service Alerts...](service-alerts.md) + +## Vehicle Positions + +#### "This bus is at position X at time Y" + +Vehicle position represents a few basic pieces of information about a particular +vehicle on the network. + +Most important are the latitude and longitude the vehicle is at, but we can also +use data on current speed and odometer readings from the vehicle. + +[More about Vehicle Position updates...](vehicle-positions.md) + +## Historical remark on feed types + +Early versions of GTFS Realtime Specification required each feed to only contain +single type of entities. An example tool to convert from merged to the +feed-per-type schema is located at +https://github.com/bliksemlabs/gtfsrt-examples/blob/master/split_by_entitytype.py diff --git a/transit/gtfs-realtime/spec/en/reference.md b/transit/gtfs-realtime/spec/en/reference.md new file mode 100644 index 000000000..aa03be1ee --- /dev/null +++ b/transit/gtfs-realtime/spec/en/reference.md @@ -0,0 +1,380 @@ +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 1.0 of the feed specification is discussed and documented on this site. + +### Term Definitions + +* **required**: Exactly one +* **repeated**: Zero or more +* **message**: Complex type +* **enum**: List of fixed values +* **experimental**: Experimental field, subject to change. It may be formally adopted in the future. + +## Element Index + +* [FeedMessage](#message-feedmessage) + * [FeedHeader](#message-feedheader) + * [Incrementality](#enum-incrementality) + * [FeedEntity](#message-feedentity) + * [TripUpdate](#message-tripupdate) + * [TripDescriptor](#message-tripdescriptor) + * [ScheduleRelationship](#enum-schedulerelationship-1) + * [VehicleDescriptor](#message-vehicledescriptor) + * [StopTimeUpdate](#message-stoptimeupdate) + * [StopTimeEvent](#message-stoptimeevent) + * [ScheduleRelationship](#enum-schedulerelationship) + * [VehiclePosition](#message-vehicleposition) + * [TripDescriptor](#message-tripdescriptor) + * [ScheduleRelationship](#enum-schedulerelationship-1) + * [VehicleDescriptor](#message-vehicledescriptor) + * [Position](#message-position) + * [VehicleStopStatus](#enum-vehiclestopstatus) + * [CongestionLevel](#enum-congestionlevel) + * [OccupancyStatus](#enum-occupancystatus) + * [Alert](#message-alert) + * [TimeRange](#message-timerange) + * [EntitySelector](#message-entityselector) + * [TripDescriptor](#message-tripdescriptor) + * [ScheduleRelationship](#enum-schedulerelationship-1) + * [Cause](#enum-cause) + * [Effect](#enum-effect) + * [TranslatedString](#message-translatedstring) + * [Translation](#message-translation) + +# Elements + +## _message_ FeedMessage + +The contents of a feed message. Each message in the stream is obtained as a response to an appropriate HTTP GET request. A realtime feed is always defined with relation to an existing GTFS feed. All the entity ids are resolved with respect to the GTFS feed. + +#### Fields + +|_**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|-----------------|------------|-------------------|-------------------| +|**header** | [FeedHeader](#message-feedheader) | required | Metadata about this feed and feed message. | +|**entity** | [FeedEntity](#message-feedentity) | repeated | Contents of the feed. | + +## _message_ FeedHeader + +Metadata about a feed, included in feed messages. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | Version of the feed specification. The current version is 1.0. | +| **incrementality** | [Incrementality](#enum-incrementality) | optional | +| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | This timestamp identifies the moment when the content of this feed has been created (in server time). In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). To avoid time skew between systems producing and consuming realtime information it is strongly advised to derive timestamp from a time server. It is completely acceptable to use Stratum 3 or even lower strata servers since time differences up to a couple of seconds are tolerable. | + +## _enum_ Incrementality + +Determines whether the current fetch is incremental. + +* **FULL_DATASET**: this feed update will overwrite all preceding realtime information for the feed. Thus this update is expected to provide a full snapshot of all known realtime information. +* **DIFFERENTIAL**: currently, this mode is **unsupported** and behavior is **unspecified** for feeds that use this mode. There are discussions on the [GTFS Realtime mailing list](http://groups.google.com/group/gtfs-realtime) around fully specifying the behavior of DIFFERENTIAL mode and the documentation will be updated when those discussions are finalized. + +#### Values + +| _**Value**_ | +|-------------| +| **FULL_DATASET** | +| **DIFFERENTIAL** | + +## _message_ FeedEntity + +A definition (or update) of an entity in the transit feed. If the entity is not being deleted, exactly one of 'trip_update', 'vehicle' and 'alert' fields should be populated. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | Feed-unique identifier for this entity. The ids are used only to provide incrementality support. The actual entities referenced by the feed must be specified by explicit selectors (see EntitySelector below for more info). | +| **is_deleted** | [bool](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Whether this entity is to be deleted. Relevant only for incremental fetches. | +| **trip_update** | [TripUpdate](#message-tripupdate) | optional | Data about the realtime departure delays of a trip. | +| **vehicle** | [VehiclePosition](#message-vehicleposition) | optional | Data about the realtime position of a vehicle. | +| **alert** | [Alert](#message-alert) | optional | Data about the realtime alert. | + +## _message_ TripUpdate + +Realtime update on the progress of a vehicle along a trip. Please also refer to the general discussion of the [trip updates entities](trip-updates.md). + +Depending on the value of ScheduleRelationship, a TripUpdate can specify: + +* A trip that proceeds along the schedule. +* A trip that proceeds along a route but has no fixed schedule. +* A trip that has been added or removed with regard to schedule. + +The updates can be for future, predicted arrival/departure events, or for past events that already occurred. In most cases information about past events is a measured value thus its uncertainty value is recommended to be 0\. Although there could be cases when this does not hold so it is allowed to have uncertainty value different from 0 for past events. If an update's uncertainty is not 0, either the update is an approximate prediction for a trip that has not completed or the measurement is not precise or the update was a prediction for the past that has not been verified after the event occurred. + +Note that the update can describe a trip that has already completed.To this end, it is enough to provide an update for the last stop of the trip. If the time of arrival at the last stop is in the past, the client will conclude that the whole trip is in the past (it is possible, although inconsequential, to also provide updates for preceding stops). This option is most relevant for a trip that has completed ahead of schedule, but according to the schedule, the trip is still proceeding at the current time. Removing the updates for this trip could make the client assume that the trip is still proceeding. Note that the feed provider is allowed, but not required, to purge past updates - this is one case where this would be practically useful. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **trip** | [TripDescriptor](#message-tripdescriptor) | required | The Trip that this message applies to. There can be at most one TripUpdate entity for each actual trip instance. If there is none, that means there is no prediction information available. It does *not* mean that the trip is progressing according to schedule. | +| **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | optional | Additional information on the vehicle that is serving this trip. | +| **stop_time_update** | [StopTimeUpdate](#message-stoptimeupdate) | repeated | Updates to StopTimes for the trip (both future, i.e., predictions, and in some cases, past ones, i.e., those that already happened). The updates must be sorted by stop_sequence, and apply for all the following stops of the trip up to the next specified one. | +| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Moment at which the vehicle's real-time progress was measured. In POSIX time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC). | +| **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional |The current schedule deviation for the trip. Delay should only be specified when the prediction is given relative to some existing schedule in GTFS.
Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time.
Delay information in StopTimeUpdates take precedent of trip-level delay information, such that trip-level delay is only propagated until the next stop along the trip with a StopTimeUpdate delay value specified.
Feed providers are strongly encouraged to provide a TripUpdate.timestamp value indicating when the delay value was last updated, in order to evaluate the freshness of the data.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| + +## _message_ StopTimeEvent + +Timing information for a single predicted event (either arrival or departure). Timing consists of delay and/or estimated time, and uncertainty. + +* delay should be used when the prediction is given relative to some existing schedule in GTFS. +* time should be given whether there is a predicted schedule or not. If both time and delay are specified, time will take precedence (although normally, time, if given for a scheduled trip, should be equal to scheduled time in GTFS + delay). + +Uncertainty applies equally to both time and delay. The uncertainty roughly specifies the expected error in true delay (but note, we don't yet define its precise statistical meaning). It's possible for the uncertainty to be 0, for example for trains that are driven under computer timing control. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time. | +| **time** | [int64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Event as absolute time. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | +| **uncertainty** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | If uncertainty is omitted, it is interpreted as unknown. To specify a completely certain prediction, set its uncertainty to 0. | + +## _message_ StopTimeUpdate + +Realtime update for arrival and/or departure events for a given stop on a trip. Please also refer to the general discussion of stop time updates in the [TripDescriptor](#message-tripdescriptor) and [trip updates entities](trip-updates.md) documentation. + +Updates can be supplied for both past and future events. The producer is allowed, although not required, to drop past events. +The update is linked to a specific stop either through stop_sequence or stop_id, so one of these fields must necessarily be set. If the same stop_id is visited more than once in a trip, then stop_sequence should be provided in all StopTimeUpdates for that stop_id on that trip. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Must be the same as in stop_times.txt in the corresponding GTFS feed. | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Must be the same as in stops.txt in the corresponding GTFS feed. | +| **arrival** | [StopTimeEvent](#message-stoptimeevent) | optional | +| **departure** | [StopTimeEvent](#message-stoptimeevent) | optional | +| **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | optional | The default relationship is SCHEDULED. | + +## _enum_ ScheduleRelationship + +The relation between this StopTime and the static schedule. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **SCHEDULED** | The vehicle is proceeding in accordance with its static schedule of stops, although not necessarily according to the times of the schedule. This is the **default** behavior. At least one of arrival and departure must be provided. If the schedule for this stop contains both arrival and departure times then so must this update. | +| **SKIPPED** | The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional. | +| **NO_DATA** | No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied. | + +## _message_ VehiclePosition + +Realtime positioning information for a given vehicle. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **trip** | [TripDescriptor](#message-tripdescriptor) | optional | The Trip that this vehicle is serving. Can be empty or partial if the vehicle can not be identified with a given trip instance. | +| **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | optional | Additional information on the vehicle that is serving this trip. Each entry should have a **unique** vehicle id. | +| **position** | [Position](#message-position) | optional | Current position of this vehicle. | +| **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The stop sequence index of the current stop. The meaning of current_stop_sequence (i.e., the stop that it refers to) is determined by current_status. If current_status is missing IN_TRANSIT_TO is assumed. | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. | +| **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | optional | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | +| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | +| **congestion_level** | [CongestionLevel](#enum-congestionlevel) | optional | +| _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _optional_ |The degree of passenger occupancy of the vehicle.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| + +## _enum_ VehicleStopStatus + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **INCOMING_AT** | The vehicle is just about to arrive at the stop (on a stop display, the vehicle symbol typically flashes). | +| **STOPPED_AT** | The vehicle is standing at the stop. | +| **IN_TRANSIT_TO** | The vehicle has departed the previous stop and is in transit. | + +## _enum_ CongestionLevel + +Congestion level that is affecting this vehicle. + +#### Values + +| _**Value**_ | +|-------------| +| **UNKNOWN_CONGESTION_LEVEL** | +| **RUNNING_SMOOTHLY** | +| **STOP_AND_GO** | +| **CONGESTION** | +| **SEVERE_CONGESTION** | + +## _enum OccupancyStatus_ + +The degree of passenger occupancy for the vehicle. + +**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. + +#### _Values_ + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| _**EMPTY**_ | _The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ | +| _**MANY_SEATS_AVAILABLE**_ | _The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ | +| _**FEW_SEATS_AVAILABLE**_ | _The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ | +| _**STANDING_ROOM_ONLY**_ | _The vehicle can currently accomodate only standing passengers._ | +| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle can currently accomodate only standing passengers and has limited space for them._ | +| _**FULL**_ | _The vehicle is considered full by most measures, but may still be allowing passengers to board._ | +| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle can not accept passengers._ | + +## _message_ Alert + +An alert, indicating some sort of incident in the public transit network. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **active_period** | [TimeRange](#message-timerange) | repeated | Time when the alert should be shown to the user. If missing, the alert will be shown as long as it appears in the feed. If multiple ranges are given, the alert will be shown during all of them. | +| **informed_entity** | [EntitySelector](#message-entityselector) | repeated | Entities whose users we should notify of this alert. | +| **cause** | [Cause](#enum-cause) | optional | +| **effect** | [Effect](#enum-effect) | optional | +| **url** | [TranslatedString](#message-translatedstring) | optional | The URL which provides additional information about the alert. | +| **header_text** | [TranslatedString](#message-translatedstring) | optional | Header for the alert. This plain-text string will be highlighted, for example in boldface. | +| **description_text** | [TranslatedString](#message-translatedstring) | optional | 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. | + +## _enum_ Cause + +Cause of this alert. + +#### Values + +| _**Value**_ | +|-------------| +| **UNKNOWN_CAUSE** | +| **OTHER_CAUSE** | +| **TECHNICAL_PROBLEM** | +| **STRIKE** | +| **DEMONSTRATION** | +| **ACCIDENT** | +| **HOLIDAY** | +| **WEATHER** | +| **MAINTENANCE** | +| **CONSTRUCTION** | +| **POLICE_ACTIVITY** | +| **MEDICAL_EMERGENCY** | + +## _enum_ Effect + +The effect of this problem on the affected entity. + +#### Values + +| _**Value**_ | +|-------------| +| **NO_SERVICE** | +| **REDUCED_SERVICE** | +| **SIGNIFICANT_DELAYS** | +| **DETOUR** | +| **ADDITIONAL_SERVICE** | +| **MODIFIED_SERVICE** | +| **OTHER_EFFECT** | +| **UNKNOWN_EFFECT** | +| **STOP_MOVED** | + +## _message_ TimeRange + +A time interval. The interval is considered active at time `t` if `t` is greater than or equal to the start time and less than the end time. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **start** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Start time, in POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). If missing, the interval starts at minus infinity. | +| **end** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | End time, in POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). If missing, the interval ends at plus infinity. | + +## _message_ Position + +A geographic position of a vehicle. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **latitude** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | Degrees North, in the WGS-84 coordinate system. | +| **longitude** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | Degrees East, in the WGS-84 coordinate system. | +| **bearing** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Bearing, in degrees, clockwise from True North, i.e., 0 is North and 90 is East. This can be the compass bearing, or the direction towards the next stop or intermediate location. This should not be deduced from the sequence of previous positions, which clients can compute from previous data. | +| **odometer** | [double](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Odometer value, in meters. | +| **speed** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Momentary speed measured by the vehicle, in meters per second. | + +## _message_ TripDescriptor + +A descriptor that identifies an instance of a GTFS trip, or all instances of a trip along a route. To specify a single trip instance, the trip_id (and if necessary, start_time) is set. If route_id is also set, then it should be same as one that the given trip corresponds to. To specify all the trips along a given route, only the route_id should be set. Note that if the trip_id is not known, then station sequence ids in TripUpdate are not sufficient, and stop_ids must be provided as well. In addition, absolute arrival/departure times must be provided. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The trip_id from the GTFS feed that this selector refers to. For non frequency-based trips, this field is enough to uniquely identify the trip. For frequency-based trip, start_time and start_date might also be necessary. | +| **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The route_id from the GTFS that this selector refers to. | +| **direction_id** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The direction_id from the GTFS feed trips.txt file, indicating the direction of travel for trips this selector refers to.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
| +| **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The initially scheduled start time of this trip instance. When the trip_id corresponds to a non-frequency-based trip, this field should either be omitted or be equal to the value in the GTFS feed. When the trip_id correponds to a frequency-based trip, the start_time must be specified for trip updates and vehicle positions. If the trip corresponds to exact_times=1 GTFS record, then start_time must be some multiple (including zero) of headway_secs later than frequencies.txt start_time for the corresponding time period. If the trip corresponds to exact_times=0, then its start_time may be arbitrary, and is initially expected to be the first departure of the trip. Once established, the start_time of this frequency-based trip should be considered immutable, even if the first departure time changes -- that time change may instead be reflected in a StopTimeUpdate. Format and semantics of the field is same as that of GTFS/frequencies.txt/start_time, e.g., 11:15:35 or 25:15:35. | +| **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The scheduled start date of this trip instance. This field must be provided to disambiguate trips that are so late as to collide with a scheduled trip on a next day. For example, for a train that departs 8:00 and 20:00 every day, and is 12 hours late, there would be two distinct trips on the same time. This field can be provided but is not mandatory for schedules in which such collisions are impossible - for example, a service running on hourly schedule where a vehicle that is one hour late is not considered to be related to schedule anymore. In YYYYMMDD format. | +| **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship-1) | optional | + +## _enum_ ScheduleRelationship + +The relation between this trip and the static schedule. If a trip is done in accordance with temporary schedule, not reflected in GTFS, then it shouldn't be marked as SCHEDULED, but marked as ADDED. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **SCHEDULED** | Trip that is running in accordance with its GTFS schedule, or is close enough to the scheduled trip to be associated with it. | +| **ADDED** | An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to respond to sudden passenger load. | +| **UNSCHEDULED** | A trip that is running with no schedule associated to it, for example, if there is no schedule at all. | +| **CANCELED** | A trip that existed in the schedule but was removed. | + +## _message_ VehicleDescriptor + +Identification information for the vehicle performing the trip. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field | +| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle. | +| **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The license plate of the vehicle. | + +## _message_ EntitySelector + +A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, then the matching has to apply to all the given specifiers. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **agency_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | +| **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | +| **route_type** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | +| **trip** | [TripDescriptor](#message-tripdescriptor) | optional | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | + +## _message_ TranslatedString + +An internationalized message containing per-language versions of a snippet of text or a URL. One of the strings from a message will be picked up. The resolution proceeds as follows: If the UI language matches the language code of a translation, the first matching translation is picked. If a default UI language (e.g., English) matches the language code of a translation, the first matching translation is picked. If some translation has an unspecified language code, that translation is picked. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **translation** | [Translation](#message-translation) | repeated | At least one translation must be provided. | + +## _message_ Translation + +A localized string mapped to a language. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|-------------------|-------------------| +| **text** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | A UTF-8 string containing the message. | +| **language** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | BCP-47 language code. Can be omitted if the language is unknown or if no internationalization is done at all for the feed. At most one translation is allowed to have an unspecified language tag. | diff --git a/transit/gtfs-realtime/spec/en/service-alerts.md b/transit/gtfs-realtime/spec/en/service-alerts.md new file mode 100644 index 000000000..c27031ecc --- /dev/null +++ b/transit/gtfs-realtime/spec/en/service-alerts.md @@ -0,0 +1,56 @@ +Service alerts allow you to provide updates whenever there is disruption on the network. Delays and cancellations of individual trips should usually be communicated using [Trip updates](trip-updates.md). + +You have the option to provide the following: + +* URL - link to your site explaining more about the alert +* Header text - a summary of the alert +* Description - a full description of the alert, which will always be shown alongside the header (so should not repeat this information). + +### Time Range + +The alert will be displayed where appropriate within the given time range. This range should cover the entire time that the alert is useful for the passenger to see. + +If no time is given, we will display the alert for as long as it is in the feed. If multiple ranges are given, we will display during all of them. + +### Entity Selector + +Entity selector allows you specify exactly which parts of the network this alert affects, so that we can display only the most appropriate alerts to the user. You may include multiple entity selectors for alerts which affect multiple entities. + +Entities are selected using their GTFS identifiers, and you can select any of the following: + +* Agency - affects the whole network +* Route - affects the whole route +* Route type - affects any route of this type. e.g. all subways. +* Trip - affects a particular trip +* Stop - affects a particular stop + +### Cause + +What is the cause of this alert? You may specify one of the following: + +* Unknown cause +* Other cause (not represented by any of these options) +* Technical problem +* Strike +* Demonstration +* Accident +* Holiday +* Weather +* Maintenance +* Construction +* Police activity +* Medical emergency + +### Effect + +What effect does this problem have on the specified entity? You may specify one of the following: + +* No service +* Reduced service +* Significant delays (insignificant delays should only be provided through [Trip updates](trip-updates.md)). +* Detour +* Additional service +* Modified service +* Stop moved +* Other effect (not represented by any of these options) +* Unknown effect diff --git a/transit/gtfs-realtime/spec/en/trip-updates.md b/transit/gtfs-realtime/spec/en/trip-updates.md new file mode 100644 index 000000000..60933605f --- /dev/null +++ b/transit/gtfs-realtime/spec/en/trip-updates.md @@ -0,0 +1,100 @@ +Trip updates represent fluctuations in the timetable. We would expect to receive trip updates for all trips you have scheduled that are realtime-capable. These updates would give a predicted arrival or departure time for stops along the route. Trip updates can also provide for more complex scenarios where trips are canceled or added to the schedule, or even re-routed. + +**Reminder:** In [GTFS](https://developers.google.com/transit/gtfs/), a trip is a sequence of two of more stops occurring at a specific time. + +There should be **at most** one trip update for each scheduled trip. In case there is no trip update for a scheduled trip, it will be concluded that no realtime data is available for the trip. The data consumer should **not** assume that the trip is running on time. + +## Stop Time Updates + +A trip update consists of one or more updates to vehicle stop times, which are referred to as [StopTimeUpdates](reference.md#StopTimeUpdate). These can be supplied for past and future stop times. You are allowed, but not required, to drop past stop times. Producers should not drop a past `StopTimeUpdate` if it refers to a stop with a scheduled arrival time in the future for the given trip (i.e. the vehicle has passed the stop ahead of schedule), as otherwise it will be concluded that there is no update for this stop. + +For example, if the following data appears in the GTFS-rt feed: + +* Stop 4 – Predicted at 10:18am (scheduled at 10:20am – 2 min early) +* Stop 5 – Predicted at 10:30am (scheduled at 10:30am – on time) + +...the prediction for Stop 4 cannot be dropped from the feed until 10:21am, even if the bus actually passes the stop at 10:18am. If the `StopTimeUpdate` for Stop 4 was dropped from the feed at 10:18am or 10:19am, and the scheduled arrival time is 10:20am, then the consumer should assume that no real-time information exists for Stop 4 at that time, and schedule data from GTFS should be used. + +Each [StopTimeUpdate](reference.md#StopTimeUpdate) is linked to a stop. Ordinarily this can be done using either a GTFS stop_sequence or a GTFS stop_id. However, in the case you are providing an update for a trip without a GTFS trip_id, you must specify stop_id as stop_sequence has no value. The stop_id must still reference a stop_id in GTFS. If the same stop_id is visited more than once in a trip, then stop_sequence should be provided in all StopTimeUpdates for that stop_id on that trip. + +The update can provide a exact timing for **arrival** and/or **departure** at a stop in [StopTimeUpdates](reference.md#StopTimeUpdate) using [StopTimeEvent](reference.md#StopTimeEvent). This should contain either an absolute **time** or a **delay** (i.e. an offset from the scheduled time in seconds). Delay can only be used in case the trip update refers to a scheduled GTFS trip, as opposed to a frequency-based trip. In this case, time should be equal to scheduled time + delay. You may also specify **uncertainty** of the prediction along with [StopTimeEvent](reference.md#StopTimeEvent), which is discussed in more detail in section [Uncertainty](#uncertainty) further down the page. + +For each [StopTimeUpdate](reference.md#StopTimeUpdate), the default schedule relationship is **scheduled**. (Note that this is different from the schedule relationship for the trip). You may change this to **skipped** if the stop will not be stopped at, or **no data** if you only have realtime data for some of the trip. + +**Updates should be sorted by stop_sequence** (or stop_ids in the order they occur in the trip). + +If one or more stops are missing along the trip the update is propagated to all subsequent stops. This means that updating a stop time for a certain stop will change all subsequent stops in the absence of any other information. + +**Example 1** + +For a trip with 20 stops, a [StopTimeUpdate](reference.md#StopTimeUpdate) with arrival delay and departure delay of 0 ([StopTimeEvents](reference.md#StopTimeEvent)) for stop_sequence of the current stop means that the trip is exactly on time. + +**Example 2** + +For the same trip instance, three [StopTimeUpdates](reference.md#StopTimeUpdate) are provided: + +* delay of 300 seconds for stop_sequence 3 +* delay of 60 seconds for stop_sequence 8 +* delay of unspecified duration for stop_sequence 10 + +This will be interpreted as: + +* stop_sequences 1,2 have unknown delay. +* stop_sequences 3,4,5,6,7 have delay of 300 seconds. +* stop_sequences 8,9 have delay of 60 seconds. +* stop_sequences 10,..,20 have unknown delay. + +### Trip Descriptor + +The information provided by the trip descriptor depends on the schedule relationship of trip you are updating. There are a number of options for you to set: + +|_**Value**_|_**Comment**_| +|-----------|-------------| +| **Scheduled** | This trip is running according to a GTFS schedule, or is close enough to still be associated with it. | +| **Added** | This trip was not scheduled and has been added. For example, to cope with demand, or replace a broken down vehicle. | +| **Unscheduled** | This trip is running and is never associated with a schedule. For example, if there is no schedule and the buses run on a shuttle service. | +| **Canceled** | This trip was scheduled, but is now removed. | + +In most cases, you should provide the trip_id of the scheduled trip in GTFS that this update relates to. + +#### Systems with repeated trip_ids + +For systems using repeated trip_ids, for example trips modeled using frequencies.txt, that is frequency-based trips, the trip_id is not in itself a unique identifier of a single journey, as it lacks a +specific time component. In order to uniquely identify such trips within a +TripDescriptor, a triple of identifiers must be provided: + +* __trip_id__ +* __start_time__ +* __start_date__ + +start_time should be first published, and any subsequent feed updates should use +that same start_time when referring to the same journey. StopTimeUpdates +should be used to indicate adjustments; start_time does not have to be precisely +the departure time from the first station, although it should be pretty close to +that time. + +For example, let’s say we decide at 10:00, May, 25th 2015, that a trip with +trip_id=T will start at start_time=10:10:00, and provide this information via +realtime feed at 10:01. By 10:05 we suddenly know that the trip will start not +at 10:10 but at 10:13. In our new realtime feed we can still identify this trip +as (T, 2015-05-25, 10:10:00) but provide a StopTimeUpdate with departure from +first stop at 10:13:00. + +#### Alternative trip matching + +Trips which are not frequency based may also be uniquely identified by a +TripDescriptor including the combination of: + +* __route_id__ +* __direction_id__ +* __start_time__ +* __start_date__ + +where start_time is the scheduled start time as defined in the static schedule, as long as the combination of ids provided resolves to a unique trip. + + +## Uncertainty + +Uncertainty applies to both the time and the delay value of a [StopTimeUpdate](reference.md#StopTimeUpdate). The uncertainty roughly specifies the expected error in true delay as an integer in seconds (but note, the precise statistical meaning is not defined yet). It's possible for the uncertainty to be 0, for example for trains that are driven under computer timing control. + +As an example a long-distance bus that has an estimated delay of 15 minutes arriving to its next stop within a 4 minute window of error (that is +2 / -2 minutes) will have an Uncertainty value of 240. diff --git a/transit/gtfs-realtime/spec/en/vehicle-positions.md b/transit/gtfs-realtime/spec/en/vehicle-positions.md new file mode 100644 index 000000000..62da24dd7 --- /dev/null +++ b/transit/gtfs-realtime/spec/en/vehicle-positions.md @@ -0,0 +1,59 @@ +Vehicle position is used to provide automatically generated information on the location of a vehicle, such as from a GPS device on board. A single vehicle position should be provided for every vehicle that is capable of providing it. + +The trip that the vehicle is currently serving should be given through a [trip descriptor](reference.md#TripDescriptor). You can also provide a [vehicle descriptor](reference.md#VehicleDescriptor), which specifies a precise physical vehicle that you are providing updates about. Documentation is provided below. + +A **timestamp** denoting the time when the position reading was taken can be provided. Note that this is different from the timestamp in the feed header, which is the time that this message was generated by the server. + +**Current passage** can also be provided (either as a `stop_sequence` or `stop_id`). This is a reference to the stop that the vehicle is either on its way to, or already stopped at. + +## Position + +Position contains the location data within Vehicle Position. Latitude and longitude are required, the other fields are optional. These types of data are: + +* **Latitude** - degrees North, in the WGS-84 coordinate system +* **Longitude** - degrees East, in the WGS-84 coordinate system +* **Bearing** - direction that the vehicle is facing +* **Odometer** - the distance that the vehicle has travelled +* **Speed** - momentary speed measured by the vehicle, in meters per second + +## Congestion Level + +Vehicle position also allows the agency to specify the congestion level that the vehicle is currently experiencing. Congestion can be classed under the following categories: + +* Unknown congestion level +* Running smoothly +* Stop and go +* Congestion +* Severe congestion + +It is up to the agency to classify what you class as each type of congestion. Our guidance is that severe congestion is only used in situations where the traffic is so congested that people are leaving their cars. + +## Occupancy status + +Vehicle position also allows the agency to specify the degree of passenger occupancy for the vehicle. Occupancy status can be classed under the following categories: + +* Empty +* Many seats available +* Few seats available +* Standing room only +* Crushed standing room only +* Full +* Not accepting passengers + +This field is still **experimental**, and subject to change. It may be formally adopted in the future. + +## VehicleStopStatus + +Vehicle stop status gives more meaning to the status of a vehicle in relation with a stop that it is currently approaching or is at. It can be set to any of these values. + +* **Incoming at** - the vehicle is about to arrive at the referenced stop +* **Stopped at** - the vehicle is stopped at the referenced stop +* **In transit to** - the referenced stop is the next stop for the vehicle - **default** + +## Vehicle Descriptor + +Vehicle descriptor describes a precise physical vehicle and can contain any of the following attributes: + +* **ID** - internal system of identification for the vehicle. Should be unique to the vehicle +* **Label** - a user visible label - for example the name of a train +* **License plate** - the actual license plate of the vehicle diff --git a/transit/gtfs-realtime/spec/es/README.md b/transit/gtfs-realtime/spec/es/README.md new file mode 100644 index 000000000..ac2154f95 --- /dev/null +++ b/transit/gtfs-realtime/spec/es/README.md @@ -0,0 +1,50 @@ +GTFS en tiempo real es una especificación de feed que permite que las empresas de tranporte público proporcionen actualizaciones en tiempo real sobre su flota a los programadores de la aplicación. Es una extensión de [GTFS](https://developers.google.com/transit/gtfs/reference) (Especificación general de feeds de transporte público), un formato de datos abierto para los horarios de transporte público y la información geográfica asociada. GTFS en tiempo real fue diseñado en torno a la facilidad de implementación, buena interoperabilidad GTFS y un enfoque en la información al pasajero. + +La especificación fue diseñada a través de una asociación de las empresas miembro de las [Actualizaciones del transporte público en tiempo real](https://developers.google.com/transit/google-transit#LiveTransitUpdates) iniciales, diferentes programadores de transporte público y Google. La especificación está publicada bajo la licencia [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0). + +## ¿Cómo empiezo? + +1. Sigue leyendo el resumen general a continuación. +2. Decide qué [tipos de feed](feed-types.md) proporcionarás. +3. Consulta los [ejemplos de feeds](examples/). +4. Crea tus propios feeds mediante la [referencia](reference.md). +5. Publica tu feed. + +## Resumen general de los tipos de feed GTFS en tiempo real + +La especificación es compatible actualmente con los siguientes tipos de información: + +* **Actualizaciones de viaje**: retrasos, cancelaciones, cambios de ruta +* **Alertas del servicio**: traslados de paradas o eventos imprevistos que afectan una estación, ruta o toda la red +* **Posiciones del vehículo**: información sobre los vehículos, incluidos la ubicación y el nivel de congestión + +Las actualizaciones de cada tipo se proporcionan en un feed separado. Los feeds se muestran a través de HTTP y se actualizan con frecuencia. El archivo en sí es un archivo binario normal, por lo que cualquier tipo de servidor web puede alojar y mostrar el archivo (es posible utilizar otros protocolos de transferencia también). Alternativamente, los servidores de aplicaciones web también se podrían utilizar, los cuales devolverán el feed como una respuesta a una solicitud GET de HTTP válida. No hay limitaciones en cuanto a la frecuencia ni al método exacto de cómo el feed debe ser actualizado o recuperado. + +Ya que GTFS en tiempo real te permite presentar el estado _real_ de tu flota, el feed debe ser actualizado con frecuencia, de preferencia cuando se ingresen nuevos datos de tu sistema de ubicación automática de vehículos. + +[Más información sobre los tipos de feed...](feed-types.md) + +## Formato de los datos + +El formato de intercambio de datos de GTFS en tiempo real se basa en [Búferes de protocolo](https://developers.google.com/protocol-buffers/). + +Los búferes de protocolo son un mecanismo de lenguaje y plataforma neutral para serializar datos estructurados (como XML, pero más pequeño, rápido y simple). La estructura de datos se define en un archivo [gtfs-realtime.proto](gtfs-realtime.proto), que luego se utiliza para generar el código fuente para leer y escribir fácilmente tus datos estructurados desde y hacia una variedad de flujos de datos, mediante diferentes lenguajes, por ejemplo Java, C++ o Python. + +[Más información sobre los búferes de protocolo](https://developers.google.com/protocol-buffers/)... + +## Estructura de los datos + +La jerarquía de los elementos y las definiciones de su tipo están especificadas en el archivo [gtfs-realtime.proto](gtfs-realtime.proto). + +Este archivo de texto se utiliza para generar las bibliotecas necesarias en tu lenguaje de programación seleccionado. Estas bibliotecas proporcionan las clases y funciones necesarias para generar feeds GTFS en tiempo real válidos. Las bibliotecas no solo hacen que la creación del feed sea más fácil, sino que también garantizan que solo se produzcan feeds válidos. + +[Más información sobre la estructura de los datos.](reference.md) + +## Obtener ayuda + +Para participar en los debates sobre GTFS en tiempo real y sugerir cambios y adiciones a la especificación, únete al [grupo de debate de GTFS en tiempo real](http://groups.google.com/group/gtfs-realtime). + +## Google Maps y Actualizaciones de transporte público en tiempo real + +Una de las posibles aplicaciones que utiliza GTFS en tiempo real es [Actualizaciones de transporte público en tiempo real](https://developers.google.com/transit/google-transit#LiveTransitUpdates), una función de Google Maps que proporciona a los usuarios información de transporte público en tiempo real. Si trabajas para una empresa de transporte público que está interesada en proporcionar actualizaciones en tiempo real para Google Maps, visita la [Página de socios de Google Transit](http://maps.google.com/help/maps/transit/partners/live-updates.html). + diff --git a/transit/gtfs-realtime/spec/es/examples/README.md b/transit/gtfs-realtime/spec/es/examples/README.md new file mode 100644 index 000000000..7db8d1e27 --- /dev/null +++ b/transit/gtfs-realtime/spec/es/examples/README.md @@ -0,0 +1,4 @@ +Los siguientes ejemplos muestran una representación textual de los feeds. Durante el desarrollo, es más conveniente producir una salida de búfer del protocolo ASCII para una depuración más fácil. Puedes comparar tu salida de texto con estos ejemplos para comprobar la validez de los datos. + +* [Alertas de Google](alerts.asciipb) +* [Actualización de viaje (conjunto de datos completo)](trip-updates-full.asciipb) diff --git a/transit/gtfs-realtime/spec/es/examples/alerts.asciipb b/transit/gtfs-realtime/spec/es/examples/alerts.asciipb new file mode 100644 index 000000000..663c405db --- /dev/null +++ b/transit/gtfs-realtime/spec/es/examples/alerts.asciipb @@ -0,0 +1,72 @@ +# Información del encabezado +header { + # Versión de la especificación de velocidad. Actualmente "1.0". + gtfs_realtime_version: "1.0" + + # Determina si el conjunto de datos se completó o tiene un incremento gradual. + incrementality: FULL_DATASET + + # La hora en la que se generó el conjunto de datos en el servidor + # para determinar la secuencia de feeds de alerta. + timestamp: 1284457468 +} +# Se pueden incluir varias entidades en el feed. +entity { + # Identificador único para la entidad + id: "0" + + # "Tipo" de la entidad + alert { + # Se pueden definir varios períodos cuando la alerta está activa. + active_period { + # Hora de inicio en formato epoch POSIX + start: 1284457468 + # Hora de fin en formato epoch POSIX + end: 1284468072 + } + # Selecciona qué entidades GTFS serán afectadas. + informed_entity { + # Parámetros válidos: agency_id, route_id, route_type, + # stop_id, viaje (consultar TripDescriptor) + route_id: "219" + } + # Se pueden entregar selectores múltiples (informed_entity). + informed_entity { + stop_id: "16230" + } + + # Causa de la alerta: consultar gtfs-realtime.proto para valores válidos + cause: CONSTRUCTION + # Efecto de la alerta: consultar gtfs-realtime.proto para valores reales + effect: DETOUR + + # La URL dada proporciona información adicional. + url { + # Varios idiomas/traducciones compatibles + translation { + # La página está alojada fuera de Google (en el proveedor o la empresa, etc.). + text: "http://www.sometransitagency/alerts" + language: "es" + } + } + + # El encabezado para la alerta será destacado. + header_text { + # Varios idiomas o traducciones son compatibles. + translation { + text: "La parada en Elm street está cerrada, detenerse temporalmente en Oak street" + language: "es" + } + } + + # Descripción de la alerta. Información adicional al texto del encabezado. + description_text { + # Varios idiomas o traducciones son compatibles. + translation { + text: "Debido a una construcción en Elm street, la parada está cerrada. La parada temporal se puede encontrar a 300 metros al norte de Oak street." + language: "es" + } + } + } +} + diff --git a/transit/gtfs-realtime/spec/es/examples/trip-updates-full.asciipb b/transit/gtfs-realtime/spec/es/examples/trip-updates-full.asciipb new file mode 100644 index 000000000..f8e653964 --- /dev/null +++ b/transit/gtfs-realtime/spec/es/examples/trip-updates-full.asciipb @@ -0,0 +1,79 @@ +# Información del encabezado +header { + # Especificación de la versión de la velocidad. La versión "1.0" actual + gtfs_realtime_version: "1.0" + # determina si el conjunto de datos se completó o continúa creciendo + incrementality: FULL_DATASET + # en el momento en el que se generó en el servidor. + timestamp: 1284457468 +} + +# Se pueden incluir varias entidades en el +entity { + # identificador único del feed correspondiente a la entidad + id: "simple-trip" + + # "tipo" de la entidad. + trip_update { + trip { + # Selecciona qué entidad GTFS (viaje) se verá afectada. + trip_id: "trip-1" + } + # Actualización de la información del programa + stop_time_update { + # Se selecciona qué parada se ve afectada + stop_sequence: 3 + # para que el vehículo llegue + arrival { + # cinco segundos tarde. + delay: 5 + } + } + # La demora de este vehículo se extiende a las siguientes paradas. + + # Próxima actualización de la información acerca del programa del vehículo + stop_time_update { + # según el campo stop_sequence. Se actualizará + stop_sequence: 8 + # el horario de llegada original del vehículo (programado) con una + arrival { + # demora de un segundo. + delay: 1 + } + } + # ...Asimismo, la demora se extiende a las siguientes paradas. + + # Próxima actualización de la información acerca del programa del vehículo + stop_time_update { + # según el campo stop_sequence. Se actualizará el horario de llegada del vehículo + stop_sequence: 10 + # con la demora predeterminada de cero segundos (a tiempo) y se extenderá esta actualización + # al resto de las paradas del vehículo. + } + } +} + +# Segunda entidad con información acerca de la actualización de otro viaje +entity { + id: "3" + trip_update { + trip { + # En función de su frecuencia, los viajes se definen según el + # trip_id de la especificación GTFS y el campo + trip_id: "frequency-expanded-trip" + # start_time + start_time: "11:15:35" + } + stop_time_update { + stop_sequence: 1 + arrival { + # Una demora negativa se produce cuando el vehículo se adelanta dos segundos según lo establecido en el programa. + delay: -2 + } + } + stop_time_update { + stop_sequence: 9 + } + } +} + diff --git a/transit/gtfs-realtime/spec/es/feed-types.md b/transit/gtfs-realtime/spec/es/feed-types.md new file mode 100644 index 000000000..13b44f804 --- /dev/null +++ b/transit/gtfs-realtime/spec/es/feed-types.md @@ -0,0 +1,36 @@ +La especificación GTFS en tiempo real admite el envío de tres tipos diferentes de datos en tiempo real. Si bien la sintaxis del archivo [gtfs-realtime.proto](gtfs-realtime.proto) permite que se mezclen distintos tipos de entidades para un feed, solo se puede usar un tipo de entidad por feed. Los resúmenes se ofrecen a continuación, con la documentación completa proporcionada en la sección correspondiente. + +## Actualizaciones de viaje + +#### "El autobús X tiene una demora de cinco minutos". + +Las actualizaciones de viaje ofrecen información acerca de fluctuaciones en el horario. Esperamos recibir actualizaciones de viaje para todos los viajes programados cuya duración se puede predecir en tiempo real. Estas actualizaciones ofrecerían un horario de llegada o salida para las diferentes paradas de la ruta. Las actualizaciones de viaje también pueden brindar información en situaciones más complejas, como cuando los viajes se cancelan o agregan al programa, o como cuando su trayecto se modifica. + +[Más información acerca de las Actualizaciones de viaje...](trip-updates.md) + +## Alertas de servicio + +#### "La estación Y está cerrada por tareas de construcción". + +Las alertas de servicio ofrecen información acerca de los problemas más graves que puede sufrir una entidad en particular. En general, se expresan a través de una descripción textual de la interrupción. + +Pueden representar los problemas que sufren: + +* las estaciones, +* las líneas, +* la red completa, +* etc. + +Una alerta de servicio a menudo consiste en una descripción textual del problema. También permitimos que se incluyan las URL de los sitios en los que se ofrecen más detalles e información más estructurada para poder entender a quién afecta una alerta de servicio. + +[Más información acerca de las Alertas de servicio...](service-alerts.md) + +## Posiciones de los vehículos + +#### "Este autobús se encuentra en la posición X a la hora Y". + +La posición de un vehículo ofrece datos básicos acerca de un vehículo en particular de la red. + +La información más importante consiste en la latitud y longitud donde se encuentra el vehículo. Sin embargo, también podemos usar datos acerca de las lecturas del cuentakilómetros y velocidad actuales del vehículo. + +[Más información acerca las actualizaciones de las Posiciones de los vehículos...](vehicle-positions.md) diff --git a/transit/gtfs-realtime/spec/es/gtfs-realtime.proto b/transit/gtfs-realtime/spec/es/gtfs-realtime.proto new file mode 100644 index 000000000..cc2925333 --- /dev/null +++ b/transit/gtfs-realtime/spec/es/gtfs-realtime.proto @@ -0,0 +1,569 @@ +// Copyright 2015 The GTFS Specifications Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Archivo de definición de protocolo para GTFS en tiempo real. +// +// GTFS en tiempo real permite que las agencias de transporte público brinden a +// los consumidores información en tiempo real acerca de las interrupciones de +// sus servicios (estaciones cerradas, líneas que no funcionan, demoras +// importantes, etc.), la ubicación de sus vehículos y los horarios de llegada +// esperados. +// +// Este protocolo se publica en: +// https://github.com/google/transit/tree/master/gtfs-realtime + +syntax = "proto2"; + +option java_package = "com.google.transit.realtime"; +package transit_realtime; + +// El contenido de un mensaje de feed +// Un feed es un flujo continuo de mensajes de feed. Cada mensaje del flujo se +// obtiene como una respuesta a una solicitud HTTP GET adecuada. +// Un feed en tiempo real siempre se define con relación a un feed GTFS +// existente. Todos los ID de entidad se resuelven con respecto al feed GTFS. +// +// Un feed depende de cierta configuración externa: +// - El feed GTFS correspondiente. +// - Aplicación del feed (actualizaciones, posiciones o alertas). Un feed solo +// debe contener elementos de una aplicación especificada; todas las demás +// entidades se ignorarán. +// - Frecuencia de sondeo. +message FeedMessage { + // Metadatos acerca de este feed y mensaje de feed + required FeedHeader header = 1; + + // Contenido del feed + repeated FeedEntity entity = 2; +} + +// Metadatos acerca de un feed, incluidos en mensajes de feed +message FeedHeader { + // Versión de la especificación de feed + // La versión actual es 1.0. + required string gtfs_realtime_version = 1; + + // Determina si la búsqueda actual es incremental. Actualmente, el modo + // DIFFERENTIAL no es admitido y no se especifica para feeds que usan este + // modo. Existen foros de debate en la lista de correo de GTFS en tiempo real + // sobre la especificación completa del comportamiento del modo DIFFERENTIAL y + // la documentación se actualizará cuando esos foros de debate finalicen. + enum Incrementality { + FULL_DATASET = 0; + DIFFERENTIAL = 1; + } + optional Incrementality incrementality = 2 [default = FULL_DATASET]; + + // Esta marca de tiempo identifica el momento en que se creó el contenido de + // este feed (en tiempo del servidor). En tiempo POSIX (es decir, la cantidad + // de segundos desde el 1.º de enero de 1970 00:00:00 UTC). + optional uint64 timestamp = 3; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; +} + +// Una definición (o actualización) de una entidad en el feed de transporte +// público. +message FeedEntity { + // Los ID se usan solo para proporcionar asistencia sobre el aumento + // incremental. El ID debe ser único dentro de un FeedMessage. Los + // FeedMessages consiguientes pueden contener FeedEntities con el mismo ID. En + // el caso de una actualización DIFFERENTIAL, la nueva FeedEntity con algunos + // ID reemplazará a la antigua FeedEntity con el mismo ID (o la eliminará: + // consulta is_deleted a continuación). Las entidades de GTFS reales (p. ej., + // estaciones, rutas, viajes) a las que hace referencia el feed deben estar + // especificadas por selectores explícitos (consulta EntitySelector a + // continuación para obtener más información). + required string id = 1; + + // Establece si esta entidad debe eliminarse. Relevante solo para búsquedas + // incrementales. + optional bool is_deleted = 2 [default = false]; + + // Datos acerca de la propia entidad. Exactamente uno de los siguientes campos + // debe estar presente (a menos que se esté eliminando la entidad). + optional TripUpdate trip_update = 3; + optional VehiclePosition vehicle = 4; + optional Alert alert = 5; +} + +// +// Entidades usadas en el feed. +// + +// La actualización en tiempo real del progreso de un vehículo a lo largo de un +// viaje. Dependiendo del valor de ScheduleRelationship, un TripUpdate puede +// especificar: +// - Un viaje que continúa según el programa. +// - Un viaje que continúa por la ruta, pero no tiene un programa fijo. +// - Un viaje que se agregó o eliminó con respecto al programa. +// +// Las actualizaciones pueden ser para eventos de llegada/salida futuros +// previstos o para eventos pasados que ya ocurrieron. +// Normalmente, las actualizaciones deben ser más precisas y más certeras +// (consulta incertidumbre a continuación) a medida que los eventos se acercan +// al momento actual. +// Aun cuando eso no sea posible, la información para eventos pasados debe ser +// precisa y certera. En particular, si una actualización apunta a un momento +// pasado, pero la incertidumbre de su actualización no es 0, el cliente debe +// concluir que la actualización es una predicción (errónea) y que el viaje aún +// no se ha completado. +// +// Ten en cuenta que la actualización puede describir un viaje que ya se ha +// completado. A este fin, proporcionar una actualización para la última parada +// del viaje es suficiente. Si tal momento está en el pasado, el cliente +// concluirá que todo el viaje está en el pasado (es posible, aunque ilógico, +// proporcionar también actualizaciones para las paradas precedentes). Esta +// opción es más relevante para un viaje que se ha completado con anticipación a +// lo programado, pero que, de acuerdo con el programa, el viaje todavía +// continúa en este momento. Si se eliminan las actualizaciones para este viaje, +// el cliente puede asumir que el viaje todavía continúa. Ten en cuenta que al +// proveedor del feed se le permite, pero no está obligado a, purgar +// actualizaciones pasadas: en este caso, esto sería útil en la práctica. +message TripUpdate { + // El viaje al que se aplica este mensaje. Puede haber como máximo una + // entidad TripUpdate para cada instancia de viaje real. + // Si no hay ninguna, eso significa que no hay información de predicción + // disponible. *No* significa que el viaje se está realizando de acuerdo con + // la programación. + required TripDescriptor trip = 1; + + // Información adicional sobre el vehículo que está realizando el viaje. + optional VehicleDescriptor vehicle = 3; + + // Información sobre los tiempos para un solo evento previsto (ya sea llegada + // o salida). + // Los horarios consisten en la información sobre demoras o tiempos estimados + // y la incertidumbre. La demora (delay) debe usarse cuando la predicción se + // realiza con relación a una programación existente en GTFS. + // - El tiempo (time) debe darse aunque no haya una programación prevista. Si + // se especifican tanto el tiempo como la demora, el tiempo será prioritario + // (aunque, por lo general, el tiempo, si se otorga para un viaje + // programado, debe ser igual al tiempo programado en GTFS + la demora). + // + // La incertidumbre se aplica de la misma forma tanto al tiempo como a la + // demora. La incertidumbre especifica el error esperado en una demora real + // (pero ten en cuenta, que todavía no definimos su significado estadístico + // preciso). Es posible que la incertidumbre sea 0, por ejemplo, para los + // trenes que funcionan con un control de horarios por computadora. + message StopTimeEvent { + // La demora (en segundos) puede ser positiva (significa que el vehículo + // está retrasado) o negativa (significa que el vehículo está adelantado). + // Una demora de 0 significa que el vehículo está yendo a tiempo. + optional int32 delay = 1; + + // El evento como tiempo absoluto + // En tiempo Unix (es decir, la cantidad de segundos desde el 1.º de enero + // de 1970 00:00:00 UTC). + optional int64 time = 2; + + // Si se omite la incertidumbre, se interpreta como desconocida. + // Si la predicción es desconocida o demasiado incierta, el campo demora (o + // tiempo) debe estar vacío. En tal caso, el campo incertidumbre se ignora. + // Para especificar una predicción completamente cierta, configura su + // incertidumbre en 0. + optional int32 uncertainty = 3; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; + } + + // Actualización en tiempo real para eventos de llegada o salida para una + // determinada parada en un viaje. Se pueden suministrar actualizaciones tanto + // para eventos pasados como para eventos futuros. Al productor se le + // permite, aunque no está obligado a, proporcionar eventos pasados. + message StopTimeUpdate { + // La actualización está vinculada con una parada específica ya sea mediante + // stop_sequence o stop_id, de manera que necesariamente debe configurarse + // uno de los campos que aparecen a continuación. Consulta la documentación + // en TripDescriptor para obtener más información. + + // Debe ser la misma que la de stop_times.txt en el feed GTFS + // correspondiente. + optional uint32 stop_sequence = 1; + // Debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. + optional string stop_id = 4; + + optional StopTimeEvent arrival = 2; + optional StopTimeEvent departure = 3; + + // La relación entre este StopTime y el programa estático. + enum ScheduleRelationship { + // El vehículo continúa conforme a su programa estático de paradas, aunque + // no necesariamente de acuerdo a los horarios del programa. + // Se debe proporcionar al menos uno de los horarios de llegada y salida. + // Si el programa para esta parada contiene los horarios tanto de llegada + // como de salida, entonces esta actualización también debe tenerlos. Una + // actualización con solo una llegada, por ejemplo, cuando el programa + // tiene ambos, indica que el viaje está terminando temprano en esta + // parada. + SCHEDULED = 0; + + // La parada se omite, es decir, el vehículo no se detendrá en esta + // parada. La llegada y la salida son opcionales. + SKIPPED = 1; + + // No hay datos para esta parada. La intención principal de este valor es + // brindar predicciones solo para parte de un viaje, es decir, si la + // última actualización para un viaje tiene un especificador NO_DATA, + // entonces se considerará que tampoco se especifican StopTimes para el + // resto de las paradas del viaje. No se debe suministrar ni la llegada + // ni la salida. + NO_DATA = 2; + } + optional ScheduleRelationship schedule_relationship = 5 + [default = SCHEDULED]; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; + } + + // Actualizaciones a StopTimes para el viaje (tanto futuras, es decir, + // predicciones, como, en algunos casos, pasadas, es decir, aquellas que ya + // ocurrieron). + // Las actualizaciones se deben clasificar por stop_sequence y aplicarse a + // todas las paradas siguientes del viaje hasta la próxima especificada. + // + // Ejemplo 1: + // Para un viaje con 20 paradas, una StopTimeUpdate con demora de llegada y + // demora de salida de 0 para una stop_sequence de la parada actual significa + // que el viaje está llegando exactamente a horario. + // + // Ejemplo 2: + // Para la misma instancia de viaje, se proporcionan 3 StopTimeUpdates: + // - demora de 5 minutos para la stop_sequence 3 + // - demora de 1 minuto para la stop_sequence 8 + // - demora de duración no especificada para la stop_sequence 10 + // Esto se interpretará como: + // - las stop_sequences 3,4,5,6,7 tienen una demora de 5 minutos. + // - las stop_sequences 8,9 tienen una demora de 1 minuto. + // - las stop_sequences 10,... tienen una demora desconocido. + repeated StopTimeUpdate stop_time_update = 2; + + // Momento en el cual se midió el progreso en tiempo real del vehículo. En + // tiempo POSIX (es decir, la cantidad de segundos desde el 1º de enero de + // 1970 00:00:00 UTC). + optional uint64 timestamp = 4; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; +} + +// Información de posicionamiento en tiempo real de un vehículo dado. +message VehiclePosition { + // El viaje que este vehículo está realizando. + // Puede estar vacío o ser parcial si el vehículo no se puede identificar con + // una instancia de viaje dada. + optional TripDescriptor trip = 1; + + // Información adicional sobre el vehículo que está realizando este viaje. + optional VehicleDescriptor vehicle = 8; + + // Posición actual de este vehículo. + optional Position position = 2; + + // El índice de la secuencia de parada de la parada actual. El significado de + // current_stop_sequence (es decir, la parada a la que hace referencia) lo + // determina current_status. + // Si falta current_status, se asume IN_TRANSIT_TO. + optional uint32 current_stop_sequence = 3; + // Identifica la parada actual. El valor debe ser el mismo que el de stops.txt + // en el feed GTFS correspondiente. + optional string stop_id = 7; + + enum VehicleStopStatus { + // El vehículo está a punto de llegar a la parada (en una visualización de + // la parada, el símbolo del vehículo, por lo general, parpadea). + INCOMING_AT = 0; + + // El vehículo está detenido en la parada. + STOPPED_AT = 1; + + // El vehículo ha partido y está en tránsito hacia la siguiente parada. + IN_TRANSIT_TO = 2; + } + // El estado exacto del vehículo con respecto a la parada actual. + // Se ignora si falta el valor en current_stop_sequence. + optional VehicleStopStatus current_status = 4 [default = IN_TRANSIT_TO]; + + // Momento en el cual se midió la posición del vehículo. En tiempo POSIX (es + // decir, la cantidad de segundos desde el 1º de enero de 1970 00:00:00 UTC). + optional uint64 timestamp = 5; + + // El nivel de congestión que está afectando a este vehículo. + enum CongestionLevel { + UNKNOWN_CONGESTION_LEVEL = 0; + RUNNING_SMOOTHLY = 1; + STOP_AND_GO = 2; + CONGESTION = 3; + SEVERE_CONGESTION = 4; // Personas que dejan sus autos. + } + optional CongestionLevel congestion_level = 6; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; +} + +// Una alerta, que indica que existe algún tipo de incidente en la red de +// transporte público. +message Alert { + // Tiempo durante el cual la alerta debe mostrarse al usuario. Si falta, la + // alerta se mostrará durante todo el tiempo en que aparezca en el feed. + // Si se proporcionan múltiples intervalos, la alerta se mostrará durante + // todos ellos. + repeated TimeRange active_period = 1; + + // Entidades a cuyos usuarios debemos notificar esta alerta. + repeated EntitySelector informed_entity = 5; + + // Causa de esta alerta. + enum Cause { + UNKNOWN_CAUSE = 1; + OTHER_CAUSE = 2; // No representable mediante máquina. + TECHNICAL_PROBLEM = 3; + STRIKE = 4; // Los empleados de las empresas de transporte público dejaron de trabajar. + DEMONSTRATION = 5; // Las personas están bloqueando las calles. + ACCIDENT = 6; + HOLIDAY = 7; + WEATHER = 8; + MAINTENANCE = 9; + CONSTRUCTION = 10; + POLICE_ACTIVITY = 11; + MEDICAL_EMERGENCY = 12; + } + optional Cause cause = 6 [default = UNKNOWN_CAUSE]; + + // El efecto de este problema en la entidad afectada. + enum Effect { + NO_SERVICE = 1; + REDUCED_SERVICE = 2; + + // No nos preocupan las demoras NO significativas: son difíciles de + // detectar, tienen un pequeño impacto sobre el usuario y desordenarían los + // resultados ya que son demasiado frecuentes. + SIGNIFICANT_DELAYS = 3; + + DETOUR = 4; + ADDITIONAL_SERVICE = 5; + MODIFIED_SERVICE = 6; + OTHER_EFFECT = 7; + UNKNOWN_EFFECT = 8; + STOP_MOVED = 9; + } + optional Effect effect = 7 [default = UNKNOWN_EFFECT]; + + // La URL que proporciona información adicional acerca de la alerta. + optional TranslatedString url = 8; + + // Encabezado de la alerta. Contiene un breve resumen del texto de la alerta + // como texto simple. + optional TranslatedString header_text = 10; + + // Descripción completa de la alerta como texto simple. La información de la + // descripción debe agregar a la información del encabezado. + optional TranslatedString description_text = 11; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; +} + +// +// Estructuras de datos de bajo nivel que se utilizaron más arriba. +// + +// Un intervalo de tiempo. El intervalo se considera activo a la hora 't' si 't' +// es mayor o igual que la hora de inicio y menor que la hora de finalización. +message TimeRange { + // Hora de inicio, en tiempo POSIX (es decir, la cantidad de segundos desde el + // 1º de enero de 1970 00:00:00 UTC). + // Si falta esta información, el intervalo comienza en el infinito negativo. + optional uint64 start = 1; + + // Hora de finalización, en tiempo POSIX (es decir, la cantidad de segundos + // desde el 1º de enero de 1970 00:00:00 UTC). + // Si falta esta información, el intervalo finaliza en el infinito positivo. + optional uint64 end = 2; +} + +// Una posición. +message Position { + // Grados al Norte, en el sistema de coordenadas WGS-84. + required float latitude = 1; + + // Grados al Este, en el sistema de coordenadas WGS-84 + required float longitude = 2; + + // Orientación, en grados, en el sentido de las agujas del reloj desde el + // Norte, es decir, 0 es Norte y 90 es Este. Esto puede ser la orientación de + // la brújula o la dirección hacia la siguiente parada o la ubicación + // intermedia. + // Esto no debe deducirse de las instrucciones de la secuencia de posiciones + // anteriores, que puede calcularse a partir de los datos anteriores. + optional float bearing = 3; + + // Valor del odómetro, en metros. + optional double odometer = 4; + // Velocidad momentánea medida por el vehículo, en metros por segundo. + optional float speed = 5; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; +} + +// Un descriptor que identifica una instancia de un viaje de GTFS, o todas las +// instancias de un viaje por una ruta. +// - Para especificar una sola instancia de viaje, se establece el trip_id (y, +// en caso de ser necesario, el start_time). Si también se establece el +// route_id, entonces debe ser el mismo al que corresponde el viaje dado. +// - Para especificar todos los viajes por una ruta dada, solo se debe +// establecer el route_id. Ten en cuenta que si el trip_id no se conoce, +// entonces los identificadores de secuencia de parada en TripUpdate no son +// suficientes y los stop_ids también se deben proporcionar. Además, se deben +// proporcionar las horas absolutas de llegada/salida. +message TripDescriptor { + // El trip_id del feed GTFS al cual hace referencia este selector. + // Para viajes sin frecuencia expandida, este campo es suficiente para + // identificar de forma unívoca al viaje. Para viajes con frecuencia + // expandida, start_time y start_date también podrían ser necesarios. + optional string trip_id = 1; + + // El route_id de GTFS al cual hace referencia este selector. + optional string route_id = 5; + + // La hora de inicio programada de esta instancia de viaje. + // Este campo debe proporcionarse solo si el viaje es de frecuencia expandida + // en el feed GTFS. El valor debe corresponder precisamente a la start_time + // especificada para la ruta del feed GTFS más algún múltiplo de headway_secs. + // El formato del campo es el mismo que el de GTFS/frequencies.txt/start_time, + // p. ej., 11:15:35 o 25:15:35. + optional string start_time = 2; + + // La fecha de inicio programada de esta instancia de viaje. + // Se debe proporcionar para desambiguar los viajes que están tan retrasados + // que pueden colisionar con un viaje programado para el día siguiente. Por + // ejemplo, para un tren que sale a las 8:00 y a las 20:00 todos los días, y + // que tiene una demora de 12 horas, habrá dos viajes diferentes a la misma + // hora. + // Este campo se puede proporcionar pero no es obligatorio para los programas + // en los cuales tales colisiones son imposibles: por ejemplo, un servicio que + // funciona según una programación por hora donde un vehículo que tiene una + // demora de una hora ya deja de considerarse relacionado con el programa. + // En formato AAAAMMDD. + optional string start_date = 3; + + // La relación entre este viaje y el programa estático. Si un viaje se realiza + // de acuerdo con un programa temporal, no se refleja en GTFS, entonces + // no debe marcarse como SCHEDULED, sino como ADDED. + enum ScheduleRelationship { + // Viaje que se está ejecutando de acuerdo con su programa de GTFS,o que es + // lo suficientemente parecido al viaje programado como para asociarse a él. + SCHEDULED = 0; + + // Un viaje adicional que se ha agregado a un programa en ejecución, por + // ejemplo, para reemplazar un vehículo averiado o para responder a una + // carga repentina de un pasajero. + ADDED = 1; + + // Un viaje que se está ejecutando sin ningún programa asociado, por + // ejemplo, cuando no existe ningún programa. + UNSCHEDULED = 2; + + // Un viaje que existió en el programa, pero se eliminó. + CANCELED = 3; + } + optional ScheduleRelationship schedule_relationship = 4; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; +} + +// Información de identificación para el vehículo que realiza el viaje. +message VehicleDescriptor { + // Identificación interna del sistema para el vehículo. Debe ser única para el + // vehículo y se puede usar para realizar un seguimiento del vehículo a medida + // que avanza en el sistema. + optional string id = 1; + + // Etiqueta visible para el usuario, es decir, algo que se debe mostrar al + // pasajero para ayudarlo a identificar el vehículo correcto. + optional string label = 2; + + // La patente del vehículo. + optional string license_plate = 3; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; +} + +// Un selector para una entidad en un feed GTFS. +message EntitySelector { + // Los valores de los campos deben corresponder a los campos apropiados en el + // feed GTFS. + // Se debe brindar, al menos, un especificador. Si se proporcionan varios, + // entonces el que coincide debe aplicarse a todos los especificadores dados. + optional string agency_id = 1; + optional string route_id = 2; + // corresponde a route_type en GTFS. + optional int32 route_type = 3; + optional TripDescriptor trip = 4; + optional string stop_id = 5; + + // El espacio de nombres de extensiones permite a los programadores externos + // extender la especificación de GTFS en tiempo real para agregar y evaluar + // nuevas funciones y modificaciones a la especificación. + extensions 1000 to 1999; +} + +// Un mensaje internacionalizado que contiene versiones por idioma de un +// fragmento de texto o una URL. +// Se seleccionará una de las cadenas de un mensaje. La resolución se realiza de +// la siguiente manera: +// 1. Si el idioma de la interfaz de usuario coincide con el código de idioma de +// una traducción, se elige la primera traducción coincidente. +// 2. Si un idioma de interfaz de usuario predeterminado (p. ej., inglés) +// coincide con el código de idioma de una traducción, se elige la primera +// traducción coincidente. +// 3. Si alguna traducción tiene un código de idioma no especificado, se elige +// esa traducción. +message TranslatedString { + message Translation { + // Una cadena UTF-8 que contiene el mensaje. + required string text = 1; + // Código de idioma BCP-47. Se puede omitir si el idioma es desconocido o si + // no se realiza ningún i18n para el feed. Como máximo, se permite que + // una traducción tenga una etiqueta de idioma no especificado. + optional string language = 2; + } + // Se debe proporcionar al menos una traducción. + repeated Translation translation = 1; +} diff --git a/transit/gtfs-realtime/spec/es/reference.md b/transit/gtfs-realtime/spec/es/reference.md new file mode 100644 index 000000000..0b8c2e70a --- /dev/null +++ b/transit/gtfs-realtime/spec/es/reference.md @@ -0,0 +1,361 @@ +Un feed GTFS en tiempo real permite que las empresas de transporte público brinden a los consumidores información en tiempo real acerca de las interrupciones de sus servicios (estaciones cerradas, líneas que no funcionan, demoras importantes, etc.), la ubicación de sus vehículos y tiempos de llegada esperados. + +Las especificaciones de la versión 1.0 del feed se abordan y documentan en este sitio. + +### Definiciones de términos + +* **obligatorio**: uno +* **repetido**: cero o más +* **mensaje**: tipo complejo +* **enum.**: lista de valores fijos + +## Índice de elementos + +* [FeedMessage](#FeedMessage) + * [FeedHeader](#FeedHeader) + * [Incrementality](#Incrementality) + * [FeedEntity](#FeedEntity) + * [TripUpdate](#TripUpdate) + * [TripDescriptor](#TripDescriptor) + * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) + * [VehicleDescriptor](#VehicleDescriptor) + * [StopTimeUpdate](#StopTimeUpdate) + * [StopTimeEvent](#StopTimeEvent) + * [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) + * [VehiclePosition](#VehiclePosition) + * [TripDescriptor](#TripDescriptor) + * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) + * [Position](#Position) + * [Alert](#Alert) + * [TimeRange](#TimeRange) + * [EntitySelector](#EntitySelector) + * [TripDescriptor](#TripDescriptor) + * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) + * [Cause](#Cause) + * [Effect](#Effect) + * [TranslatedString](#TranslatedString) + * [Translation](#Translation) + +# Elementos + +## _mensaje_ FeedMessage + +El contenido de un mensaje de feed. Cada mensaje en el flujo de datos se obtiene como una respuesta a una solicitud HTTP GET adecuada. Un feed en tiempo real siempre se define en relación con un feed GTFS existente. Todos los ID de entidades se resuelven en relación con el feed GTFS. + +Un feed depende de algunas configuraciones externas: + +* El feed GTFS correspondiente. +* La aplicación del feed (actualizaciones, posiciones o alertas). Un feed debe contener únicamente elementos de las aplicaciones correspondientes; todas las otras entidades se ignorarán. +* Frecuencia de sondeo, controlada por min_update_delay, max_update_delay. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **header** | [FeedHeader](#FeedHeader) | obligatorio | Metadatos sobre este feed y mensaje del feed | +| **entity** | [FeedEntity](#FeedEntity) | repetido | Contenido del feed | + +## _mensaje_ FeedHeader + +Metadatos sobre un feed, incluido en los mensajes del feed + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Especificación de la versión del feed. La versión actual es 1.0. | +| **incrementality** | [Incrementality](#Incrementality) | opcional | +| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Esta marca de tiempo identifica el momento en que se ha creado el contenido de este feed (en la hora del servidor). En la hora de POSIX (es decir, cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Para evitar el desvío de tiempos entre los sistemas que producen y que consumen información en tiempo real, se recomienda derivar la marca de tiempo desde un servidor de tiempo. Es absolutamente aceptable usar servidores de estrato 3 o, incluso, inferiores, porque las diferencias de tiempo de hasta un par de segundos son tolerables. | + +## _enum._ Incrementality + +Determina si la búsqueda actual es incremental. + +* **FULL_DATASET**: la actualización de este feed sobrescribirá toda la información en tiempo real anterior para el feed. Por lo tanto, se espera que esta actualización proporcione un resumen completo de toda la información en tiempo real conocida. +* **DIFFERENTIAL**: en este momento, este modo **no está admitido** y su comportamiento **no se especifica** para los feeds que usan este modo. Existen debates sobre la [lista de correo](http://groups.google.com/group/gtfs-realtime) de GTFS en tiempo real, relacionados con la especificación completa del comportamiento del modo DIFFERENTIAL, y la documentación se actualizará cuando esos debates finalicen. + +### Valores + +| _**Valor**_ | +|-------------| +| **FULL_DATASET** | +| **DIFFERENTIAL** | + +## _mensaje_ FeedEntity + +La definición (o actualización) de una entidad en el feed de transporte público. Si la entidad no se elimina, uno de los campos "trip_update", "vehicle" y "alert" debe completarse. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Identificador único del feed para esta entidad. Los identificadores se usan solamente para proporcionar soporte de incrementalidad. Las entidades reales a las que hace referencia el feed deben especificarse mediante selectores explícitos (ver EntitySelector más adelante para obtener más información). | +| **is_deleted** | [bool](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Establece si esta entidad debe eliminarse. Es relevante solo para las búsquedas incrementales. | +| **trip_update** | [TripUpdate](#TripUpdate) | opcional | Datos sobre las demoras de salida en tiempo real de un viaje. | +| **vehicle** | [VehiclePosition](#VehiclePosition) | opcional | Datos sobre la posición en tiempo real de un vehículo. | +| **alert** | [Alert](#Alert) | opcional | Datos sobre las alertas en tiempo real. | + +## _mensaje_ TripUpdate + +Actualización en tiempo real del progreso de un vehículo en un viaje. También consulta el debate general del [tipo de feed de actualizaciones del viaje](./trip-updates). + +Según el valor de ScheduleRelationship, TripUpdate puede especificar lo siguiente: + +* Un viaje que avanza según la programación. +* Un viaje que avanza por una ruta, pero que no tiene una programación fija. +* Un viaje que se ha agregado o se ha quitado en relación con una programación. + +Las actualizaciones pueden ser para eventos de llegada/salida futuros y previstos, o para eventos pasados que ya ocurrieron. En la mayoría de los casos, la información sobre los eventos pasados es un valor medido, por lo tanto, se recomienda que su valor de incertidumbre sea 0\. Aunque puede haber algunos casos en que esto no sea así, por lo que se admiten valores de incertidumbre distintos de 0 para los eventos pasados. Si el valor de incertidumbre de una actualización no es 0, entonces la actualización es una predicción aproximada para un viaje que no se ha completado o la medición no es precisa o la actualización fue una predicción para el pasado que no se ha verificado después de que ocurrió el evento. + +Ten en cuenta que la actualización puede describir un viaje que ya se ha completado. En este caso, es suficiente con proporcionar una actualización para la última parada del viaje. Si el tiempo de llegada para la última parada es en el pasado, el cliente concluirá que todo el viaje es pasado (es posible, aunque inconsecuente, proporcionar también actualizaciones para las paradas anteriores). Esta opción es más relevante para un viaje que se ha completado antes de lo que establecía la programación, pero que según esta, el viaje todavía se está realizando en este momento. Quitar las actualizaciones de este viaje podría hacer que el cliente considere que el viaje todavía se está realizando. Ten en cuenta que el proveedor del feed tiene permitido, aunque no está obligado, a purgar las actualizaciones pasadas (en este caso esto sería útil). + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **trip** | [TripDescriptor](#TripDescriptor) | obligatorio | El viaje al cual se aplica este mensaje. Puede haber una entidad de TripUpdate, como máximo, para cada instancia de viaje real. Si no hay ninguna, entonces no habrá información de predicciones disponible. *No* significa que el viaje se está realizando de acuerdo con la programación. | +| **vehicle** | [VehicleDescriptor](#VehicleDescriptor) | opcional | Información adicional sobre el vehículo con el cual se está realizando este viaje. | +| **stop_time_update** | [StopTimeUpdate](#StopTimeUpdate) | repetido | Las actualizaciones de StopTimes para el viaje (futuras, como las predicciones, y, en algunos casos, pasadas, es decir, aquellas que ya ocurrieron). Las actualizaciones deben ordenarse por secuencia de parada y deben aplicarse a todas las siguientes paradas del viaje hasta la próxima especificada. | +| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Momento en el que se midió el progreso en tiempo real del vehículo. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). | + +## _mensaje_ StopTimeEvent + +Información de horarios para un único evento previsto (sea la llegada o la salida). Los horarios consisten en la información sobre demoras o tiempos estimados y la incertidumbre. + +* La demora (delay) debe usarse cuando la predicción se realiza con relación a una programación existente en GTFS. +* El tiempo (time) debe darse aunque no haya una programación prevista. Si se especifican tanto el tiempo como la demora, el tiempo será prioritario (aunque, por lo general, el tiempo, si se otorga para un viaje programado, debe ser igual al tiempo programado en GTFS + la demora). + +La incertidumbre se aplica de la misma forma tanto al tiempo como a la demora. La incertidumbre especifica el error esperado en una demora real (pero ten en cuenta, que todavía no definimos su significado estadístico preciso). Es posible que la incertidumbre sea 0, por ejemplo, para los trenes que funcionan con un control de horarios por computadora. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La demora (en segundos) puede ser positiva (significa que el vehículo está retrasado) o negativa (significa que el vehículo está adelantado). Una demora de 0 significa que el vehículo está yendo a tiempo. | +| **time** | [int64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Evento como tiempo absoluto. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). | +| **uncertainty** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Si se omite la incertidumbre, se interpreta como desconocida. Para especificar una predicción completamente certera, establece la incertidumbre en 0. | + +## _mensaje_ StopTimeUpdate + +La actualización en tiempo real para los eventos de llegada o de salida para una determinada parada de un viaje. Consulta el debate general de las actualizaciones de tiempos de parada en la documentación de [TripDescriptor](#TripDescriptor) y [del tipo de feed de actualizaciones de viaje](./trip-updates). + +Las actualizaciones se pueden proporcionar tanto para eventos pasados como futuros. El productor tiene permitido, aunque no está obligado, a desestimar los eventos pasados. + La actualización está vinculada a una parada específica sea a través de stop_sequence o de stop_id, de manera que uno de estos campos debe definirse, necesariamente. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Debe ser la misma que la de stop_times.txt en el feed GTFS correspondiente. | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. | +| **arrival** | [StopTimeEvent](#StopTimeEvent) | opcional | +| **departure** | [StopTimeEvent](#StopTimeEvent) | opcional | +| **schedule_relationship** | [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) | opcional | La relación predeterminada es SCHEDULED. | + +## _enum._ ScheduleRelationship + +La relación entre este StopTime y la programación estática + +### Valores + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **SCHEDULED** | El vehículo está avanzando según su programación estática de paradas, aunque no necesariamente de acuerdo con los tiempos de la programación. Este es el comportamiento **predeterminado**. Al menos debe proporcionarse uno de los valores de llegada y de salida. Si la programación para esta parada contiene los tiempos de llegada y de salida, entonces también debe contener estos dos valores la actualización. Una actualización son solo una salida, digamos, cuando la programación tiene ambos datos, indica que el viaje se termina antes en esta parada. | +| **SKIPPED** | La parada se omite, es decir, el vehículo no se detendrá en esta parada. Los valores de llegada y salida son opcionales. | +| **NO_DATA** | No se proporcionan datos para esta parada. Esto indica que no hay información en tiempo real disponible. Cuando se establece NO_DATA, esto se propaga en las siguientes paradas, de manera que esta es la forma recomendada de especificar desde qué parada no tienes información en tiempo real. Cuando se establece NO_DATA, no se deben proporcionar los datos de llegada ni de salida. | + +## _mensaje_ VehiclePosition + +Información de posicionamiento en tiempo real para un vehículo dado + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **trip** | [TripDescriptor](#TripDescriptor) | opcional | El viaje que está haciendo este vehículo. Puede estar vacío o parcialmente vacío si el vehículo no puede identificarse con una instancia de viaje dada. | +| **vehicle** | [VehicleDescriptor](#VehicleDescriptor) | opcional | Información adicional sobre el vehículo que está realizando el viaje. Cada entrada debe tener un ID de vehículo **único**. | +| **position** | [Position](#Position) | opcional | Posición actual de este vehículo. | +| **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El índice de la secuencia de parada de la parada actual. El significado de current_stop_sequence (es decir, la parada a la que hace referencia) está determinado por current_status. Si falta el valor en current_status, se asume IN_TRANSIT_TO. | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Identifica la parada actual. El valor debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. | +| **current_status** | [VehicleStopStatus](#VehicleStopStatus) | opcional | El estado exacto del vehículo con respecto a la parada actual. Se ignora si falta el valor en current_stop_sequence. | +| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Momento en el cual se midió la posición del vehículo. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). | +| **congestion_level** | [CongestionLevel](#CongestionLevel) | opcional | + +## _enum._ VehicleStopStatus + +### Valores + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **INCOMING_AT** | El vehículo está a punto de llegar a la parada (en la visualización de la parada, el símbolo del vehículo, por lo general, parpadea). | +| **STOPPED_AT** | El vehículo está detenido en la parada. | +| **IN_TRANSIT_TO** | El vehículo ha salido de la parada anterior y está en tránsito. | + +## _enum._ CongestionLevel + +El nivel de congestión que está afectando al vehículo. + +### Valores + +| _**Valor**_ | +|-------------| +| **UNKNOWN_CONGESTION_LEVEL** | +| **RUNNING_SMOOTHLY** | +| **STOP_AND_GO** | +| **CONGESTION** | +| **SEVERE_CONGESTION** | + +## _mensaje_ Alert + +Una alerta que indica que existe algún tipo de incidente en la red de transporte público. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **active_period** | [TimeRange](#TimeRange) | repetido | Tiempo durante el cual debe mostrarse la alerta al usuario. Si falta, la alerta se mostrará durante todo el tiempo que aparezca en el feed. Si se otorgan varios intervalos, la alerta se mostrará durante todos ellos. | +| **informed_entity** | [EntitySelector](#EntitySelector) | repetido | Entidades a cuyos usuarios debemos notificar esta alerta. | +| **cause** | [Cause](#Cause) | opcional | +| **effect** | [Effect](#Effect) | opcional | +| **url** | [TranslatedString](#TranslatedString) | opcional | La URL que proporciona información adicional sobre la alerta. | +| **header_text** | [TranslatedString](#TranslatedString) | opcional | Encabezado de la alerta. Esta cadena de texto sin formato se resaltará, por ejemplo, en negrita. | +| **description_text** | [TranslatedString](#TranslatedString) | opcional | Descripción de la alerta. A esta cadena de texto sin formato se le aplicará el formato del cuerpo de la alerta (o se mostrará en una solicitud explícita de "expansión" realizada por el usuario
). La información de la descripción debe completar la información del encabezado. | + +## _enum._ Cause + +Causa de la alerta + +### Valores + +| _**Valor**_ | +|-------------| +| **UNKNOWN_CAUSE** | +| **OTHER_CAUSE** | +| **TECHNICAL_PROBLEM** | +| **STRIKE** | +| **DEMONSTRATION** | +| **ACCIDENT** | +| **HOLIDAY** | +| **WEATHER** | +| **MAINTENANCE** | +| **CONSTRUCTION** | +| **POLICE_ACTIVITY** | +| **MEDICAL_EMERGENCY** | + +## _enum._ Effect + +El efecto de este problema en la entidad afectada. + +### Valores + +| _**Valor**_ | +|-------------| +| **NO_SERVICE** | +| **REDUCED_SERVICE** | +| **SIGNIFICANT_DELAYS** | +| **DETOUR** | +| **ADDITIONAL_SERVICE** | +| **MODIFIED_SERVICE** | +| **OTHER_EFFECT** | +| **UNKNOWN_EFFECT** | +| **STOP_MOVED** | + +## _mensaje_ TimeRange + +Un intervalo de tiempo. El intervalo se considera activo `t` si `t` es mayor o igual que la hora de inicio y mejor que la hora de finalización. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **start** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Hora de inicio, en tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Si falta esta información, el intervalo comienza con el valor infinito negativo. | +| **end** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Hora de finalización, en tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Si falta esta información, el intervalo finaliza con el valor infinito positivo. | + +## _mensaje_ Position + +La posición geográfica de un vehículo + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **latitude** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Grados norte, en el sistema de coordenadas WGS-84 | +| **longitude** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Grados este, en el sistema de coordenadas WGS-84 | +| **bearing** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Orientación, en grados, en el sentido de las agujas del reloj desde el norte verdadero, es decir, 0 es el norte y 90 es el este. Esta puede ser la orientación de la brújula, o la dirección hacia la próxima parada o la ubicación intermedia. Esto no debe deducirse a partir de la secuencia de posiciones anteriores, que los clientes pueden calcular a partir de los datos anteriores. | +| **odometer** | [double](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El valor del odómetro en metros. | +| **speed** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Velocidad momentánea medida por el vehículo, en metros por segundo. | + +## _mensaje_ TripDescriptor + +Un descriptor que identifica una instancia de un viaje de GTFS o todas las instancias de un viaje por una ruta. Para especificar una sola instancia de viaje, se define trip_id (y si fuera necesario, start_time). Si también se define route_id, debe ser el mismo que uno a los cuales corresponda el viaje dado. Para especificar todos los viajes de una determinada ruta, solo se debe definir route_id. Ten en cuenta que si no se conoce el trip_id, entonces los identificadores de la secuencia de la estación en TripUpdate no son suficientes y, también, se deberán proporcionar los identificadores de parada. Además, se deben proporcionar las horas absolutas de llegada/salida. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El identificador de viaje del feed GTFS al cual hace referencia este selector. Para los viajes sin frecuencia extendida, este campo es suficiente para identificar de forma unívoca al viaje. Para los viajes con frecuencia extendida, también podrían necesitarse start_time y start_date. | +| **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El identificador de la ruta de GTFS al que hace referencia este selector. | +| **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La hora de inicio programada de esta instancia de viaje. Este campo debe proporcionarse solo si el viaje tiene frecuencia extendida en el feed GTFS. El valor debe corresponder precisamente a la hora de inicio especificada para la ruta del feed GTFS más algunos múltiplos de headway_secs. El formato del campo es el mismo que el de GTFS/frequencies.txt/start_time, es decir, 11:15:35 o 25:15:35. | +| **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La fecha de inicio programada de esta instancia de viaje. Este campo debe proporcionarse para desambiguar los viajes que están tan retrasados que pueden superponerse con un viaje programado para el día siguiente. Por ejemplo, para un tren que sale a las 8:00 y a las 20:00 todos los días, y está 12 horas retrasado, habrá dos viajes distintos a la misma hora. Este campo puede proporcionarse, pero no es obligatorio para las programaciones en las cuales las superposiciones son imposibles, por ejemplo, un servicio que funciona según una programación horaria donde un vehículo que está una hora retrasado deja de considerarse relacionado a la programación. En formato AAAAMMDD. | +| **schedule_relationship** | [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) | opcional | + +## _enum._ ScheduleRelationship + +La relación entre este viaje y la programación estática. Si un viaje se realiza de acuerdo con la programación temporal, no se refleja en GTFS, y por lo tanto, no debe marcarse como SCHEDULED, sino como ADDED. + +### Valores + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **SCHEDULED** | Viaje que se está realizando de acuerdo con su programación de GTFS, o que está realizándose tan parecido al viaje programado que se puede asociar con él. | +| **ADDED** | Un viaje adicional que se agregó además de una programación existente, por ejemplo, para reemplazar un vehículo averiado o para responder a una carga repentina de pasajeros. | +| **UNSCHEDULED** | Un viaje que se está realizando sin ninguna programación asociada, por ejemplo, cuando no existe ninguna programación. | +| **CANCELED** | Un viaje que existió en la programación, pero que luego se eliminó. | +| **REPLACEMENT** | Un viaje que reemplaza una parte de la programación estática. Si el selector de viaje identifica determinada instancia de viaje, entonces solamente esa instancia se reemplaza. Si el selector identifica una ruta, entonces todos los viajes de la ruta se reemplazan.
El reemplazo se aplica solamente a la parte del viaje que se suministra. Por ejemplo, consideremos una ruta que pasa por las paradas A,B,C,D,E,F y un viaje REPLACEMENT proporciona datos para las paradas A,B,C. Entonces, los horarios para las paradas D,E,F todavía se toman de la programación estática.
Un feed debe suministrar varios viajes REPLACEMENT. En este caso, la parte de la programación estática que se reemplaza es la suma de las definiciones de todos los feeds. Por lo general, todos los viajes REPLACEMENT deben corresponder a la misma ruta o a instancias de viaje individuales. | + +## _mensaje_ VehicleDescriptor + +Información de identificación para el vehículo que realiza el viaje. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Identificación interna del sistema para el vehículo. Debe ser **única** para cada vehículo y se usa para hacer un seguimiento del vehículo en la medida en que avanza en el sistema. Este identificador debe ser visible para el usuario final; para ello debes usar el campo **label** | +| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Etiqueta visible para el usuario, es decir, que se debe mostrar al pasajero para ayudarlo a identificar el vehículo correcto. | +| **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La patente del vehículo. | + +## _mensaje_ EntitySelector + +Un selector para una entidad en un feed GTFS. Los valores de los campos deben coincidir con los campos correspondientes del feed GTFS. Debe otorgarse al menos un especificador. Si se otorgan muchos, entonces la coincidencia debe hacerse con todos los especificadores dados. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **agency_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | +| **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | +| **route_type** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | +| **trip** | [TripDescriptor](#TripDescriptor) | opcional | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | + +## _mensaje_ TranslatedString + +Un mensaje internacionalizado que contiene versiones por idioma de un fragmento de texto o una URL. Se seleccionará una de las cadenas de un mensaje. La resolución se realiza de la siguiente manera: si el idioma de la IU coincide con el código de idioma de una traducción, se elije la primera traducción coincidente. Si un idioma de IU predetermiando (por ejemplo, inglés) coincide con el código de idioma de una traducción, se elije la primera traducción coincidente. Si alguna traducción tiene un código de idioma no especificado, se elija esa traducción. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **translation** | [Translation](#Translation) | repetido | Se debe proporcionar al menos una traducción. | + +## _mensaje_ Translation + +Una cadena localizada asignada a un idioma. + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **text** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Una cadena UTF-8 que contiene el mensaje. | +| **language** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Código de idioma BCP-47\. Se puede omitir si el idioma es desconocido o si no se realiza ninguna internacionalización para el feed. Al menos una traducción puede tener una etiqueta de idioma no especificado. | diff --git a/transit/gtfs-realtime/spec/es/service-alerts.md b/transit/gtfs-realtime/spec/es/service-alerts.md new file mode 100644 index 000000000..aa9903b26 --- /dev/null +++ b/transit/gtfs-realtime/spec/es/service-alerts.md @@ -0,0 +1,56 @@ +Las alertas de servicio te permiten proporcionar actualizaciones cada vez que se produce una interrupción en la red. Las demoras y cancelaciones de viajes individuales a menudo se deben comunicar a través de las [Actualizaciones de viaje](trip-updates.md). + +Puedes proporcionar la siguiente información: + +* la URL del sitio en el que se ofrecen más detalles acerca de la alerta, +* el texto del encabezado a modo de resumen de la alerta, +* la descripción completa de la alerta que se mostrará junto al encabezado (la información no debe ser la misma en ambas partes). + +### Período + +La alerta aparecerá cuando corresponda en el transcurso del período establecido. Este período debe cubrir en su totalidad el lapso en el que el pasajero necesita la alerta. + +Si no se establece ningún período, mostraremos la alerta el tiempo que esta se encuentre en el feed. Si se establecen varios períodos, mostraremos la alerta durante todos ellos. + +### Selector de entidad + +El selector de entidad te permite especificar exactamente qué partes de la red afecta una alerta, a fin de que le podamos mostrar al usuario solo las alertas más adecuadas. Puedes incluir varios selectores de entidad en el caso de las alertas que afectan muchas entidades. + +Las entidades se seleccionan a través de los identificadores de la especificación GTFS y puedes elegir cualquiera de los siguientes: + +* Empresa: afecta toda la red. +* Ruta: afecta toda la ruta. +* Tipo de ruta: afecta cualquier ruta del tipo seleccionado; p. ej., todos los metros. +* Viaje: afecta un viaje en particular. +* Parada: afecta una parada en particular. + +### Causa + +¿Cuál es la causa de esta alerta? Puedes especificar cualquiera de las siguientes: + +* causa desconocida, +* otra causa (que no se ve representada por ninguna de estas opciones), +* problema técnico, +* huelga, +* manifestación, +* accidente, +* feriado, +* clima, +* tareas de mantenimiento, +* tareas de construcción, +* actividad policial, +* emergencia médica. + +### Efecto + +¿Qué efecto tiene este problema en la entidad seleccionada? Puedes especificar cualquiera de los siguientes: + +* sin servicio, +* servicio reducido, +* demoras importantes (aquellas poco importantes se deben informar a través de las [Actualizaciones de viaje](trip-updates.md)), +* desvío, +* servicio adicional, +* servicio modificado, +* traslado de parada, +* otro efecto (que no se ve representado por ninguna de estas opciones), +* efecto desconocido. diff --git a/transit/gtfs-realtime/spec/es/trip-updates.md b/transit/gtfs-realtime/spec/es/trip-updates.md new file mode 100644 index 000000000..20c2e8433 --- /dev/null +++ b/transit/gtfs-realtime/spec/es/trip-updates.md @@ -0,0 +1,56 @@ +Las actualizaciones de viaje representan fluctuaciones en el horario. Esperamos recibir actualizaciones de viaje para todos los viajes que has programado, que sean aptos para tiempo real. Estas actualizaciones brindarían un horario de llegada o salida previsto para las paradas a lo largo de la ruta. Las actualizaciones de viaje también pueden prever escenarios más complejos en los cuales se cancelen o agreguen viajes al programa, o incluso se redirijan. + +**Recordatorio:** En [GTFS](https://developers.google.com/transit/gtfs/), un viaje es una secuencia de dos o más paradas que tienen lugar a una hora específica. + +Debe haber **como máximo** una actualización de viaje para cada viaje programado. En caso de que no haya ninguna actualización de viaje para un viaje programado, se concluirá que no hay datos en tiempo real disponibles para el viaje. El consumidor de datos **no** debe asumir que el viaje se está realizando a horario. + +## Actualizaciones de horario de paradas + +Una actualización de viaje comprende una o más actualizaciones a los horarios de parada del vehículo, que se conocen como [StopTimeUpdates](reference.md#StopTimeUpdate). Pueden proporcionarse para horarios de paradas pasados y futuros. Tienes permitido brindar horarios de parada pasados, pero no es obligatorio que los brindes. Cuando lo hagas, ten en cuenta que no debes proporcionar una actualización pasada si se refiere a un viaje todavía no programado para haber terminado (es decir, que finalizó antes de lo programado), ya que, de lo contrario, se concluirá que no hay actualización de ese viaje. + +Cada [StopTimeUpdate](reference.md#StopTimeUpdate) está vinculada a una parada. Normalmente, esto se puede hacer usando un GTFS stop_sequence o un GTFS stop_id. Sin embargo, en caso de que estés suministrando una actualización para un viaje sin un trip_id de GTFS, debes especificar el stop_id ya que stop_sequence no tiene valor. El stop_id todavía debe hacer referencia a un stop_id en GTFS. + +La actualización puede proporcionar un horario exacto para la **llegada** o la **salida** en una parada en [StopTimeUpdates](reference.md#StopTimeUpdate) mediante [StopTimeEvent](reference.md#StopTimeUpdate). Esto debe contener un **horario** absoluto o un **retraso** (es decir, una compensación desde el horario programado en segundos). El retraso solo se puede utilizar en caso de que la actualización de viaje se refiera a un viaje de GTFS programado, en contraposición con un viaje basado en la frecuencia. En este caso, el horario debe ser igual al horario programado + el retraso. También debes especificar la **incertidumbre** de la predicción junto con [StopTimeEvent](reference.md#StopTimeUpdate), que se analiza más detalladamente en la sección [Incertidumbre](#Incertidumbre) más abajo en la página. + +Para cada [StopTimeUpdate](reference.md#StopTimeUpdate), la relación de programación predeterminada es **programada**. (Ten en cuenta que es diferente de la relación de programación para el viaje). Puedes cambiarla a **omitida** si la parada no se va a utilizar o a **sin datos** si solo tienes datos en tiempo real para parte del viaje. + +**Las actualizaciones se deben clasificar por stop_sequence** (o stop_id, en el orden en que tienen lugar en el viaje). + +Si faltan una o más paradas a lo largo del viaje, la actualización se propaga a todas las paradas subsiguientes. Esto significa que, en caso de no haber otra información, al actualizar un horario de parada para una cierta parada, se cambiarán todas las paradas subsiguientes. + +**Ejemplo 1** + +Para un viaje con 20 paradas, una [StopTimeUpdate](reference.md#StopTimeUpdate) con retraso de llegada y retraso de salida de 0 ([StopTimeEvents](reference.md#StopTimeEvent)) para la stop_sequence de la parada actual, significa que el viaje está exactamente a horario. + +**Ejemplo 2** + +Para la misma instancia de viaje, se proporcionan tres [StopTimeUpdates](reference.md#StopTimeUpdate): + +* retraso de 300 segundos para la stop_sequence 3 +* retraso de 60 segundos para la stop_sequence 8 +* retraso de duración no especificada para la stop_sequence 10 + +Esto se interpretará como: + +* las stop_sequences 3,4,5,6,7 tienen un retraso de 300 segundos. +* las stop_sequences 8,9 tienen un retraso de 60 segundos. +* las stop_sequences 10,..,20 tienen un retraso desconocido. + +### Descriptor de viajes + +La información suministrada por el descriptor de viajes depende de la relación de programación del viaje que estás actualizando. Hay una cantidad de opciones que puedes configurar: + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **Programado** | Este viaje se está ejecutando de acuerdo con un programa de GTFS o se asemeja lo suficiente como para seguir estando asociado a él. | +| **Agregado** | Este viaje no estaba programado y se ha agregado. Por ejemplo, para hacer frente a la demanda o reemplazar un vehículo averiado. | +| **Sin programar** | Este viaje se está ejecutando y nunca se asocia con un programa. Por ejemplo, si no hay programa y los autobuses operan en un servicio de traslados. | +| **Cancelado** | Este viaje se programó pero ahora se eliminó. | + +En la mayoría de los casos, debes proporcionar el trip_id del viaje programado en GTFS con el que se relaciona esta actualización. En caso de que no puedas vincular esta actualización con un viaje en GTFS, puedes brindar un route_id de GTFS, y una fecha y hora de inicio para el viaje. Generalmente, este es el caso de los viajes agregados, sin programar y de algunos tipos de viajes de reemplazo. + +## Incertidumbre + +La incertidumbre se aplica tanto al horario como al valor de retraso de una [StopTimeUpdate](reference.md#StopTimeUpdate). La incertidumbre especifica, en términos generales, el error esperado en retraso verdadero como un entero en segundos (pero ten en cuenta que, el significado estadístico preciso todavía no está definido). Es posible que la incertidumbre sea 0, por ejemplo, para los trenes conducidos bajo control de horarios por computadora. + +Como ejemplo, un autobús de larga distancia que tiene un retraso estimado de 15 minutos y llega a su siguiente parada con una ventana de error de 4 minutos (es decir, +2/-2 minutos) tendrá un valor de Incertidumbre de 240. diff --git a/transit/gtfs-realtime/spec/es/vehicle-positions.md b/transit/gtfs-realtime/spec/es/vehicle-positions.md new file mode 100644 index 000000000..a6fafad97 --- /dev/null +++ b/transit/gtfs-realtime/spec/es/vehicle-positions.md @@ -0,0 +1,45 @@ +La posición del vehículo se utiliza para proporcionar información generada automáticamente sobre la ubicación de un vehículo, como de un dispositivo GPS a bordo. Se debe proporcionar una sola posición del vehículo para cada vehículo que puede proporcionarla. + +El viaje que el vehículo está realizando actualmente se debe proporcionar a través de un [descriptor de viaje](reference.md#VehicleDescriptor). También puedes proporcionar un [descriptor de vehículo](reference.md#VehicleDescriptor) que especifique un vehículo físico preciso sobre el cual estás proporcionando actualizaciones. La documentación se proporciona a continuación. + +Se puede proporcionar una **marca de tiempo** que indique el momento en el que se tomó la lectura de la posición. Ten en cuenta que esto es diferente de la marca de tiempo en el encabezado del feed, que es el tiempo en el que el servidor generó este mensaje. + +También se puede proporcionar un **paso actual** (ya sea como stop_sequence o stop_id). Esto es una referencia a la parada a la que el vehículo se está dirigiendo o en la que ya se detuvo. + +## Posición + +La posición contiene los datos de ubicación dentro de Posición del vehículo. Los campos de latitud y longitud son obligatorios; los demás campos son opcionales. Estos tipos de datos son: + +* **Latitud**: grados Norte, en el sistema de coordenadas WGS-84. +* **Longitud**: grados Este, en el sistema de coordenadas WGS-84. +* **Rumbo**: la dirección en la que el vehículo se orienta. +* **Odómetro**: la distancia que el vehículo ha recorrido. +* **Velocidad**: velocidad instantánea medida por el vehículo, en metros por segundo. + +## Nivel de congestión + +La posición del vehículo también permite que la empresa especifique el nivel de congestión que el vehículo está experimentando en el momento. La congestión se puede clasificar en las siguientes categorías: + +* Nivel de congestión desconocido +* Tráfico fluido +* Tráfico intermitente +* Congestión +* Congestión grave + +A la empresa le corresponde clasificar lo que clasificas como cada tipo de congestión. Nuestra orientación es que la congestión grave solo se utiliza en situaciones en las que el tráfico está tan congestionado que las personas están abandonando sus vehículos. + +## VehicleStopStatus + +El estado de parada del vehículo le da más significado al estado de un vehículo en relación con una parada a la que se está aproximando o en la que ya está. Se puede ajustar a cualquiera de estos valores. + +* **Llegando a**: el vehículo está a punto de llegar a la parada indicada. +* **Detenido en**: el vehículo está detenido en la parada indicada. +* **En camino a**: la parada indicada es la siguiente parada para el vehículo: **predeterminado**. + +## Descriptor de vehículo + +El descriptor de vehículo describe un vehículo físico preciso y puede contener cualquiera de los siguientes atributos: + +* **ID**: sistema interno de identificación del vehículo. Debe ser único para el vehículo. +* **Etiqueta**: una etiqueta visible para el usuario, por ejemplo el nombre de un tren. +* **Placa**: la placa real del vehículo. diff --git a/transit/gtfs/CHANGES.md b/transit/gtfs/CHANGES.md new file mode 100644 index 000000000..83379ba3a --- /dev/null +++ b/transit/gtfs/CHANGES.md @@ -0,0 +1,199 @@ +The GTFS Specification is not set in stone. Instead, it is an open specification developed and maintained by the community of transit agencies, developers, and other stakeholders who use GTFS. It is expected that this community of producers and consumers of GTFS data will have proposals for extending the spec to enable new capabilities. To help manage that process, the following procedures and guidelines have been established. + +### Specification amendment process +The official specification, reference and documentation are written in English. If a translation to a different language differs from the English original, the latter takes precedence. All communication is performed 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. +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. +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). +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. + 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. +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. + 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. +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 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. + +### Guiding Principles +In order to preserve the original vision of GTFS, a number of guiding principles have been established to take into consideration when extending the spec: + +#### Feeds should be easy to create and edit +We chose CSV as the basis for the specification because it's easy to view and edit using spreadsheet programs and text editors, which is helpful for smaller agencies. It's also straightforward to generate from most programming languages and databases, which is good for publishers of larger feeds. + +#### Feeds should be easy to parse +Feed readers should be able to extract the information they're looking for with as little work as possible. Changes and additions to the feed should be as broadly useful as possible, to minimize the number of code paths that readers of the feed need to implement. (However, making creation easier should be given precedence, since there will ultimately be more feed publishers than feed readers.) + +#### Changes to the spec should be backwards-compatible +When adding features to the specification, we want to avoid making changes that will make existing feeds invalid. We don't want to create more work for existing feed publishers until they want to add capabilities to their feeds. Also, whenever possible, we want existing parsers to be able to continue to read the older parts of newer feeds. + +#### Speculative features are discouraged +Every new feature adds complexity to the creation and reading of feeds. Therefore, we want to take care to only add features that we know to be useful. Ideally, any proposal will have been tested by generating data for a real transit system that uses the new feature and writing software to read and display it. Note that the GTFS readily allows for extensions to the format through the addition of extra columns and files that are ignored by the official parsers & validators, so proposals can be easily prototyped and tested on existing feeds. + +### Revision History + +#### March 16, 2016 + +* Transition of GTFS documentation to Github at https://github.com/google/transit + +#### February 2, 2015 + +* Added stop_times.txt 'timepoint' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/Ah-J9JP2rJY) + +#### February 17, 2014 + +* Added trips.txt 'bikes_allowed' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/rEiSeKNc4cs) + +#### October 15, 2012 + +Added trips.txt 'wheelchair_accessible' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/ASxItgsQlh4) + +#### June 20, 2012 + +* Added 'wheelchair_boarding' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/ASxItgsQlh4) + +#### February 2, 2012 + +* Added 'stop_timezone' proposal to spec: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/2Il0Q9OXqu4) + +#### January 18, 2012 + +* Migrated documentation from old code.google.com to their new location at developers.google.com. + +#### September 26, 2011 + +* Added 'feed_info' proposal to spec: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/Sh0e4o9o2Gw) + +#### September 6, 2011 + +* Added 'agency_fare_url' proposal to spec: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/Zp9rPG07CgE) +* Added 'exact_times' proposal to spec: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/nZF9lbQ7TQs) + +#### March 30, 2009 + +* A new section on making a transit feed publicly available. This wasn't previously discussed on the group, because it wasn't strictly a change to how the data is interpreted or written. However, some of the folks at Google thought that it would be informative to include discussion of non-Google uses of GTFS, since there are an increasing number of applications that can make use of GTFS-formatted data. +* CSV format clarifications: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/03qz5aTA2mk). +* Additional guidance on how to pick contrasting colors in the descriptions of the route_color and route_text_color fields. +* trip_short_name, as proposed and tested in these threads: a and b. +* A fix for a minor error in the sample data included at the end of the document (giving stop S7 the parent_station S8). +* Added "agency_lang" information to the sample data at the end of the document, as suggested by Marcy during the comment period: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/5qP1kDUFqx0). +* Updated the link to OCTA's GTFS feed in the sidebar +* See [original summary](https://groups.google.com/forum/#!topic/gtfs-changes/cL1E4oKKpKw). + +#### February 26, 2009 + +* Removed most of the Google-specific feed submission instructions, since there are many other applications that consume GTFS data at this point. +* Fixed a broken link in the sidebar to Orange County OCTA's public feed. + +#### August 7, 2008 + +* Restored the stop_url field, which was accidentally omitted in the August 6 version +* Added agency_phone to sample data +* Added a mention of the data use agreement when submitting a feed to Google + +#### August 6, 2008 + +* Added transfers.txt file, allowing the feed publishers to provide hints on preferred transfer behavior ([original proposal](https://groups.google.com/forum/#!topic/gtfs-changes/cL1E4oKKpKw)) +* Added location_type and parent_station fields to stops.txt, allowing stop points to be grouped into stations ([original proposal](https://groups.google.com/forum/#!topic/gtfs-changes/ScGAyZ9a_yw)) +* Added agency_phone field for providing voice telephone number for an agency ([original proposal](https://groups.google.com/forum/#!topic/gtfs-changes/8Itt58ueyqA)) +* Added "Testing Your Feeds" section mentioning open-source testing tools +* Added clarifications about CSV format, agency_timezone, agency_lang, route_color, route_text_color, arrival_time, departure_time, calendar.txt vs. calendar_dates.txt, fare tables, and frequencies.txt +* Added link to feed history document, and corrected some public feed links +* Updated example images to depict the current Google Maps UI +* Updated/fixed sample data in document + +#### February 29, 2008 + +* Added the stop_code field in stops.txt to allow for the specification of rider-facing stop codes ([original proposal](https://groups.google.com/forum/#!topic/gtfs-changes/k9A95fYZexc)) +* Clarified the descriptions of route_short_name and route_long_name in routes.txt +* Clarified the descriptions of arrival_time and departure_time in stop_times.txt +* Fixed typos in the Sample Data section + +#### November 20, 2007 + +* Clarified block_id description +* Changed language to de-emphasize Google Transit (since non-Google applications are using GTFS, and transit routing is now an integrated feature of Google Maps), and to fix assorted typos +* Updated example screenshots to reflect the presentation of GTFS fields in the current Google Maps UI +* Updated the Google contact email address for transit data providers +* Updated formatting + +#### October 5, 2007 + +* Changed stop_sequence and shape_pt_sequence to allow for any increasing non-negative integers +* Clarified descriptions and fixed typos + +#### May 31, 2007 + +* Updated page style, made HTML cleaner and more accessible +* Added links to public feed examples and other useful sites +* Removed examples from individual field descriptions + +#### April 9, 2007 + +* Added section on [submitting a feed](https://developers.google.com/transit/google-transit#SubmitFeedToGoogle). +* Added the [Example Demo Transit Agency feed](https://developers.google.com/transit/gtfs/examples/gtfs-feed). +* Added note that calendar.txt can be omitted if all the service dates are defined in calendar_dates.txt. +* Made the agency_id field optional in feeds containing only one agency. This allows existing feeds without agency_id to remain valid. +* Added fuller specification of agency_url, stop_url, and route_url, and additional example values for those fields. +* Added 6 (Gondola) and 7 (Funicular) as valid route_type values. + +#### March 8, 2007 + +* Minor edit to move the stop_url field from stop_times.txt, where it was incorrectly specified in the Feb. 28 update, to stops.txt, where it belongs. + +#### March 5, 2007 + +* Minor edit to clarify the description of the route_long_name field. + +#### February 28, 2007 + +* Addition of frequencies.txt for headway-based schedule support. +* Multiple agencies now allowed in the the same feed. Also added new agency_id field in both agencies.txt and routes.txt that lets you specify which route is operated by which agency. +* Addition of per-route and per-stop URLs. +* Addition of direction_id field in trips.txt. +* Support for mid-trip headsign changes with addition of stop_headsign field in stop_times.txt. +* Support for route colors with addition of optional route_color and route_text_color in routes.txt. +* Removed the ability to specify stops using street addresses. The previous version of the spec allowed you to give the location of a transit stop using a street address in the stop_street, stop_city, stop_region, stop_postcode, and stop_country fields. Now stop locations must be given using stop_lat for latitude and stop_lon for longitude, which are more useful for most applications. +* Addition of cable car vehicle type for route_type field in routes.txt. +* See the original [Headway blog post](http://headwayblog.com/2007/03/02/google-feed-spec-update-2007-02/) summary of the changes. + +#### November 29, 2006 + +* Added support for trip shape information via shapes.txt +* Clarified the definition of stop_sequence +* Marked pickup_type and drop_off_type optional + +#### October 31, 2006 + +* Added support for fare information +* Removed dates from individual file names +* Changed the route_type value definitions +* Allowed for multiple feed files to be posted at the same time, as long as their service periods didn't overlap +* Fixed block_id in trips.txt so that it was correctly marked Optional +* Noted that column headers must be included + +#### September 29, 2006 + +* Minor edit to fix a couple errors in the examples. + +#### September 25, 2006 + +* Initial version. diff --git a/transit/gtfs/README.md b/transit/gtfs/README.md new file mode 100644 index 000000000..0b9b7d109 --- /dev/null +++ b/transit/gtfs/README.md @@ -0,0 +1,5 @@ +This directory contains GTFS Specification and documentation. + +### Quick links +- [Documentation](spec/en) +- [How to change the specification?](CHANGES.md) \ No newline at end of file diff --git a/transit/gtfs/spec/en/README.md b/transit/gtfs/spec/en/README.md new file mode 100644 index 000000000..b86e258f5 --- /dev/null +++ b/transit/gtfs/spec/en/README.md @@ -0,0 +1,37 @@ +# What is GTFS? + +The General Transit Feed Specification (GTFS) defines a common format for public transportation schedules and associated geographic information. GTFS "feeds" allow public transit agencies to publish their transit data and developers to write applications that consume that data in an interoperable way. + +## How do I start? + +1. Continue reading the overview below. +1. Take a look at the [example feeds](examples/). +1. Create your own feeds using the [reference](reference.md) as a guide. +1. Test your feed using [validation tools](tools.md). +1. Publish your feed. + +## Overview of a GTFS feed + +A GTFS feed is composed of a series of text files collected in a ZIP file. Each file models a particular aspect of transit information: stops, routes, trips, and other schedule data. The details of each file are defined in the [GTFS reference](reference.md). An example feed can be found in the [GTFS examples](examples/). A transit agency can produce a GTFS feed to share their public transit information with developers, who write tools that consume GTFS feeds to incorporate public transit information into their applications. GTFS can be used to power trip planners, time table publishers, and a variety of applications, too diverse to list here, that use public transit information in some way. + +## Making a Transit Feed Publicly Available + +Many applications are compatible with data in the GTFS format. The simplest way to make a feed public is to host it on a web server and publish an announcement that makes it available for use. + +Here are a few ways that interested software developers learn about public feeds: + +* A list of transit agencies who provide public feeds is available on the [TransitWiki.org "Publicly-accessible public transportation data" page](http://www.transitwiki.org/TransitWiki/index.php?title=Publicly-accessible_public_transportation_data). +* Several websites allows developers to subscribe to announcements about new and updated feeds, and serve as a registry of feeds: + * [Gtfs Data Exchange.com](http://www.gtfs-data-exchange.com/) + * [TransitFeeds.com](http://transitfeeds.com/) + * [Transit.land](https://transit.land/feed-registry/) + +## Submitting a Transit Feed to Google + +If you're at a public agency that oversees public transportation for your city, you can use the GTFS specification to provide schedules and geographic information to Google Maps and other Google applications that show transit information. For full details, please refer to the [Google Transit Partners Program website](http://maps.google.com/help/maps/mapcontent/transit/participate.html). + +## Getting Help + +To participate in discussions around GTFS and suggest changes and additions to the specification, join the [GTFS changes mailing list](http://groups.google.com/group/gtfs-changes). + +*Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.* \ No newline at end of file diff --git a/transit/gtfs/spec/en/community.md b/transit/gtfs/spec/en/community.md new file mode 100644 index 000000000..e13c65c28 --- /dev/null +++ b/transit/gtfs/spec/en/community.md @@ -0,0 +1,25 @@ +## Community + +### Mailing Lists + +There are a number of mailing lists that can be good resources when you have questions about public transit data, software, formats like GTFS and GTFS-realtime, and other issues: + +* transitfeed: discussion of the open-source transitfeed project, as well of discussion of the GTFS specification and associated tools. +* gtfs-realtime: discussion of the GTFS-realtime specification. +* gtfs-changes: discussion of proposal for extending the GTFS specification, as outlined in the GTFS Changes document. +* transit-developers: general transit developer discussions. Many transit agencies also have their own developer mailing lists specific to the agency. For example: + * NYC MTA + * Portland, OR + * BART - San Francisco, CA + * MassDOT + +Check with your local transit agency to see if they have a mailing list of their own. + +## Other Resources + +* [TransitWiki.org "General Transit Feed Specification" page](http://www.transitwiki.org/TransitWiki/index.php?title=General_Transit_Feed_Specification) +* Public GTFS feed list - [TransitWiki.org "Publicly-accessible public transportation data" page](http://www.transitwiki.org/TransitWiki/index.php?title=Publicly-accessible_public_transportation_data). +* Several websites serve as a registry of feeds: + * [Gtfs Data Exchange.com](http://www.gtfs-data-exchange.com/) + * [TransitFeeds.com](http://transitfeeds.com/) + * [Transit.land](https://transit.land/feed-registry/) \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/README.md b/transit/gtfs/spec/en/examples/README.md new file mode 100644 index 000000000..0f5d73817 --- /dev/null +++ b/transit/gtfs/spec/en/examples/README.md @@ -0,0 +1,130 @@ +## Example GTFS Feed + +This example GTFS feed shows comma-delimited data samples for each file in a transit feed. The sample data files shown here aren't all related to each other. You can also [download a complete GTFS feed](sample-feed-1.zip) in final form to work with as well, or browse the individual files of that same feed online [here](sample-feed-1). + +### agency.txt + +~~~ +agency_id,agency_name,agency_url,agency_timezone,agency_phone,agency_lang +FunBus,The Fun Bus,http://www.thefunbus.org,America/Los_Angeles,(310) 555-0222,en +~~~ + +### stops.txt + +~~~ +stop_id,stop_name,stop_desc,stop_lat,stop_lon,stop_url,location_type,parent_station +S1,Mission St. & Silver Ave.,The stop is located at the southwest corner of the intersection.,37.728631,-122.431282,,, +S2,Mission St. & Cortland Ave.,The stop is located 20 feet south of Mission St.,37.74103,-122.422482,,, +S3,Mission St. & 24th St.,The stop is located at the southwest corner of the intersection.,37.75223,-122.418581,,, +S4,Mission St. & 21st St.,The stop is located at the northwest corner of the intersection.,37.75713,-122.418982,,, +S5,Mission St. & 18th St.,The stop is located 25 feet west of 18th St.,37.761829,-122.419382,,, +S6,Mission St. & 15th St.,The stop is located 10 feet north of Mission St.,37.766629,-122.419782,,, +S7,24th St. Mission Station,,37.752240,-122.418450,,,S8 +S8,24th St. Mission Station,,37.752240,-122.418450,http://www.bart.gov/stations/stationguide/stationoverview_24st.asp,1, +~~~ + +### routes.txt + +~~~ +route_id,route_short_name,route_long_name,route_desc,route_type +A,17,Mission,"The ""A"" route travels from lower Mission to Downtown.",3 +~~~ + +### trips.txt + +~~~ +route_id,service_id,trip_id,trip_headsign,block_id +A,WE,AWE1,Downtown,1 +A,WE,AWE2,Downtown,2 +~~~ + +### stop_times.txt + +~~~ +trip_id,arrival_time,departure_time,stop_id,stop_sequence,pickup_type,drop_off_type +AWE1,0:06:10,0:06:10,S1,1,0,0 +AWE1,,,S2,2,1,3 +AWE1,0:06:20,0:06:30,S3,3,0,0 +AWE1,,,S5,4,0,0 +AWE1,0:06:45,0:06:45,S6,5,0,0 +AWD1,0:06:10,0:06:10,S1,1,0,0 +AWD1,,,S2,2,0,0 +AWD1,0:06:20,0:06:20,S3,3,0,0 +AWD1,,,S4,4,0,0 +AWD1,,,S5,5,0,0 +AWD1,0:06:45,0:06:45,S6,6,0,0 +~~~ + +### calendar.txt + +~~~ +service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date +WE,0,0,0,0,0,1,1,20060701,20060731 +WD,1,1,1,1,1,0,0,20060701,20060731 +~~~ + +### calendar_dates.txt + +This example shows service exceptions for the Independence Day holiday in 2006. On Monday July 3, 2006, regular weekday service (`service_id=WD`) is interrupted (`exception_type=2`). Instead, weekend service (`service_id=WE`) runs on that date (`exception_type=1`). The same change applies on Tuesday July 4, as well. + +~~~ +service_id,date,exception_type +WD,20060703,2 +WE,20060703,1 +WD,20060704,2 +WE,20060704,1 +~~~ + +### fare_attributes.txt + +~~~ +fare_id,price,currency_type,payment_method,transfers,transfer_duration +1,0.00,USD,0,0,0 +2,0.50,USD,0,0,0 +3,1.50,USD,0,0,0 +4,2.00,USD,0,0,0 +5,2.50,USD,0,0,0 +~~~ + +### fare_rules.txt + +~~~ +fare_id,route_id,origin_id,destination_id,contains_id +a,TSW,1,1, +a,TSE,1,1, +a,GRT,1,1, +a,GRJ,1,1, +a,SVJ,1,1, +a,JSV,1,1, +a,GRT,2,4, +a,GRJ,4,2, +b,GRT,3,3, +c,GRT,,,6 +~~~ + +### shapes.txt + +~~~ +shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled +A_shp,37.61956,-122.48161,1,0 +A_shp,37.64430,-122.41070,2,6.8310 +A_shp,37.65863,-122.30839,3,15.8765 +~~~ + +### frequencies.txt + +~~~ +trip_id,start_time,end_time,headway_secs +AWE1,05:30:00,06:30:00,300 +AWE1,06:30:00,20:30:00,180 +AWE1,20:30:00,28:00:00,420 +~~~ + +### transfers.txt + +~~~ +from_stop_id,to_stop_id,transfer_type,min_transfer_time +S6,S7,2,300 +S7,S6,3, +S23,S7,1, +~~~ diff --git a/transit/gtfs/spec/en/examples/sample-feed-1.zip b/transit/gtfs/spec/en/examples/sample-feed-1.zip new file mode 100644 index 0000000000000000000000000000000000000000..79819e21ad51d7b0dcf0aeb51a298437df4bdfc3 GIT binary patch literal 3217 zcmZ{m3pAAL8pppGmzc!3rnE^W83xld<5IH8WS6DlTib5Yz3J|5a3=>0? z66^dH9;3#1Gv*S&DcRPx6|xX?$Nq#-??W;E$PAI>AK=wF9rB8tP9neEt{L} zk||l3C~s$*)R62@dSoy|SeP-LDa>#>(Q{3KcsQqBx2I*@_7<$z$`#7FD#|PQ%4XfI zkJ55Nn{v1zUSO9Ao#@d-i`;9;%5)Fw4L^6RiR~U1!DO)z$(gkej z4VFCEbPtou@?`ROT=vdjqDdyj)l6hB-?6BmF&?xlF ze(jg~sV5n&!xD7vY6**IBiiK(S@Q9iZQ<(mKB9_$7TA1Vrxtf=sO=B(qwHsm!K$U# zT@Uwve}S6Q77Mg}grZETK-Uhir2p2&4faJ8BN@oriYSI|%X$o-CZ-#fy*53i&GZviJ`+YJd{O9^QS0fWLwF&- z=1q#)oRV6gWMiP0YY0%`ih>{+SP7RE7!1xf8zJQ_kitMn(ZRP7;=%F3>rn~X3HrA? z=ntrO>>`OI2YJUfd7T$Yjz^Pfqb!cE3hpS8lH%L6v`VxQD~ZH@?kA}Pa&&v1d!8Fw zc1xQ?b>`_KVoq&x+AQ&h(RR&@mQHBTReX_0C@ym2o&K@rQkm*ijFW5aQ&k4iME^Qd zvlB@I=UyaB(0dIC-vori6Up_T*Hx^^e9iP!bIf5P)@mv$q!m@<<#T}VEnD}hD6umu z+Q^wrCTTMKpOY#5WA~0t)c~xxka@ZmoS;P3h&;&010s5f=;keqEO)vuD}yi34wESU*fnF(Z>} zw&`Xz(UAk64>~68m9ZBdBpa~c4-fKY1|XVM0h;x1WV7zt5NzOK$BS>k*bWBC*`*oH zgh|*3?qjm|?ci!V;nr5v;I5z5DkD(VQN$2cE(BF}zi?4K1yuNe=K9*<)uSy&etqK|x+2N!es1zq?sCNaH%B=UjF}U{w z-?GQQ>ZGTh@2*u%ou0(gL{kR|!(l7?Zn;|4pQrZ|yVX=;O|Edz1`|&yK_?}#VcyAW zTm&!5RzC_dnDTrWVdfoEH{m7oLrY++Qfq!%r)p=32gW;w@2oCgrLkw}3MNU5wX3?e?NIMTO#(#>Avy@mcCLxGVb?p zwsxRM!pGWv^)jJ26jjTx-*i8%3StHOwlRx$ih;WQJq(tjUB7Ksby;; z2zAP64RWS^wP{HBy#oW+s~bt>YW+i#g|{OIFAVk+_MM^K&AxhL_*{+bXWN%_XG;T; zlg5iialeoc`-dIVG*OP}LzlyFY<%~KX1UGGO55Hs&5WwgVjl}nyi%DPb~oT+=(dgr z?x33CQwIZg1$WKA!*T{qigg7fJvi`A(kvJFMyJB^igjYpUDwp67E#5%94 z#2&0Y*gMYtS{I*#^++*05fpA^qHBLhA(^zr``oGU9N9QZ;salU#O1q`3o72!GrmYS zjq@p@H!lsln3ezeqSG_r5IRBWK&|u617`B)Sg~X2`fcRjs-d$eSobZPYnbz0~&I5cB%2Tb!h&>FZcz@iXs;e+`?wk0K%E*(Y0#!PAUMT&H6>0DZA zDJTDIS|pIAo!q$%zalZAx>{E#!P$PN{mY&mp41R={c^t2YkZLYvfD!&bQG*~+E-$z zxhevmxJ$OfA%|QNnt!>oH`#*wgtNiRMD&bEA3j*aqY1r5d7zc4Dd^fwNFr=rWvo(@ z6IZ;!TAj~&KNPB(dsO|A&~p=7h2>WuJnWODpTToVT6H)V`>s*deahE!U*)P4x2byN z-g9ZcH`3LbRikX5C9YPq9k_V;Lp^2YX|&#twrzA$AHxoXUM})aIcpgx3Iu_wKxZT2 zCuHgpn@wHLp%A#T<{*nB5fYLQAoBwfz`y}%4)af`1&J{QlK#dZGYo*i8DMT5SJF&|?_1Fbn_^90nGW7W*-h zlpzAmb7ug7-FYEov9}>1Nx*=RP6r^c(=CK7_ADf18ip)zFaUxbY$0gzb%_Kui_e1o qcXPC8(~lRnE31AGWt3Vw>9czYz_xBmiKz-WR1 literal 0 HcmV?d00001 diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/agency.txt b/transit/gtfs/spec/en/examples/sample-feed-1/agency.txt new file mode 100644 index 000000000..eb24555d0 --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/agency.txt @@ -0,0 +1,2 @@ +agency_id,agency_name,agency_url,agency_timezone +DTA,Demo Transit Authority,http://google.com,America/Los_Angeles \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/calendar.txt b/transit/gtfs/spec/en/examples/sample-feed-1/calendar.txt new file mode 100644 index 000000000..b95f2a7c6 --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/calendar.txt @@ -0,0 +1,3 @@ +service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date +FULLW,1,1,1,1,1,1,1,20070101,20101231 +WE,0,0,0,0,0,1,1,20070101,20101231 \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/calendar_dates.txt b/transit/gtfs/spec/en/examples/sample-feed-1/calendar_dates.txt new file mode 100644 index 000000000..51c495bf8 --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/calendar_dates.txt @@ -0,0 +1,2 @@ +service_id,date,exception_type +FULLW,20070604,2 \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/fare_attributes.txt b/transit/gtfs/spec/en/examples/sample-feed-1/fare_attributes.txt new file mode 100644 index 000000000..9c3b421fc --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/fare_attributes.txt @@ -0,0 +1,3 @@ +fare_id,price,currency_type,payment_method,transfers,transfer_duration +p,1.25,USD,0,0, +a,5.25,USD,0,0, \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/fare_rules.txt b/transit/gtfs/spec/en/examples/sample-feed-1/fare_rules.txt new file mode 100644 index 000000000..acf470ddc --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/fare_rules.txt @@ -0,0 +1,5 @@ +fare_id,route_id,origin_id,destination_id,contains_id +p,AB,,, +p,STBA,,, +p,BFC,,, +a,AAMV,,, \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/frequencies.txt b/transit/gtfs/spec/en/examples/sample-feed-1/frequencies.txt new file mode 100644 index 000000000..47941ef36 --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/frequencies.txt @@ -0,0 +1,12 @@ +trip_id,start_time,end_time,headway_secs +STBA,6:00:00,22:00:00,1800 +CITY1,6:00:00,7:59:59,1800 +CITY2,6:00:00,7:59:59,1800 +CITY1,8:00:00,9:59:59,600 +CITY2,8:00:00,9:59:59,600 +CITY1,10:00:00,15:59:59,1800 +CITY2,10:00:00,15:59:59,1800 +CITY1,16:00:00,18:59:59,600 +CITY2,16:00:00,18:59:59,600 +CITY1,19:00:00,22:00:00,1800 +CITY2,19:00:00,22:00:00,1800 \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/routes.txt b/transit/gtfs/spec/en/examples/sample-feed-1/routes.txt new file mode 100644 index 000000000..398ba162c --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/routes.txt @@ -0,0 +1,6 @@ +route_id,agency_id,route_short_name,route_long_name,route_desc,route_type,route_url,route_color,route_text_color +AB,DTA,10,Airport - Bullfrog,,3,,, +BFC,DTA,20,Bullfrog - Furnace Creek Resort,,3,,, +STBA,DTA,30,Stagecoach - Airport Shuttle,,3,,, +CITY,DTA,40,City,,3,,, +AAMV,DTA,50,Airport - Amargosa Valley,,3,,, \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/shapes.txt b/transit/gtfs/spec/en/examples/sample-feed-1/shapes.txt new file mode 100644 index 000000000..aa62a022a --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/shapes.txt @@ -0,0 +1 @@ +shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/stop_times.txt b/transit/gtfs/spec/en/examples/sample-feed-1/stop_times.txt new file mode 100644 index 000000000..90c649cf4 --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/stop_times.txt @@ -0,0 +1,29 @@ +trip_id,arrival_time,departure_time,stop_id,stop_sequence,stop_headsign,pickup_type,drop_off_type,shape_dist_traveled +STBA,6:00:00,6:00:00,STAGECOACH,1,,,, +STBA,6:20:00,6:20:00,BEATTY_AIRPORT,2,,,, +CITY1,6:00:00,6:00:00,STAGECOACH,1,,,, +CITY1,6:05:00,6:07:00,NANAA,2,,,, +CITY1,6:12:00,6:14:00,NADAV,3,,,, +CITY1,6:19:00,6:21:00,DADAN,4,,,, +CITY1,6:26:00,6:28:00,EMSI,5,,,, +CITY2,6:28:00,6:30:00,EMSI,1,,,, +CITY2,6:35:00,6:37:00,DADAN,2,,,, +CITY2,6:42:00,6:44:00,NADAV,3,,,, +CITY2,6:49:00,6:51:00,NANAA,4,,,, +CITY2,6:56:00,6:58:00,STAGECOACH,5,,,, +AB1,8:00:00,8:00:00,BEATTY_AIRPORT,1,,,, +AB1,8:10:00,8:15:00,BULLFROG,2,,,, +AB2,12:05:00,12:05:00,BULLFROG,1,,,, +AB2,12:15:00,12:15:00,BEATTY_AIRPORT,2 +BFC1,8:20:00,8:20:00,BULLFROG,1 +BFC1,9:20:00,9:20:00,FUR_CREEK_RES,2 +BFC2,11:00:00,11:00:00,FUR_CREEK_RES,1 +BFC2,12:00:00,12:00:00,BULLFROG,2 +AAMV1,8:00:00,8:00:00,BEATTY_AIRPORT,1 +AAMV1,9:00:00,9:00:00,AMV,2 +AAMV2,10:00:00,10:00:00,AMV,1 +AAMV2,11:00:00,11:00:00,BEATTY_AIRPORT,2 +AAMV3,13:00:00,13:00:00,BEATTY_AIRPORT,1 +AAMV3,14:00:00,14:00:00,AMV,2 +AAMV4,15:00:00,15:00:00,AMV,1 +AAMV4,16:00:00,16:00:00,BEATTY_AIRPORT,2 diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/stops.txt b/transit/gtfs/spec/en/examples/sample-feed-1/stops.txt new file mode 100644 index 000000000..8ed623d08 --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/stops.txt @@ -0,0 +1,10 @@ +stop_id,stop_name,stop_desc,stop_lat,stop_lon,zone_id,stop_url +FUR_CREEK_RES,Furnace Creek Resort (Demo),,36.425288,-117.133162,, +BEATTY_AIRPORT,Nye County Airport (Demo),,36.868446,-116.784582,, +BULLFROG,Bullfrog (Demo),,36.88108,-116.81797,, +STAGECOACH,Stagecoach Hotel & Casino (Demo),,36.915682,-116.751677,, +NADAV,North Ave / D Ave N (Demo),,36.914893,-116.76821,, +NANAA,North Ave / N A Ave (Demo),,36.914944,-116.761472,, +DADAN,Doing Ave / D Ave N (Demo),,36.909489,-116.768242,, +EMSI,E Main St / S Irving St (Demo),,36.905697,-116.76218,, +AMV,Amargosa Valley (Demo),,36.641496,-116.40094,, \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/trips.txt b/transit/gtfs/spec/en/examples/sample-feed-1/trips.txt new file mode 100644 index 000000000..7ee117edc --- /dev/null +++ b/transit/gtfs/spec/en/examples/sample-feed-1/trips.txt @@ -0,0 +1,12 @@ +route_id,service_id,trip_id,trip_headsign,direction_id,block_id,shape_id +AB,FULLW,AB1,to Bullfrog,0,1, +AB,FULLW,AB2,to Airport,1,2, +STBA,FULLW,STBA,Shuttle,,, +CITY,FULLW,CITY1,,0,, +CITY,FULLW,CITY2,,1,, +BFC,FULLW,BFC1,to Furnace Creek Resort,0,1, +BFC,FULLW,BFC2,to Bullfrog,1,2, +AAMV,WE,AAMV1,to Amargosa Valley,0,, +AAMV,WE,AAMV2,to Airport,1,, +AAMV,WE,AAMV3,to Amargosa Valley,0,, +AAMV,WE,AAMV4,to Airport,1,, \ No newline at end of file diff --git a/transit/gtfs/spec/en/reference.md b/transit/gtfs/spec/en/reference.md new file mode 100644 index 000000000..8d1387af3 --- /dev/null +++ b/transit/gtfs/spec/en/reference.md @@ -0,0 +1,429 @@ +## General Transit Feed Specification Reference + +**Revised August 4, 2016. 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. + +## Table of Contents + +1. [Term Definitions](#term-definitions) +2. [Feed Files](#feed-files) +3. [File Requirements](#file-requirements) +4. [Field Definitions](#field-definitions) + - [agency.txt](#agencytxt) + - [stops.txt](#stopstxt) + - [routes.txt](#routestxt) + - [trips.txt](#tripstxt) + - [stop\_times.txt](#stop_timestxt) + - [calendar.txt](#calendartxt) + - [calendar\_dates.txt](#calendar_datestxt) + - [fare\_attributes.txt](#fare_attributestxt) + - [fare\_rules.txt](#fare_rulestxt) + - [shapes.txt](#shapestxt) + - [frequencies.txt](#frequenciestxt) + - [transfers.txt](#transferstxt) + - [feed\_info.txt](#feed_infotxt) + +## Term Definitions + +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. +* **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. + +## Feed Files + +This specification defines the following files along with their associated content: + +| 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. | +| [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) | **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. | +| [calendar_dates.txt](#calendar_datestxt) | Optional | Exceptions for the service IDs defined in the [calendar.txt](#calendartxt) file. If [calendar.txt](#calendartxt) includes ALL dates of service, this file may be specified instead of [calendar.txt](#calendartxt). | +| [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. | +| [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. | + +## File Requirements + +The following requirements apply to the format and contents of your 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 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. +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. + +## Field Definitions + +### agency.txt + +File: **Required** + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| agency_id | Optional | The **agency_id** field is an ID that uniquely identifies a transit agency. A transit feed may represent data from more than one agency. The **agency_id** is dataset unique. This field is optional for transit feeds that only contain data for a single agency. | +| agency_name | Required | The **agency_name** field contains the full name of the transit agency. Google Maps will display this name. | +| agency_url | Required | The **agency_url** field contains the URL of the transit agency. The value must be 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. | +| agency_timezone | Required | The **agency_timezone** field contains the timezone where the transit agency is located. Timezone names never contain the space character but may contain an underscore. Please refer to http://en.wikipedia.org/wiki/List_of_tz_zones for a list of valid values. If multiple agencies are specified in the feed, each must have the same agency_timezone. | +| agency_lang | Optional | The **agency_lang field** contains a two-letter ISO 639-1 code for the primary language used by this transit agency. The language code is case-insensitive (both en and EN are accepted). This setting defines capitalization rules and other language-specific settings for all text contained in this transit agency's feed. Please refer to http://www.loc.gov/standards/iso639-2/php/code_list.php for a list of valid values. | +| agency_phone | 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 | 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. The value must be 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. | +| agency_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. | + +### stops.txt + +File: **Required** + +| Field Name | Required | Details | | | +| ------ | ------ | ------ | ------ | ------ | +| stop_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. The **stop_id** is used by systems as an internal identifier of this record (e.g., primary key in database), and therefore the **stop_id** must be dataset unique. | | | +| stop_code | 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 | **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 | 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 | **Required** | The **stop_lat** field contains the latitude of a stop, station, or station entrance. The field value must be a valid WGS 84 latitude. | | | +| stop_lon | **Required** | The **stop_lon** field contains the longitude of a stop, station, or station entrance. The field value must be a valid WGS 84 longitude value from -180 to 180. | | | +| zone_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 | 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. The value must be 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. | | | +| location_type | 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 | 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. | | | +| | | **This stop ID represents...** | **This entry's location type...** | **This entry's parent_station field contains...** | +| | | A stop located inside a station. | 0 or blank | The stop ID of the station where this stop is located. The stop referenced by parent_station must have location_type=1. | +| | | A stop located outside a station. | 0 or blank | A blank value. The parent_station field doesn't apply to this stop. | +| | | A station. | 1 | A blank value. Stations can't contain other stations. | +| stop_timezone | Optional | The **stop_timezone** field contains the timezone in which this stop, station, or station entrance is located. Please refer to [Wikipedia List of Timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of valid values. 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 | 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 | | | + +### routes.txt + +File: **Required** + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| route_id | **Required** | The **route_id** field contains an ID that uniquely identifies a route. The route_id is dataset unique. | +| agency_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 | **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 | **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 | 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 | **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 | Optional | The **route_url** field contains the URL of a web page about that particular route. This should be different from the agency_url. The value must be 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. | +| route_color | Optional | In systems that have colors assigned to routes, the **route_color** field defines a color that corresponds to a route. The color must be provided as a six-character hexadecimal number, for example, 00FFFF. 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 | 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. The color must be provided as a six-character hexadecimal number, for example, FFD700. 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. | + +### trips.txt + +File: **Required** + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| route_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 | **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 | **Required** | The **trip_id** field contains an ID that identifies a trip. The **trip_id** is dataset unique. | +| trip_headsign | 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 the **stop_headsign** field in [stop_times.txt](#stop_timestxt). | +| trip_short_name | 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 | 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 | 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 | 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 | 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 | 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 + +The example below is valid, with distinct blocks every day of the week. + +| route_id | trip_id | service_id | block_id | *(first stop time)* | *(last stop time)* | +|----------|---------|--------------------------------|----------|-----------------------------------------|-------------------------| +| red | trip_1 | mon-tues-wed-thurs-fri-sat-sun | red_loop | 22:00:00 | 22:55:00 | +| red | trip_2 | fri-sat-sun | red_loop | 23:00:00 | 23:55:00 | +| red | trip_3 | fri-sat | red_loop | 24:00:00 | 24:55:00 | +| red | trip_4 | mon-tues-wed-thurs | red_loop | 20:00:00 | 20:50:00 | +| 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. + +### stop_times.txt + +File: **Required** + +| Field Name | Required | Details | | +| ------ | ------ | ------ | ------ | +| trip_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 | **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 | **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 | **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 | **Required** | The **stop_sequence** field identifies the order of the stops for a particular trip. The values for **stop_sequence** must be non-negative integers, and they 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 | 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 | 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 | 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 | 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 | 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. | | + +### calendar.txt + +File: **Required** + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| service_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 | **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 | **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 | **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 | **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 | **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 | **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 | **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 | **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 | **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. | + +### calendar_dates.txt + +File: **Optional** + +The calendar_dates table allows you to explicitly activate or disable service IDs by date. You can use it 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 accomodate 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. + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| service_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 | **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 | **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. | + +### fare_attributes.txt + +File: **Optional** + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| fare_id | **Required** | The **fare_id** field contains an ID that uniquely identifies a fare class. The **fare_id** is dataset unique. | +| price | **Required** | The **price** field contains the fare price, in the unit specified by **currency_type**. | +| currency_type | **Required** | The **currency_type** field defines the currency used to pay the fare. Please use the ISO 4217 alphabetical currency codes which can be found at the following URL: http://en.wikipedia.org/wiki/ISO_4217. | +| payment_method | **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 | **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 | 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 | 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_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: + +* 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. + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| fare_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 | 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 | 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 | 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 | 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. | + +### 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. + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| shape_id | **Required** | The **shape_id** field contains an ID that uniquely identifies a shape. | +| shape_pt_lat | **Required** | The **shape_pt_lat** field associates a shape point's latitude with a shape ID. The field value must be a valid WGS 84 latitude. 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 | **Required** | The **shape_pt_lon** field associates a shape point's longitude with a shape ID. The field value must be a valid WGS 84 longitude value from -180 to 180. 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 | **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 be non-negative integers, and they 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 | 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` | + +### 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. + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| trip_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 | **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 | **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 | **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 | 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**. | + +### 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. + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| from_stop_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 | **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 | **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 | 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. | + +### 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. + +| Field Name | Required | Details | +| ------ | ------ | ------ | +| feed_publisher_name | **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 | **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).) The value must be 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_lang | Required | The **feed_lang** field contains a IETF BCP 47 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. 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/. | +| feed_start_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 are given as dates in YYYYMMDD format as for [calendar.txt](#calendartxt), or 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 | Optional | (see above) | +| feed_version | 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. | \ No newline at end of file diff --git a/transit/gtfs/spec/en/style-guide.md b/transit/gtfs/spec/en/style-guide.md new file mode 100644 index 000000000..ab06b95e3 --- /dev/null +++ b/transit/gtfs/spec/en/style-guide.md @@ -0,0 +1,33 @@ +## GTFS Style Guide + +The GTFS specification provides a lot of flexibility in how a physical transit system is modeled. What is the best approach? In general, it is a good idea to keep the following guidelines in mind when developing a feed. + +### Route Organization + +The entries in [routes.txt](reference.md#routes.txt) should typically have the same organization as the physical routes communicated to riders by an agency. As an example, an agency will often first group their timetables by route when presenting them on a website or in a printed booklet. The entries in routes.txt should generally have a one-to-one correspondence to the timetable routes. It can be tempting for an agency to break a physical route into multiple entries in routes.txt in order to represent different route variations, such as direction of travel, but the preferred approach is to instead use features of [trips.txt](reference.md#trips.txt) to model those variations. Multiple entries in routes.txt with the same route short name or route long name are often an indication that routes have been needlessly subdivided. + +Do: + +~~~ +**routes.txt** +route_id,route_short_name,route_long_name,route_type +R10,10,Airport - Downtown,3 +~~~ + +~~~ +**trips.txt** +route_id,trip_id,trip_headsign,direction_id +R10,T-10-1,Airport,0 +R10,T-10-2,Downtown,1 +~~~ + +Don't: + +~~~ +**routes.txt** +route_id,route_short_name,route_long_name,route_type +R10-in,10,To Downtown,3 +R10-out,10,To Airport,3 +R20-in,20,To Downtown,3 +R20-out,20,To University,3 +~~~ \ No newline at end of file diff --git a/transit/gtfs/spec/en/tools.md b/transit/gtfs/spec/en/tools.md new file mode 100644 index 000000000..bb1239378 --- /dev/null +++ b/transit/gtfs/spec/en/tools.md @@ -0,0 +1,8 @@ +## Tools + +### Testing Your GTFS Feeds + +Two Open Source tools are available for testing feeds in the GTFS format: + +* Use the [feedvalidator tool](https://github.com/google/transitfeed/wiki/FeedValidator) to verify that your feed data file matches the specification defined in this document. +* Use the [schedule_viewer application](https://github.com/google/transitfeed/wiki/ScheduleViewer) to see your feed data represented on a map. This is not representative of how your data will look in other applications; it is a basic tool for testing. Examine routes and schedules to ensure that the data feed correctly represents your system. \ No newline at end of file From 141479aca18202ae1072e655bc9e643a764594b9 Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Tue, 11 Jul 2017 16:57:28 +1000 Subject: [PATCH 03/10] Fix up TOC and formatting. --- gtfs-realtime/spec/en/reference.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 096f14be5..7da756c50 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -20,6 +20,13 @@ Version 1.0 of the feed specification is discussed and documented on this site. * [TripDescriptor](#message-tripdescriptor) * [ScheduleRelationship](#enum-schedulerelationship-1) * [VehicleDescriptor](#message-vehicledescriptor) + * [CarriageDescriptor](#message-carriagedescriptor) + * [OccupancyStatus](#enum-occupancystatus) + * [WheelchairAccessible](#enum-wheelchairaccessible) + * [ToiletFacilities](#enum-toiletfacilities) + * [WifiAvailability](#enum-wifiavailability) + * [AirConditioning](#enum-airconditioning) + * [BicyclesAllowed](#enum-bicyclesallowed) * [StopTimeUpdate](#message-stoptimeupdate) * [StopTimeEvent](#message-stoptimeevent) * [ScheduleRelationship](#enum-schedulerelationship) @@ -208,7 +215,7 @@ Congestion level that is affecting this vehicle. ## _enum OccupancyStatus_ -The degree of passenger occupancy for the vehicle. +The degree of passenger occupancy for the vehicle or carriage. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. @@ -216,13 +223,13 @@ The degree of passenger occupancy for the vehicle. | _**Value**_ | _**Comment**_ | |-------------|---------------| -| _**EMPTY**_ | _The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ | -| _**MANY_SEATS_AVAILABLE**_ | _The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ | -| _**FEW_SEATS_AVAILABLE**_ | _The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ | -| _**STANDING_ROOM_ONLY**_ | _The vehicle can currently accomodate only standing passengers._ | -| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle can currently accomodate only standing passengers and has limited space for them._ | -| _**FULL**_ | _The vehicle is considered full by most measures, but may still be allowing passengers to board._ | -| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle can not accept passengers._ | +| _**EMPTY**_ | _The vehicle/carriage is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ | +| _**MANY_SEATS_AVAILABLE**_ | _The vehicle/carriage has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ | +| _**FEW_SEATS_AVAILABLE**_ | _The vehicle/carriage has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ | +| _**STANDING_ROOM_ONLY**_ | _The vehicle/carriage can currently accommodate only standing passengers._ | +| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle/carriage can currently accommodate only standing passengers and has limited space for them._ | +| _**FULL**_ | _The vehicle/carriage is considered full by most measures, but may still be allowing passengers to board._ | +| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle/carriage can not accept passengers._ | ## _message_ Alert @@ -340,7 +347,7 @@ Identification information for the vehicle performing the trip. | _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|-------------------|-------------------| -| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field | +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field. | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle. | | **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The license plate of the vehicle. | | **carriage_descriptor** | [CarriageDescriptor](#message-carriagedescriptor) | repeated | An ordered list of carriage information. | @@ -353,7 +360,7 @@ Information for a carriage that is part of a vehicle. | _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|-------------------|-------------------| -| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the carriage. Should be **unique** per vehicle, and is used for tracking the carriage as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field | +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the carriage. Should be **unique** per vehicle, and is used for tracking the carriage as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field. | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that can be shown to the passenger to help identify the correct carriage. | | _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _optional_ |The degree of passenger occupancy of the carriage.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| | **wheelchair_accessible** | [WheelchairAccessible](#enum-wheelchairaccessible) | optional | Whether the carriage is wheelchair accessible. | From b228b28be092b58c06f995ab9ebe95bbd5f6676d Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Tue, 11 Jul 2017 17:28:12 +1000 Subject: [PATCH 04/10] Add extensions and fix documentation for CarriageDescriptor. --- gtfs-realtime/proto/gtfs-realtime.proto | 5 +++++ gtfs-realtime/spec/en/reference.md | 7 +++++++ gtfs-realtime/spec/en/vehicle-positions.md | 1 + 3 files changed, 13 insertions(+) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 575c47707..016746cc9 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -670,6 +670,11 @@ message VehicleDescriptor { } optional BicyclesAllowed bicycles_allowed = 8 [default = UNKNOWN]; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; } // An ordered set of CarriageDescriptor. The first element maps to the first diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 7da756c50..fc92be290 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -34,6 +34,13 @@ Version 1.0 of the feed specification is discussed and documented on this site. * [TripDescriptor](#message-tripdescriptor) * [ScheduleRelationship](#enum-schedulerelationship-1) * [VehicleDescriptor](#message-vehicledescriptor) + * [CarriageDescriptor](#message-carriagedescriptor) + * [OccupancyStatus](#enum-occupancystatus) + * [WheelchairAccessible](#enum-wheelchairaccessible) + * [ToiletFacilities](#enum-toiletfacilities) + * [WifiAvailability](#enum-wifiavailability) + * [AirConditioning](#enum-airconditioning) + * [BicyclesAllowed](#enum-bicyclesallowed) * [Position](#message-position) * [VehicleStopStatus](#enum-vehiclestopstatus) * [CongestionLevel](#enum-congestionlevel) diff --git a/gtfs-realtime/spec/en/vehicle-positions.md b/gtfs-realtime/spec/en/vehicle-positions.md index 62da24dd7..d8ffb6b78 100644 --- a/gtfs-realtime/spec/en/vehicle-positions.md +++ b/gtfs-realtime/spec/en/vehicle-positions.md @@ -57,3 +57,4 @@ Vehicle descriptor describes a precise physical vehicle and can contain any of t * **ID** - internal system of identification for the vehicle. Should be unique to the vehicle * **Label** - a user visible label - for example the name of a train * **License plate** - the actual license plate of the vehicle +* **Carriage descriptor** - an ordered list where each item specifies information about a carriage From 37e1f686d2a1ec4489372af31fea58db84a30ab3 Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Tue, 11 Jul 2017 17:39:16 +1000 Subject: [PATCH 05/10] Added CarriageDescriptor to Spanish reference. --- gtfs-realtime/spec/es/reference.md | 75 ++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/gtfs-realtime/spec/es/reference.md b/gtfs-realtime/spec/es/reference.md index 0b8c2e70a..b5e28dcfc 100644 --- a/gtfs-realtime/spec/es/reference.md +++ b/gtfs-realtime/spec/es/reference.md @@ -19,6 +19,13 @@ Las especificaciones de la versión 1.0 del feed se abordan y documentan en este * [TripDescriptor](#TripDescriptor) * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) * [VehicleDescriptor](#VehicleDescriptor) + * [CarriageDescriptor](#message-carriagedescriptor) + * [OccupancyStatus](#enum-occupancystatus) + * [WheelchairAccessible](#enum-wheelchairaccessible) + * [ToiletFacilities](#enum-toiletfacilities) + * [WifiAvailability](#enum-wifiavailability) + * [AirConditioning](#enum-airconditioning) + * [BicyclesAllowed](#enum-bicyclesallowed) * [StopTimeUpdate](#StopTimeUpdate) * [StopTimeEvent](#StopTimeEvent) * [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) @@ -324,6 +331,74 @@ Información de identificación para el vehículo que realiza el viaje. | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Identificación interna del sistema para el vehículo. Debe ser **única** para cada vehículo y se usa para hacer un seguimiento del vehículo en la medida en que avanza en el sistema. Este identificador debe ser visible para el usuario final; para ello debes usar el campo **label** | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Etiqueta visible para el usuario, es decir, que se debe mostrar al pasajero para ayudarlo a identificar el vehículo correcto. | | **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La patente del vehículo. | +| **carriage_descriptor** | [CarriageDescriptor](#CarriageDescriptor) | repetido | | + +## _mensaje_ CarriageDescriptor + +### Campos + +| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | +|------------------------|------------|--------------------|-------------------| +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | | +| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | | +| **occupancy_status** | [OccupancyStatus](#OccupancyStatus) | opcional | | +| **wheelchair_accessible** | [WheelchairAccessible](#WheelchairAccessible) | opcional | | +| **toilet_facilities** | [ToiletFacilities](#ToiletFacilities) | opcional | | +| **wifi_availability** | [WifiAvailability](#WifiAvailability) | opcional | | +| **air_conditioning** | [AirConditioning](#AirConditioning) | opcional | | +| **bicycles_allowed** | [BicyclesAllowed](#BicyclesAllowed) | opcional | | + +## _enum._ WheelchairAccessible + +### Valores + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **UNKNOWN** | | +| **WHEELCHAIR_ACCESSIBLE** | | +| **NOT_WHEELCHAIR_ACCESSIBLE** | | + +## _enum._ ToiletFacilities + +### Valores + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **UNKNOWN** | | +| **TOILET_ONBOARD** | | +| **NO_TOILET_ONBOARD** | | + +## _enum._ WifiAvailability + +### Valores + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **UNKNOWN** | | +| **FREE_WIFI** | | +| **PAID_WIFI** | | +| **NO_WIFI** | | + +## _enum._ AirConditioning + +### Valores + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **UNKNOWN** | | +| **AIR_CONDITIONED** | | +| **NOT_AIR_CONDITIONED** | | + +## _enum._ BicyclesAllowed + +### Valores + +| _**Valor**_ | _**Comentario**_ | +|-------------|------------------| +| **UNKNOWN** | | +| **ALLOWED_OUTSIDE_CARRIAGE** | | +| **ALLOWED_INSIDE_CARRIAGE** | | +| **NOT_ALLOWED** | | ## _mensaje_ EntitySelector From daa7b3c8508190d9812481ed95a039541e99ce84 Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Tue, 11 Jul 2017 17:55:28 +1000 Subject: [PATCH 06/10] Fixed anchors in spanish reference. --- gtfs-realtime/spec/es/reference.md | 112 ++++++++++++++--------------- 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/gtfs-realtime/spec/es/reference.md b/gtfs-realtime/spec/es/reference.md index b5e28dcfc..956c85d15 100644 --- a/gtfs-realtime/spec/es/reference.md +++ b/gtfs-realtime/spec/es/reference.md @@ -11,37 +11,37 @@ Las especificaciones de la versión 1.0 del feed se abordan y documentan en este ## Índice de elementos -* [FeedMessage](#FeedMessage) - * [FeedHeader](#FeedHeader) - * [Incrementality](#Incrementality) - * [FeedEntity](#FeedEntity) - * [TripUpdate](#TripUpdate) - * [TripDescriptor](#TripDescriptor) - * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) - * [VehicleDescriptor](#VehicleDescriptor) - * [CarriageDescriptor](#message-carriagedescriptor) +* [FeedMessage](#mensaje-feedmessage) + * [FeedHeader](#mensaje-feedheader) + * [Incrementality](#enum-incrementality) + * [FeedEntity](#mensaje-feedentity) + * [TripUpdate](#mensaje-tripupdate) + * [TripDescriptor](#mensaje-tripdescriptor) + * [ScheduleRelationship](#enum-schedulerelationship-1) + * [VehicleDescriptor](#mensaje-vehicledescriptor) + * [CarriageDescriptor](#mensaje-carriagedescriptor) * [OccupancyStatus](#enum-occupancystatus) * [WheelchairAccessible](#enum-wheelchairaccessible) * [ToiletFacilities](#enum-toiletfacilities) * [WifiAvailability](#enum-wifiavailability) * [AirConditioning](#enum-airconditioning) * [BicyclesAllowed](#enum-bicyclesallowed) - * [StopTimeUpdate](#StopTimeUpdate) - * [StopTimeEvent](#StopTimeEvent) - * [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) - * [VehiclePosition](#VehiclePosition) - * [TripDescriptor](#TripDescriptor) - * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) - * [Position](#Position) - * [Alert](#Alert) - * [TimeRange](#TimeRange) - * [EntitySelector](#EntitySelector) - * [TripDescriptor](#TripDescriptor) - * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) - * [Cause](#Cause) - * [Effect](#Effect) - * [TranslatedString](#TranslatedString) - * [Translation](#Translation) + * [StopTimeUpdate](#mensaje-stoptimeupdate) + * [StopTimeEvent](#mensaje-stoptimeevent) + * [ScheduleRelationship](#enum-schedulerelationship) + * [VehiclePosition](#mensaje-vehicleposition) + * [TripDescriptor](#mensaje-tripdescriptor) + * [ScheduleRelationship](#enum-schedulerelationship-1) + * [Position](#mensaje-position) + * [Alert](#mensaje-alert) + * [TimeRange](#mensaje-timerange) + * [EntitySelector](#mensaje-entitySelector) + * [TripDescriptor](#mensaje-tripdescriptor) + * [ScheduleRelationship](#enum-schedulerelationship-1) + * [Cause](#enum-cause) + * [Effect](#enum-effect) + * [TranslatedString](#mensaje-translatedstring) + * [Translation](#mensaje-translation) # Elementos @@ -59,8 +59,8 @@ Un feed depende de algunas configuraciones externas: | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **header** | [FeedHeader](#FeedHeader) | obligatorio | Metadatos sobre este feed y mensaje del feed | -| **entity** | [FeedEntity](#FeedEntity) | repetido | Contenido del feed | +| **header** | [FeedHeader](#mensaje-feedheader) | obligatorio | Metadatos sobre este feed y mensaje del feed | +| **entity** | [FeedEntity](#mensaje-feedentity) | repetido | Contenido del feed | ## _mensaje_ FeedHeader @@ -71,7 +71,7 @@ Metadatos sobre un feed, incluido en los mensajes del feed | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| | **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Especificación de la versión del feed. La versión actual es 1.0. | -| **incrementality** | [Incrementality](#Incrementality) | opcional | +| **incrementality** | [Incrementality](#enum-incrementality) | opcional | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Esta marca de tiempo identifica el momento en que se ha creado el contenido de este feed (en la hora del servidor). En la hora de POSIX (es decir, cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Para evitar el desvío de tiempos entre los sistemas que producen y que consumen información en tiempo real, se recomienda derivar la marca de tiempo desde un servidor de tiempo. Es absolutamente aceptable usar servidores de estrato 3 o, incluso, inferiores, porque las diferencias de tiempo de hasta un par de segundos son tolerables. | ## _enum._ Incrementality @@ -98,9 +98,9 @@ La definición (o actualización) de una entidad en el feed de transporte públi |------------------------|------------|--------------------|-------------------| | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Identificador único del feed para esta entidad. Los identificadores se usan solamente para proporcionar soporte de incrementalidad. Las entidades reales a las que hace referencia el feed deben especificarse mediante selectores explícitos (ver EntitySelector más adelante para obtener más información). | | **is_deleted** | [bool](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Establece si esta entidad debe eliminarse. Es relevante solo para las búsquedas incrementales. | -| **trip_update** | [TripUpdate](#TripUpdate) | opcional | Datos sobre las demoras de salida en tiempo real de un viaje. | -| **vehicle** | [VehiclePosition](#VehiclePosition) | opcional | Datos sobre la posición en tiempo real de un vehículo. | -| **alert** | [Alert](#Alert) | opcional | Datos sobre las alertas en tiempo real. | +| **trip_update** | [TripUpdate](#mensaje-tripupdate) | opcional | Datos sobre las demoras de salida en tiempo real de un viaje. | +| **vehicle** | [VehiclePosition](#mensaje-vehicleposition) | opcional | Datos sobre la posición en tiempo real de un vehículo. | +| **alert** | [Alert](#mensaje-alert) | opcional | Datos sobre las alertas en tiempo real. | ## _mensaje_ TripUpdate @@ -120,9 +120,9 @@ Ten en cuenta que la actualización puede describir un viaje que ya se ha comple | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **trip** | [TripDescriptor](#TripDescriptor) | obligatorio | El viaje al cual se aplica este mensaje. Puede haber una entidad de TripUpdate, como máximo, para cada instancia de viaje real. Si no hay ninguna, entonces no habrá información de predicciones disponible. *No* significa que el viaje se está realizando de acuerdo con la programación. | +| **trip** | [TripDescriptor](#mensaje-tripdescriptor) | obligatorio | El viaje al cual se aplica este mensaje. Puede haber una entidad de TripUpdate, como máximo, para cada instancia de viaje real. Si no hay ninguna, entonces no habrá información de predicciones disponible. *No* significa que el viaje se está realizando de acuerdo con la programación. | | **vehicle** | [VehicleDescriptor](#VehicleDescriptor) | opcional | Información adicional sobre el vehículo con el cual se está realizando este viaje. | -| **stop_time_update** | [StopTimeUpdate](#StopTimeUpdate) | repetido | Las actualizaciones de StopTimes para el viaje (futuras, como las predicciones, y, en algunos casos, pasadas, es decir, aquellas que ya ocurrieron). Las actualizaciones deben ordenarse por secuencia de parada y deben aplicarse a todas las siguientes paradas del viaje hasta la próxima especificada. | +| **stop_time_update** | [StopTimeUpdate](#mensaje-stoptimeupdate) | repetido | Las actualizaciones de StopTimes para el viaje (futuras, como las predicciones, y, en algunos casos, pasadas, es decir, aquellas que ya ocurrieron). Las actualizaciones deben ordenarse por secuencia de parada y deben aplicarse a todas las siguientes paradas del viaje hasta la próxima especificada. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Momento en el que se midió el progreso en tiempo real del vehículo. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). | ## _mensaje_ StopTimeEvent @@ -144,7 +144,7 @@ La incertidumbre se aplica de la misma forma tanto al tiempo como a la demora. L ## _mensaje_ StopTimeUpdate -La actualización en tiempo real para los eventos de llegada o de salida para una determinada parada de un viaje. Consulta el debate general de las actualizaciones de tiempos de parada en la documentación de [TripDescriptor](#TripDescriptor) y [del tipo de feed de actualizaciones de viaje](./trip-updates). +La actualización en tiempo real para los eventos de llegada o de salida para una determinada parada de un viaje. Consulta el debate general de las actualizaciones de tiempos de parada en la documentación de [TripDescriptor](#mensaje-tripdescriptor) y [del tipo de feed de actualizaciones de viaje](./trip-updates). Las actualizaciones se pueden proporcionar tanto para eventos pasados como futuros. El productor tiene permitido, aunque no está obligado, a desestimar los eventos pasados. La actualización está vinculada a una parada específica sea a través de stop_sequence o de stop_id, de manera que uno de estos campos debe definirse, necesariamente. @@ -155,9 +155,9 @@ Las actualizaciones se pueden proporcionar tanto para eventos pasados como futur |------------------------|------------|--------------------|-------------------| | **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Debe ser la misma que la de stop_times.txt en el feed GTFS correspondiente. | | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. | -| **arrival** | [StopTimeEvent](#StopTimeEvent) | opcional | -| **departure** | [StopTimeEvent](#StopTimeEvent) | opcional | -| **schedule_relationship** | [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) | opcional | La relación predeterminada es SCHEDULED. | +| **arrival** | [StopTimeEvent](#mensaje-stoptimeevent) | opcional | +| **departure** | [StopTimeEvent](#mensaje-stoptimeevent) | opcional | +| **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | opcional | La relación predeterminada es SCHEDULED. | ## _enum._ ScheduleRelationship @@ -179,9 +179,9 @@ Información de posicionamiento en tiempo real para un vehículo dado | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **trip** | [TripDescriptor](#TripDescriptor) | opcional | El viaje que está haciendo este vehículo. Puede estar vacío o parcialmente vacío si el vehículo no puede identificarse con una instancia de viaje dada. | +| **trip** | [TripDescriptor](#mensaje-tripdescriptor) | opcional | El viaje que está haciendo este vehículo. Puede estar vacío o parcialmente vacío si el vehículo no puede identificarse con una instancia de viaje dada. | | **vehicle** | [VehicleDescriptor](#VehicleDescriptor) | opcional | Información adicional sobre el vehículo que está realizando el viaje. Cada entrada debe tener un ID de vehículo **único**. | -| **position** | [Position](#Position) | opcional | Posición actual de este vehículo. | +| **position** | [Position](#mensaje-position) | opcional | Posición actual de este vehículo. | | **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El índice de la secuencia de parada de la parada actual. El significado de current_stop_sequence (es decir, la parada a la que hace referencia) está determinado por current_status. Si falta el valor en current_status, se asume IN_TRANSIT_TO. | | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Identifica la parada actual. El valor debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. | | **current_status** | [VehicleStopStatus](#VehicleStopStatus) | opcional | El estado exacto del vehículo con respecto a la parada actual. Se ignora si falta el valor en current_stop_sequence. | @@ -220,13 +220,13 @@ Una alerta que indica que existe algún tipo de incidente en la red de transport | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **active_period** | [TimeRange](#TimeRange) | repetido | Tiempo durante el cual debe mostrarse la alerta al usuario. Si falta, la alerta se mostrará durante todo el tiempo que aparezca en el feed. Si se otorgan varios intervalos, la alerta se mostrará durante todos ellos. | -| **informed_entity** | [EntitySelector](#EntitySelector) | repetido | Entidades a cuyos usuarios debemos notificar esta alerta. | -| **cause** | [Cause](#Cause) | opcional | -| **effect** | [Effect](#Effect) | opcional | -| **url** | [TranslatedString](#TranslatedString) | opcional | La URL que proporciona información adicional sobre la alerta. | -| **header_text** | [TranslatedString](#TranslatedString) | opcional | Encabezado de la alerta. Esta cadena de texto sin formato se resaltará, por ejemplo, en negrita. | -| **description_text** | [TranslatedString](#TranslatedString) | opcional | Descripción de la alerta. A esta cadena de texto sin formato se le aplicará el formato del cuerpo de la alerta (o se mostrará en una solicitud explícita de "expansión" realizada por el usuario
). La información de la descripción debe completar la información del encabezado. | +| **active_period** | [TimeRange](#mensaje-timerange) | repetido | Tiempo durante el cual debe mostrarse la alerta al usuario. Si falta, la alerta se mostrará durante todo el tiempo que aparezca en el feed. Si se otorgan varios intervalos, la alerta se mostrará durante todos ellos. | +| **informed_entity** | [EntitySelector](#mensaje-entitySelector) | repetido | Entidades a cuyos usuarios debemos notificar esta alerta. | +| **cause** | [Cause](#enum-cause) | opcional | +| **effect** | [Effect](#enum-effect) | opcional | +| **url** | [TranslatedString](#mensaje-translatedstring) | opcional | La URL que proporciona información adicional sobre la alerta. | +| **header_text** | [TranslatedString](#mensaje-translatedstring) | opcional | Encabezado de la alerta. Esta cadena de texto sin formato se resaltará, por ejemplo, en negrita. | +| **description_text** | [TranslatedString](#mensaje-translatedstring) | opcional | Descripción de la alerta. A esta cadena de texto sin formato se le aplicará el formato del cuerpo de la alerta (o se mostrará en una solicitud explícita de "expansión" realizada por el usuario
). La información de la descripción debe completar la información del encabezado. | ## _enum._ Cause @@ -304,7 +304,7 @@ Un descriptor que identifica una instancia de un viaje de GTFS o todas las insta | **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El identificador de la ruta de GTFS al que hace referencia este selector. | | **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La hora de inicio programada de esta instancia de viaje. Este campo debe proporcionarse solo si el viaje tiene frecuencia extendida en el feed GTFS. El valor debe corresponder precisamente a la hora de inicio especificada para la ruta del feed GTFS más algunos múltiplos de headway_secs. El formato del campo es el mismo que el de GTFS/frequencies.txt/start_time, es decir, 11:15:35 o 25:15:35. | | **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La fecha de inicio programada de esta instancia de viaje. Este campo debe proporcionarse para desambiguar los viajes que están tan retrasados que pueden superponerse con un viaje programado para el día siguiente. Por ejemplo, para un tren que sale a las 8:00 y a las 20:00 todos los días, y está 12 horas retrasado, habrá dos viajes distintos a la misma hora. Este campo puede proporcionarse, pero no es obligatorio para las programaciones en las cuales las superposiciones son imposibles, por ejemplo, un servicio que funciona según una programación horaria donde un vehículo que está una hora retrasado deja de considerarse relacionado a la programación. En formato AAAAMMDD. | -| **schedule_relationship** | [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) | opcional | +| **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship-1) | opcional | ## _enum._ ScheduleRelationship @@ -331,7 +331,7 @@ Información de identificación para el vehículo que realiza el viaje. | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Identificación interna del sistema para el vehículo. Debe ser **única** para cada vehículo y se usa para hacer un seguimiento del vehículo en la medida en que avanza en el sistema. Este identificador debe ser visible para el usuario final; para ello debes usar el campo **label** | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Etiqueta visible para el usuario, es decir, que se debe mostrar al pasajero para ayudarlo a identificar el vehículo correcto. | | **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La patente del vehículo. | -| **carriage_descriptor** | [CarriageDescriptor](#CarriageDescriptor) | repetido | | +| **carriage_descriptor** | [CarriageDescriptor](#mensaje-carriagedescriptor) | repetido | | ## _mensaje_ CarriageDescriptor @@ -341,12 +341,12 @@ Información de identificación para el vehículo que realiza el viaje. |------------------------|------------|--------------------|-------------------| | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | | -| **occupancy_status** | [OccupancyStatus](#OccupancyStatus) | opcional | | -| **wheelchair_accessible** | [WheelchairAccessible](#WheelchairAccessible) | opcional | | -| **toilet_facilities** | [ToiletFacilities](#ToiletFacilities) | opcional | | -| **wifi_availability** | [WifiAvailability](#WifiAvailability) | opcional | | -| **air_conditioning** | [AirConditioning](#AirConditioning) | opcional | | -| **bicycles_allowed** | [BicyclesAllowed](#BicyclesAllowed) | opcional | | +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | opcional | | +| **wheelchair_accessible** | [WheelchairAccessible](#enum-wheelchairaccessible) | opcional | | +| **toilet_facilities** | [ToiletFacilities](#enum-toiletfacilities) | opcional | | +| **wifi_availability** | [WifiAvailability](#enum-wifiavailability) | opcional | | +| **air_conditioning** | [AirConditioning](#enum-airconditioning) | opcional | | +| **bicycles_allowed** | [BicyclesAllowed](#enum-bicyclesallowed) | opcional | | ## _enum._ WheelchairAccessible @@ -411,7 +411,7 @@ Un selector para una entidad en un feed GTFS. Los valores de los campos deben co | **agency_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | | **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | | **route_type** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | -| **trip** | [TripDescriptor](#TripDescriptor) | opcional | +| **trip** | [TripDescriptor](#mensaje-tripdescriptor) | opcional | | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | ## _mensaje_ TranslatedString @@ -422,7 +422,7 @@ Un mensaje internacionalizado que contiene versiones por idioma de un fragmento | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **translation** | [Translation](#Translation) | repetido | Se debe proporcionar al menos una traducción. | +| **translation** | [Translation](#mensaje-translation) | repetido | Se debe proporcionar al menos una traducción. | ## _mensaje_ Translation From c840c759e27819496a915ed28a797a695c6d7a01 Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Wed, 12 Jul 2017 09:09:42 +1000 Subject: [PATCH 07/10] cleanup. --- transit/AUTHORS | 9 - transit/CONTRIBUTING.md | 25 - transit/CONTRIBUTORS | 16 - transit/LICENSE | 201 ------ transit/README.md | 4 - transit/gtfs-realtime/CHANGES.md | 82 --- transit/gtfs-realtime/README.md | 7 - .../gtfs-realtime/proto/gtfs-realtime.proto | 633 ------------------ transit/gtfs-realtime/spec/en/README.md | 49 -- .../gtfs-realtime/spec/en/examples/README.md | 4 - .../spec/en/examples/alerts.asciipb | 72 -- .../en/examples/trip-updates-full.asciipb | 79 --- .../gtfs-realtime/spec/en/feed-entities.md | 54 -- transit/gtfs-realtime/spec/en/reference.md | 380 ----------- .../gtfs-realtime/spec/en/service-alerts.md | 56 -- transit/gtfs-realtime/spec/en/trip-updates.md | 100 --- .../spec/en/vehicle-positions.md | 59 -- transit/gtfs-realtime/spec/es/README.md | 50 -- .../gtfs-realtime/spec/es/examples/README.md | 4 - .../spec/es/examples/alerts.asciipb | 72 -- .../es/examples/trip-updates-full.asciipb | 79 --- transit/gtfs-realtime/spec/es/feed-types.md | 36 - .../gtfs-realtime/spec/es/gtfs-realtime.proto | 569 ---------------- transit/gtfs-realtime/spec/es/reference.md | 361 ---------- .../gtfs-realtime/spec/es/service-alerts.md | 56 -- transit/gtfs-realtime/spec/es/trip-updates.md | 56 -- .../spec/es/vehicle-positions.md | 45 -- transit/gtfs/CHANGES.md | 199 ------ transit/gtfs/README.md | 5 - transit/gtfs/spec/en/README.md | 37 - transit/gtfs/spec/en/community.md | 25 - transit/gtfs/spec/en/examples/README.md | 130 ---- .../gtfs/spec/en/examples/sample-feed-1.zip | Bin 3217 -> 0 bytes .../spec/en/examples/sample-feed-1/agency.txt | 2 - .../en/examples/sample-feed-1/calendar.txt | 3 - .../examples/sample-feed-1/calendar_dates.txt | 2 - .../sample-feed-1/fare_attributes.txt | 3 - .../en/examples/sample-feed-1/fare_rules.txt | 5 - .../en/examples/sample-feed-1/frequencies.txt | 12 - .../spec/en/examples/sample-feed-1/routes.txt | 6 - .../spec/en/examples/sample-feed-1/shapes.txt | 1 - .../en/examples/sample-feed-1/stop_times.txt | 29 - .../spec/en/examples/sample-feed-1/stops.txt | 10 - .../spec/en/examples/sample-feed-1/trips.txt | 12 - transit/gtfs/spec/en/reference.md | 429 ------------ transit/gtfs/spec/en/style-guide.md | 33 - transit/gtfs/spec/en/tools.md | 8 - 47 files changed, 4109 deletions(-) delete mode 100644 transit/AUTHORS delete mode 100644 transit/CONTRIBUTING.md delete mode 100644 transit/CONTRIBUTORS delete mode 100644 transit/LICENSE delete mode 100644 transit/README.md delete mode 100644 transit/gtfs-realtime/CHANGES.md delete mode 100644 transit/gtfs-realtime/README.md delete mode 100644 transit/gtfs-realtime/proto/gtfs-realtime.proto delete mode 100644 transit/gtfs-realtime/spec/en/README.md delete mode 100644 transit/gtfs-realtime/spec/en/examples/README.md delete mode 100644 transit/gtfs-realtime/spec/en/examples/alerts.asciipb delete mode 100644 transit/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb delete mode 100644 transit/gtfs-realtime/spec/en/feed-entities.md delete mode 100644 transit/gtfs-realtime/spec/en/reference.md delete mode 100644 transit/gtfs-realtime/spec/en/service-alerts.md delete mode 100644 transit/gtfs-realtime/spec/en/trip-updates.md delete mode 100644 transit/gtfs-realtime/spec/en/vehicle-positions.md delete mode 100644 transit/gtfs-realtime/spec/es/README.md delete mode 100644 transit/gtfs-realtime/spec/es/examples/README.md delete mode 100644 transit/gtfs-realtime/spec/es/examples/alerts.asciipb delete mode 100644 transit/gtfs-realtime/spec/es/examples/trip-updates-full.asciipb delete mode 100644 transit/gtfs-realtime/spec/es/feed-types.md delete mode 100644 transit/gtfs-realtime/spec/es/gtfs-realtime.proto delete mode 100644 transit/gtfs-realtime/spec/es/reference.md delete mode 100644 transit/gtfs-realtime/spec/es/service-alerts.md delete mode 100644 transit/gtfs-realtime/spec/es/trip-updates.md delete mode 100644 transit/gtfs-realtime/spec/es/vehicle-positions.md delete mode 100644 transit/gtfs/CHANGES.md delete mode 100644 transit/gtfs/README.md delete mode 100644 transit/gtfs/spec/en/README.md delete mode 100644 transit/gtfs/spec/en/community.md delete mode 100644 transit/gtfs/spec/en/examples/README.md delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1.zip delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/agency.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/calendar.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/calendar_dates.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/fare_attributes.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/fare_rules.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/frequencies.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/routes.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/shapes.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/stop_times.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/stops.txt delete mode 100644 transit/gtfs/spec/en/examples/sample-feed-1/trips.txt delete mode 100644 transit/gtfs/spec/en/reference.md delete mode 100644 transit/gtfs/spec/en/style-guide.md delete mode 100644 transit/gtfs/spec/en/tools.md diff --git a/transit/AUTHORS b/transit/AUTHORS deleted file mode 100644 index d910fd6cf..000000000 --- a/transit/AUTHORS +++ /dev/null @@ -1,9 +0,0 @@ -# This is the official list of GTFS Specifications authors for copyright purposes. -# This file is distinct from the CONTRIBUTORS files. -# See the latter for an explanation. - -# Names should be added to this file as: -# Name or Organization -# The email address is not required for organizations. - -Google Inc. diff --git a/transit/CONTRIBUTING.md b/transit/CONTRIBUTING.md deleted file mode 100644 index 21e4c711b..000000000 --- a/transit/CONTRIBUTING.md +++ /dev/null @@ -1,25 +0,0 @@ -Want to contribute? Great! First, read this page (including the small print at the end). - -### Before you contribute -Before we can use your code, you must sign the -[Google Individual Contributor License Agreement](https://cla.developers.google.com/about/google-individual) -(CLA), which you can do online. The CLA is necessary mainly because you own the -copyright to your changes, even after your contribution becomes part of our -codebase, so we need your permission to use and distribute your code. We also -need to be sure of various other things—for instance that you'll tell us if you -know that your code infringes on other people's patents. You don't have to sign -the CLA until after you've submitted your code for review and a member has -approved it, but you must do it before we can put your code into our codebase. -Before you start working on a larger contribution, you should get in touch with -us first through the issue tracker with your idea so that we can help out and -possibly guide you. Coordinating up front makes it much easier to avoid -frustration later on. - -### Code reviews -All submissions, including submissions by project members, require review. We -use Github pull requests for this purpose. - -### The small print -Contributions made by corporations are covered by a different agreement than -the one above, the -[Software Grant and Corporate Contributor License Agreement](https://cla.developers.google.com/about/google-corporate). diff --git a/transit/CONTRIBUTORS b/transit/CONTRIBUTORS deleted file mode 100644 index 356d7718d..000000000 --- a/transit/CONTRIBUTORS +++ /dev/null @@ -1,16 +0,0 @@ -# People who have agreed to one of the CLAs and can contribute patches. -# The AUTHORS file lists the copyright holders; this file -# lists people. For example, Google employees are listed here -# but not in AUTHORS, because Google holds the copyright. -# -# https://developers.google.com/open-source/cla/individual -# https://developers.google.com/open-source/cla/corporate -# -# Names should be added to this file as: -# Name -Brian Ferris -Chiara Micca -Eric Andresen -Ivan Egorov -Ivan Maksimenko -Sean Barbeau diff --git a/transit/LICENSE b/transit/LICENSE deleted file mode 100644 index 094d8e444..000000000 --- a/transit/LICENSE +++ /dev/null @@ -1,201 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/transit/README.md b/transit/README.md deleted file mode 100644 index 52fd7cb32..000000000 --- a/transit/README.md +++ /dev/null @@ -1,4 +0,0 @@ -The repository contains specification and tools to manipulate General Transit -Feed Specification (GTFS) and GTFS Realtime. - -Please visit https://developers.google.com/transit/ for information. diff --git a/transit/gtfs-realtime/CHANGES.md b/transit/gtfs-realtime/CHANGES.md deleted file mode 100644 index 39d7b63ca..000000000 --- a/transit/gtfs-realtime/CHANGES.md +++ /dev/null @@ -1,82 +0,0 @@ -The GTFS Realtime Specification is not set in stone. Instead, it is an open specification developed and maintained by the community of transit agencies, developers, and other stakeholders who use GTFS Realtime. It is expected that this community of producers and consumers of GTFS Realtime data will have proposals for extending the spec to enable new capabilities. To help manage that process, the following procedures and guidelines have been established. - -### Specification amendment process -The official specification, reference and documentation are written in English. If a translation to a different language differs from the English original, the latter takes precedence. All communication is performed 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 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. -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. -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. - 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. -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. - 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. -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. - - 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 -In order to preserve the original vision of GTFS Realtime, a number of guiding principles have been established to take into consideration when extending the spec: - -#### Feeds should be efficient to produce and consume in realtime. -Realtime information is a continuous, dynamic stream of data that necessarily requires efficient processing. We chose Protocol Buffers as the basis for the specification because they offer a good trade-off in terms of ease of use for developers and in terms of efficiency for transmitting data. Unlike GTFS, we do not imagine many agencies will be editing GTFS Realtime feeds by hand. The choice of Protocol Buffers reflects the conclusion that most GTFS Realtime feeds will be produced and consumed programmatically. - -#### The spec is about passenger information. -Like GTFS before it, GTFS Realtime is primarily concerned with passenger information. That is, the spec should include information that can help power tools for riders, first and foremost. There is potentially a large amount of operations-oriented information that transit agencies might want to transmit internally between systems. GTFS Realtime is not intended for that purpose and there are potentially other operations-oriented data-standards that may be more appropriate. - -#### Changes to the spec should be backwards-compatible. -When adding features to the specification, we want to avoid making changes that will make existing feeds invalid. We don't want to create more work for existing feed publishers until they want to add capabilities to their feeds. Also, whenever possible, we want existing parsers to be able to continue to read the older parts of newer feeds. The conventions for extending Protocol Buffers will enforce backwards-compatibility to a certain extent. However, we wish to avoid semantic changes to existing fields that might break backwards-compatibility as well. - -#### Speculative features are discouraged. -Every new feature adds complexity to creating and reading of feeds. Therefore, we want to take care to only add features that we know to be useful. Ideally, any proposal will have been tested by generating data for a real transit system that uses the new feature and writing software to read and display it. - -We will make use of extensions, described in the following section, to support new features. GTFS Realtime producers and consumers can first test a new feature in the extension space. When the feature is ready for official adoption, we will add the feature to the official GTFS Realtime proto definition itself. - -### Extensions -To facilitate the testing of new features and to allow developers to add extra information to a GTFS Realtime feed, we will take advantage of the [Extensions feature of Protocol Buffers](https://developers.google.com/protocol-buffers/docs/proto#extensions). Extensions allow us to define a namespace in a Protocol Buffer message where third-party developers can define additional fields without the need to modify the original proto definition. - -When a developer is interested in extending the GTFS Realtime Specification, they should contact the [GTFS Realtime mailing list](https://groups.google.com/forum/#!forum/gtfs-realtime) and we will assign them the next available extension id, picked incrementally from a list of numbers starting at 1000 and going up and documented in the Extension Registry section found below. - -These assigned extension ids corresponds to the tag ids available in the "extension" namespace for each GTFS Realtime message definition. Now that the developer has an assigned extension id, they will use that id when extending any and all GTFS Realtime messages. Even if the developer only plans to extend a single message, the assigned extension id will be reserved for ALL messages. - -For a developer extending the spec, instead of adding a single field like a "string" or "int32" with their extension id, the preferred model is to define a new message like "MyTripDescriptorExtension", extend the underlying GTFS Realtime message with your new message, and then put all your new fields in there. This has the nice property that you can manage fields within your extension message however you want, without needing to reserve a new extension id from the master list. - -``` -message MyTripDescriptorExtension { - optional string some_string = 1; - optional bool some_bool = 2; - ... -} -extend transit_realtime.TripDescriptor { - optional MyTripDescriptorExtension my_trip_descriptor = YOUR_EXTENSION_ID; -} -``` - -### Extension Registry - -|Extension ID|Developer|Contact|Details| -|------------|---------|-------|-------| -|1000|OneBusAway|[onebusaway-developers](http://groups.google.com/group/onebusaway-developers)|https://github.com/OneBusAway/onebusaway/wiki/GTFS-Realtime-Resources| -|1001|New York City MTA|[mtadeveloperresources](http://groups.google.com/group/mtadeveloperresources)|http://mta.info/developers/| -|1002|Google|[transit-realtime-partner-support@google.com](mailto:transit-realtime-partner-support@google.com)|Google Maps Live Transit Updates| -|1003|OVapi|gtfs-rt at ovapi.nl|http://gtfs.ovapi.nl| -|1004|Metra|[William Ashbaugh ](mailto:w.l.ashbaugh@gmail.com)| -|1005|Metro-North Railroad|[John Larsen](mailto:mnrappdev@mnr.org)| -|1006|realCity|[David Varga](mailto:transit@realcity.io)|http://realcity.io| diff --git a/transit/gtfs-realtime/README.md b/transit/gtfs-realtime/README.md deleted file mode 100644 index 5d1bd01d1..000000000 --- a/transit/gtfs-realtime/README.md +++ /dev/null @@ -1,7 +0,0 @@ -This directory contains GTFS Realtime Specification and documentation. - -### Quick links -- [GTFS Realtime protocol buffer definition](proto/gtfs-realtime.proto) -- [Documentation](spec/en) -- [How to change the specification?](CHANGES.md) - diff --git a/transit/gtfs-realtime/proto/gtfs-realtime.proto b/transit/gtfs-realtime/proto/gtfs-realtime.proto deleted file mode 100644 index 5766bc576..000000000 --- a/transit/gtfs-realtime/proto/gtfs-realtime.proto +++ /dev/null @@ -1,633 +0,0 @@ -// Copyright 2015 The GTFS Specifications Authors. -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -// Protocol definition file for GTFS Realtime. -// -// GTFS Realtime 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. -// -// This protocol is published at: -// https://github.com/google/transit/tree/master/gtfs-realtime - -syntax = "proto2"; -option java_package = "com.google.transit.realtime"; -package transit_realtime; - -// The contents of a feed message. -// A feed is a continuous stream of feed messages. Each message in the stream is -// obtained as a response to an appropriate HTTP GET request. -// A realtime feed is always defined with relation to an existing GTFS feed. -// All the entity ids are resolved with respect to the GTFS feed. -message FeedMessage { - // Metadata about this feed and feed message. - required FeedHeader header = 1; - - // Contents of the feed. - repeated FeedEntity entity = 2; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// Metadata about a feed, included in feed messages. -message FeedHeader { - // Version of the feed specification. - // The current version is 1.0. - required string gtfs_realtime_version = 1; - - // Determines whether the current fetch is incremental. Currently, - // DIFFERENTIAL mode is unsupported and behavior is unspecified for feeds - // that use this mode. There are discussions on the GTFS Realtime mailing - // list around fully specifying the behavior of DIFFERENTIAL mode and the - // documentation will be updated when those discussions are finalized. - enum Incrementality { - FULL_DATASET = 0; - DIFFERENTIAL = 1; - } - optional Incrementality incrementality = 2 [default = FULL_DATASET]; - - // This timestamp identifies the moment when the content of this feed has been - // created (in server time). In POSIX time (i.e., number of seconds since - // January 1st 1970 00:00:00 UTC). - optional uint64 timestamp = 3; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// A definition (or update) of an entity in the transit feed. -message FeedEntity { - // The ids are used only to provide incrementality support. The id should be - // unique within a FeedMessage. Consequent FeedMessages may contain - // FeedEntities with the same id. In case of a DIFFERENTIAL update the new - // FeedEntity with some id will replace the old FeedEntity with the same id - // (or delete it - see is_deleted below). - // The actual GTFS entities (e.g. stations, routes, trips) referenced by the - // feed must be specified by explicit selectors (see EntitySelector below for - // more info). - required string id = 1; - - // Whether this entity is to be deleted. Relevant only for incremental - // fetches. - optional bool is_deleted = 2 [default = false]; - - // Data about the entity itself. Exactly one of the following fields must be - // present (unless the entity is being deleted). - optional TripUpdate trip_update = 3; - optional VehiclePosition vehicle = 4; - optional Alert alert = 5; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// -// Entities used in the feed. -// - -// Realtime update of the progress of a vehicle along a trip. -// Depending on the value of ScheduleRelationship, a TripUpdate can specify: -// - A trip that proceeds along the schedule. -// - A trip that proceeds along a route but has no fixed schedule. -// - A trip that have been added or removed with regard to schedule. -// -// The updates can be for future, predicted arrival/departure events, or for -// past events that already occurred. -// Normally, updates should get more precise and more certain (see -// uncertainty below) as the events gets closer to current time. -// Even if that is not possible, the information for past events should be -// precise and certain. In particular, if an update points to time in the past -// but its update's uncertainty is not 0, the client should conclude that the -// update is a (wrong) prediction and that the trip has not completed yet. -// -// Note that the update can describe a trip that is already completed. -// To this end, it is enough to provide an update for the last stop of the trip. -// If the time of that is in the past, the client will conclude from that that -// the whole trip is in the past (it is possible, although inconsequential, to -// also provide updates for preceding stops). -// This option is most relevant for a trip that has completed ahead of schedule, -// but according to the schedule, the trip is still proceeding at the current -// time. Removing the updates for this trip could make the client assume -// that the trip is still proceeding. -// Note that the feed provider is allowed, but not required, to purge past -// updates - this is one case where this would be practically useful. -message TripUpdate { - // The Trip that this message applies to. There can be at most one - // TripUpdate entity for each actual trip instance. - // If there is none, that means there is no prediction information available. - // It does *not* mean that the trip is progressing according to schedule. - required TripDescriptor trip = 1; - - // Additional information on the vehicle that is serving this trip. - optional VehicleDescriptor vehicle = 3; - - // Timing information for a single predicted event (either arrival or - // departure). - // Timing consists of delay and/or estimated time, and uncertainty. - // - delay should be used when the prediction is given relative to some - // existing schedule in GTFS. - // - time should be given whether there is a predicted schedule or not. If - // both time and delay are specified, time will take precedence - // (although normally, time, if given for a scheduled trip, should be - // equal to scheduled time in GTFS + delay). - // - // Uncertainty applies equally to both time and delay. - // The uncertainty roughly specifies the expected error in true delay (but - // note, we don't yet define its precise statistical meaning). It's possible - // for the uncertainty to be 0, for example for trains that are driven under - // computer timing control. - message StopTimeEvent { - // Delay (in seconds) can be positive (meaning that the vehicle is late) or - // negative (meaning that the vehicle is ahead of schedule). Delay of 0 - // means that the vehicle is exactly on time. - optional int32 delay = 1; - - // Event as absolute time. - // In Unix time (i.e., number of seconds since January 1st 1970 00:00:00 - // UTC). - optional int64 time = 2; - - // If uncertainty is omitted, it is interpreted as unknown. - // If the prediction is unknown or too uncertain, the delay (or time) field - // should be empty. In such case, the uncertainty field is ignored. - // To specify a completely certain prediction, set its uncertainty to 0. - optional int32 uncertainty = 3; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features - // and modifications to the spec. - extensions 1000 to 1999; - } - - // Realtime update for arrival and/or departure events for a given stop on a - // trip. Updates can be supplied for both past and future events. - // The producer is allowed, although not required, to drop past events. - message StopTimeUpdate { - // The update is linked to a specific stop either through stop_sequence or - // stop_id, so one of the fields below must necessarily be set. - // See the documentation in TripDescriptor for more information. - - // Must be the same as in stop_times.txt in the corresponding GTFS feed. - optional uint32 stop_sequence = 1; - // Must be the same as in stops.txt in the corresponding GTFS feed. - optional string stop_id = 4; - - optional StopTimeEvent arrival = 2; - optional StopTimeEvent departure = 3; - - // The relation between this StopTime and the static schedule. - enum ScheduleRelationship { - // The vehicle is proceeding in accordance with its static schedule of - // stops, although not necessarily according to the times of the schedule. - // At least one of arrival and departure must be provided. If the schedule - // for this stop contains both arrival and departure times then so must - // this update. - SCHEDULED = 0; - - // The stop is skipped, i.e., the vehicle will not stop at this stop. - // Arrival and departure are optional. - SKIPPED = 1; - - // No data is given for this stop. The main intention for this value is to - // give the predictions only for part of a trip, i.e., if the last update - // for a trip has a NO_DATA specifier, then StopTimes for the rest of the - // stops in the trip are considered to be unspecified as well. - // Neither arrival nor departure should be supplied. - NO_DATA = 2; - } - optional ScheduleRelationship schedule_relationship = 5 - [default = SCHEDULED]; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features - // and modifications to the spec. - extensions 1000 to 1999; - } - - // Updates to StopTimes for the trip (both future, i.e., predictions, and in - // some cases, past ones, i.e., those that already happened). - // The updates must be sorted by stop_sequence, and apply for all the - // following stops of the trip up to the next specified one. - // - // Example 1: - // For a trip with 20 stops, a StopTimeUpdate with arrival delay and departure - // delay of 0 for stop_sequence of the current stop means that the trip is - // exactly on time. - // - // Example 2: - // For the same trip instance, 3 StopTimeUpdates are provided: - // - delay of 5 min for stop_sequence 3 - // - delay of 1 min for stop_sequence 8 - // - delay of unspecified duration for stop_sequence 10 - // This will be interpreted as: - // - stop_sequences 3,4,5,6,7 have delay of 5 min. - // - stop_sequences 8,9 have delay of 1 min. - // - stop_sequences 10,... have unknown delay. - repeated StopTimeUpdate stop_time_update = 2; - - // Moment at which the vehicle's real-time progress was measured. In POSIX - // time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC). - optional uint64 timestamp = 4; - - // The current schedule deviation for the trip. Delay should only be - // specified when the prediction is given relative to some existing schedule - // in GTFS. - // - // Delay (in seconds) can be positive (meaning that the vehicle is late) or - // negative (meaning that the vehicle is ahead of schedule). Delay of 0 - // means that the vehicle is exactly on time. - // - // Delay information in StopTimeUpdates take precedent of trip-level delay - // information, such that trip-level delay is only propagated until the next - // stop along the trip with a StopTimeUpdate delay value specified. - // - // Feed providers are strongly encouraged to provide a TripUpdate.timestamp - // value indicating when the delay value was last updated, in order to - // evaluate the freshness of the data. - // - // NOTE: This field is still experimental, and subject to change. It may be - // formally adopted in the future. - optional int32 delay = 5; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// Realtime positioning information for a given vehicle. -message VehiclePosition { - // The Trip that this vehicle is serving. - // Can be empty or partial if the vehicle can not be identified with a given - // trip instance. - optional TripDescriptor trip = 1; - - // Additional information on the vehicle that is serving this trip. - optional VehicleDescriptor vehicle = 8; - - // Current position of this vehicle. - optional Position position = 2; - - // The stop sequence index of the current stop. The meaning of - // current_stop_sequence (i.e., the stop that it refers to) is determined by - // current_status. - // If current_status is missing IN_TRANSIT_TO is assumed. - optional uint32 current_stop_sequence = 3; - // Identifies the current stop. The value must be the same as in stops.txt in - // the corresponding GTFS feed. - optional string stop_id = 7; - - enum VehicleStopStatus { - // The vehicle is just about to arrive at the stop (on a stop - // display, the vehicle symbol typically flashes). - INCOMING_AT = 0; - - // The vehicle is standing at the stop. - STOPPED_AT = 1; - - // The vehicle has departed and is in transit to the next stop. - IN_TRANSIT_TO = 2; - } - // The exact status of the vehicle with respect to the current stop. - // Ignored if current_stop_sequence is missing. - optional VehicleStopStatus current_status = 4 [default = IN_TRANSIT_TO]; - - // Moment at which the vehicle's position was measured. In POSIX time - // (i.e., number of seconds since January 1st 1970 00:00:00 UTC). - optional uint64 timestamp = 5; - - // Congestion level that is affecting this vehicle. - enum CongestionLevel { - UNKNOWN_CONGESTION_LEVEL = 0; - RUNNING_SMOOTHLY = 1; - STOP_AND_GO = 2; - CONGESTION = 3; - SEVERE_CONGESTION = 4; // People leaving their cars. - } - optional CongestionLevel congestion_level = 6; - - // The degree of passenger occupancy of the vehicle. This field is still - // experimental, and subject to change. It may be formally adopted in the - // future. - enum OccupancyStatus { - // The vehicle is considered empty by most measures, and has few or no - // passengers onboard, but is still accepting passengers. - EMPTY = 0; - - // The vehicle has a relatively large percentage of seats available. - // What percentage of free seats out of the total seats available is to be - // considered large enough to fall into this category is determined at the - // discretion of the producer. - MANY_SEATS_AVAILABLE = 1; - - // The vehicle has a relatively small percentage of seats available. - // What percentage of free seats out of the total seats available is to be - // considered small enough to fall into this category is determined at the - // discretion of the feed producer. - FEW_SEATS_AVAILABLE = 2; - - // The vehicle can currently accommodate only standing passengers. - STANDING_ROOM_ONLY = 3; - - // The vehicle can currently accommodate only standing passengers - // and has limited space for them. - CRUSHED_STANDING_ROOM_ONLY = 4; - - // The vehicle is considered full by most measures, but may still be - // allowing passengers to board. - FULL = 5; - - // The vehicle is not accepting additional passengers. - NOT_ACCEPTING_PASSENGERS = 6; - - } - optional OccupancyStatus occupancy_status = 9; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// An alert, indicating some sort of incident in the public transit network. -message Alert { - // Time when the alert should be shown to the user. If missing, the - // alert will be shown as long as it appears in the feed. - // If multiple ranges are given, the alert will be shown during all of them. - repeated TimeRange active_period = 1; - - // Entities whose users we should notify of this alert. - repeated EntitySelector informed_entity = 5; - - // Cause of this alert. - enum Cause { - UNKNOWN_CAUSE = 1; - OTHER_CAUSE = 2; // Not machine-representable. - TECHNICAL_PROBLEM = 3; - STRIKE = 4; // Public transit agency employees stopped working. - DEMONSTRATION = 5; // People are blocking the streets. - ACCIDENT = 6; - HOLIDAY = 7; - WEATHER = 8; - MAINTENANCE = 9; - CONSTRUCTION = 10; - POLICE_ACTIVITY = 11; - MEDICAL_EMERGENCY = 12; - } - optional Cause cause = 6 [default = UNKNOWN_CAUSE]; - - // What is the effect of this problem on the affected entity. - enum Effect { - NO_SERVICE = 1; - REDUCED_SERVICE = 2; - - // We don't care about INsignificant delays: they are hard to detect, have - // little impact on the user, and would clutter the results as they are too - // frequent. - SIGNIFICANT_DELAYS = 3; - - DETOUR = 4; - ADDITIONAL_SERVICE = 5; - MODIFIED_SERVICE = 6; - OTHER_EFFECT = 7; - UNKNOWN_EFFECT = 8; - STOP_MOVED = 9; - } - optional Effect effect = 7 [default = UNKNOWN_EFFECT]; - - // The URL which provides additional information about the alert. - optional TranslatedString url = 8; - - // Alert header. Contains a short summary of the alert text as plain-text. - optional TranslatedString header_text = 10; - - // 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; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features - // and modifications to the spec. - extensions 1000 to 1999; -} - -// -// Low level data structures used above. -// - -// A time interval. The interval is considered active at time 't' if 't' is -// greater than or equal to the start time and less than the end time. -message TimeRange { - // Start time, in POSIX time (i.e., number of seconds since January 1st 1970 - // 00:00:00 UTC). - // If missing, the interval starts at minus infinity. - optional uint64 start = 1; - - // End time, in POSIX time (i.e., number of seconds since January 1st 1970 - // 00:00:00 UTC). - // If missing, the interval ends at plus infinity. - optional uint64 end = 2; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// A position. -message Position { - // Degrees North, in the WGS-84 coordinate system. - required float latitude = 1; - - // Degrees East, in the WGS-84 coordinate system. - required float longitude = 2; - - // Bearing, in degrees, clockwise from North, i.e., 0 is North and 90 is East. - // This can be the compass bearing, or the direction towards the next stop - // or intermediate location. - // This should not be direction deduced from the sequence of previous - // positions, which can be computed from previous data. - optional float bearing = 3; - - // Odometer value, in meters. - optional double odometer = 4; - // Momentary speed measured by the vehicle, in meters per second. - optional float speed = 5; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// A descriptor that identifies an instance of a GTFS trip, or all instances of -// a trip along a route. -// - To specify a single trip instance, the trip_id (and if necessary, -// start_time) is set. If route_id is also set, then it should be same as one -// that the given trip corresponds to. -// - To specify all the trips along a given route, only the route_id should be -// set. Note that if the trip_id is not known, then stop sequence ids in -// TripUpdate are not sufficient, and stop_ids must be provided as well. In -// addition, absolute arrival/departure times must be provided. -message TripDescriptor { - // The trip_id from the GTFS feed that this selector refers to. - // For non frequency-based trips, this field is enough to uniquely identify - // the trip. For frequency-based trip, start_time and start_date might also be - // necessary. - optional string trip_id = 1; - - // The route_id from the GTFS that this selector refers to. - optional string route_id = 5; - - // The direction_id from the GTFS feed trips.txt file, indicating the - // direction of travel for trips this selector refers to. This field is - // still experimental, and subject to change. It may be formally adopted in - // the future. - optional uint32 direction_id = 6; - - // The initially scheduled start time of this trip instance. - // When the trip_id corresponds to a non-frequency-based trip, this field - // should either be omitted or be equal to the value in the GTFS feed. When - // the trip_id correponds to a frequency-based trip, the start_time must be - // specified for trip updates and vehicle positions. If the trip corresponds - // to exact_times=1 GTFS record, then start_time must be some multiple - // (including zero) of headway_secs later than frequencies.txt start_time for - // the corresponding time period. If the trip corresponds to exact_times=0, - // then its start_time may be arbitrary, and is initially expected to be the - // first departure of the trip. Once established, the start_time of this - // frequency-based trip should be considered immutable, even if the first - // departure time changes -- that time change may instead be reflected in a - // StopTimeUpdate. - // Format and semantics of the field is same as that of - // GTFS/frequencies.txt/start_time, e.g., 11:15:35 or 25:15:35. - optional string start_time = 2; - // The scheduled start date of this trip instance. - // Must be provided to disambiguate trips that are so late as to collide with - // a scheduled trip on a next day. For example, for a train that departs 8:00 - // and 20:00 every day, and is 12 hours late, there would be two distinct - // trips on the same time. - // This field can be provided but is not mandatory for schedules in which such - // collisions are impossible - for example, a service running on hourly - // schedule where a vehicle that is one hour late is not considered to be - // related to schedule anymore. - // In YYYYMMDD format. - optional string start_date = 3; - - // The relation between this trip and the static schedule. If a trip is done - // in accordance with temporary schedule, not reflected in GTFS, then it - // shouldn't be marked as SCHEDULED, but likely as ADDED. - enum ScheduleRelationship { - // Trip that is running in accordance with its GTFS schedule, or is close - // enough to the scheduled trip to be associated with it. - SCHEDULED = 0; - - // An extra trip that was added in addition to a running schedule, for - // example, to replace a broken vehicle or to respond to sudden passenger - // load. - ADDED = 1; - - // A trip that is running with no schedule associated to it, for example, if - // there is no schedule at all. - UNSCHEDULED = 2; - - // A trip that existed in the schedule but was removed. - CANCELED = 3; - } - optional ScheduleRelationship schedule_relationship = 4; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// Identification information for the vehicle performing the trip. -message VehicleDescriptor { - // Internal system identification of the vehicle. Should be unique per - // vehicle, and can be used for tracking the vehicle as it proceeds through - // the system. - optional string id = 1; - - // User visible label, i.e., something that must be shown to the passenger to - // help identify the correct vehicle. - optional string label = 2; - - // The license plate of the vehicle. - optional string license_plate = 3; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// A selector for an entity in a GTFS feed. -message EntitySelector { - // The values of the fields should correspond to the appropriate fields in the - // GTFS feed. - // At least one specifier must be given. If several are given, then the - // matching has to apply to all the given specifiers. - optional string agency_id = 1; - optional string route_id = 2; - // corresponds to route_type in GTFS. - optional int32 route_type = 3; - optional TripDescriptor trip = 4; - optional string stop_id = 5; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} - -// An internationalized message containing per-language versions of a snippet of -// text or a URL. -// One of the strings from a message will be picked up. The resolution proceeds -// as follows: -// 1. If the UI language matches the language code of a translation, -// the first matching translation is picked. -// 2. If a default UI language (e.g., English) matches the language code of a -// translation, the first matching translation is picked. -// 3. If some translation has an unspecified language code, that translation is -// picked. -message TranslatedString { - message Translation { - // A UTF-8 string containing the message. - required string text = 1; - // BCP-47 language code. Can be omitted if the language is unknown or if - // no i18n is done at all for the feed. At most one translation is - // allowed to have an unspecified language tag. - optional string language = 2; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; - } - // At least one translation must be provided. - repeated Translation translation = 1; - - // The extensions namespace allows 3rd-party developers to extend the - // GTFS Realtime Specification in order to add and evaluate new features and - // modifications to the spec. - extensions 1000 to 1999; -} diff --git a/transit/gtfs-realtime/spec/en/README.md b/transit/gtfs-realtime/spec/en/README.md deleted file mode 100644 index dedc70df6..000000000 --- a/transit/gtfs-realtime/spec/en/README.md +++ /dev/null @@ -1,49 +0,0 @@ -GTFS Realtime is a feed specification that allows public transportation agencies to provide realtime updates about their fleet to application developers. It is an extension to [GTFS](https://developers.google.com/transit/gtfs/reference) (General Transit Feed Specification), an open data format for public transportation schedules and associated geographic information. GTFS Realtime was designed around ease of implementation, good GTFS interoperability and a focus on passenger information. - -The specification was designed through a partnership of the initial [Live Transit Updates](https://developers.google.com/transit/google-transit#LiveTransitUpdates) partner agencies, a number of transit developers and Google. The specification is published under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html). - -## How do I start? - -1. Continue reading the overview below. -2. Decide which [feed entities](feed-entities.md) you will be providing. -3. Take a look at [example feeds](examples/). -4. Create your own feeds using the [reference](reference.md). -5. Publish your feed. - -## Overview of GTFS Realtime feeds - -The specification currently supports the following types of information: - -* **Trip updates** - delays, cancellations, changed routes -* **Service alerts** - stop moved, unforeseen events affecting a station, route or the entire network -* **Vehicle positions** - information about the vehicles including location and congestion level - -A feed may, although not required to, combine entities of different types. Feeds are served via HTTP and updated frequently. The file itself is a regular binary file, so any type of webserver can host and serve the file (other transfer protocols might be used as well). Alternatively, web application servers could also be used which as a response to a valid HTTP GET request will return the feed. There are no constraints on how frequently nor on the exact method of how the feed should be updated or retrieved. - -Because GTFS Realtime allows you to present the _actual_ status of your fleet, the feed needs to be updated regularly - preferably whenever new data comes in from your Automatic Vehicle Location system. - -[More about feed entities...](feed-entities.md) - -## Data format - -The GTFS Realtime data exchange format is based on [Protocol Buffers](https://developers.google.com/protocol-buffers/) - -Protocol buffers are a language- and platform-neutral mechanism for serializing structured data (think XML, but smaller, faster, and simpler). The data structure is defined in a [gtfs-realtime.proto](../../proto/gtfs-realtime.proto) file, which then is used to generate source code to easily read and write your structured data from and to a variety of data streams, using a variety of languages – e.g. Java, C++ or Python. - -[More about Protocol Buffers...](https://developers.google.com/protocol-buffers/). - -## Data structure - -The hierarchy of elements and their type definitions are specified in the [gtfs-realtime.proto](../../proto/gtfs-realtime.proto) file. - -This text file is used to generate the necessary libraries in your choice of programming language. These libraries provide the classes and functions needed for generating valid GTFS Realtime feeds. The libraries not only make feed creation easier but also ensure that only valid feeds are produced. - -[More about the data structure...](reference.md) - -## Getting Help - -To participate in discussions around GTFS Realtime and suggest changes and additions to the specification, join the [GTFS Realtime mailing list](http://groups.google.com/group/gtfs-realtime). - -## Google Maps and Live Transit Updates - -One of the possible applications that uses GTFS Realtime is [Live Transit Updates](https://developers.google.com/transit/google-transit#LiveTransitUpdates), a feature within Google Maps that provides users with realtime transit information. If you are working for a public transportation agency that is interested in providing realtime updates to Google Maps, please visit the [Google Transit Partner Page](http://maps.google.com/help/maps/transit/partners/live-updates.html). diff --git a/transit/gtfs-realtime/spec/en/examples/README.md b/transit/gtfs-realtime/spec/en/examples/README.md deleted file mode 100644 index d38444d2a..000000000 --- a/transit/gtfs-realtime/spec/en/examples/README.md +++ /dev/null @@ -1,4 +0,0 @@ -The following examples show a textual representation of feeds. During development it is more convenient to produce ASCII protocol buffer output for easier debugging. You can compare your text output with these examples to check for the validity of data. - -* [Alerts](alerts.asciipb) -* [Trip update (full dataset)](trip-updates-full.asciipb) diff --git a/transit/gtfs-realtime/spec/en/examples/alerts.asciipb b/transit/gtfs-realtime/spec/en/examples/alerts.asciipb deleted file mode 100644 index c304f89bd..000000000 --- a/transit/gtfs-realtime/spec/en/examples/alerts.asciipb +++ /dev/null @@ -1,72 +0,0 @@ -# header information -header { - # version of speed specification. Currently "1.0" - gtfs_realtime_version: "1.0" - - # determines whether dataset is incremental or full - incrementality: FULL_DATASET - - # the time where this dataset was generated on server - # for determining the sequence of alert feeds - timestamp: 1284457468 -} -# multiple entities can be included in the feed -entity { - # unique identifier for the entity - id: "0" - - # "type" of the entity - alert { - # multiple periods can be defined when alert is active - active_period { - # start time in POSIX epoch format - start: 1284457468 - # end time in POSIX epoch format - end: 1284468072 - } - # selects which GTFS entities will be affected - informed_entity { - # valid parameters: - # agency_id, route_id, route_type, stop_id, trip (see TripDescriptor) - route_id: "219" - } - # multiple selectors (informed_entity) can be given - informed_entity { - stop_id: "16230" - } - - # cause of the alert - see gtfs-realtime.proto for valid values - cause: CONSTRUCTION - # effect of the alert - see gtfs-realtime.proto for valid values - effect: DETOUR - - # the given url provides additional information - url { - # multiple languages/translations supported - translation { - # page hosted outside of Google (at provider/agency, etc.) - text: "http://www.sometransitagency/alerts" - language: "en" - } - } - - # header for the alert will be highlighted - header_text { - # multiple languages/translations supported - translation { - text: "Stop at Elm street is closed, temporary stop at Oak street" - language: "en" - } - } - - # Alert description. Additional info to the header text - description_text { - # multiple languages/translations supported - translation { - text: "Due to construction at Elm street the stop is closed. The temporary stop can be found 300 meters north at Oak street" - language: "en" - } - } - } -} - diff --git a/transit/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb b/transit/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb deleted file mode 100644 index cc245cf75..000000000 --- a/transit/gtfs-realtime/spec/en/examples/trip-updates-full.asciipb +++ /dev/null @@ -1,79 +0,0 @@ -# header information -header { - # version of speed specification. Currently "1.0" - gtfs_realtime_version: "1.0" - # determines whether dataset is incremental or full - incrementality: FULL_DATASET - # the moment where this dataset was generated on server - timestamp: 1284457468 -} - -# multiple entities can be included in the feed -entity { - # unique identifier for the entity - id: "simple-trip" - - # "type" of the entity - trip_update { - trip { - # selects which GTFS entity (trip) will be affected - trip_id: "trip-1" - } - # schedule information update - stop_time_update { - # selecting which stop is affected - stop_sequence: 3 - # for the vehicle's arrival time - arrival { - # to be delayed with 5 seconds - delay: 5 - } - } - # ...this vehicle's delay is propagated to its subsequent stops. - - # Next information update on the vehicle's schedule - stop_time_update { - # selected by stop_sequence. It will update - stop_sequence: 8 - # the vehicle's original (scheduled) arrival time with a - arrival { - # 1 second delay. - delay: 1 - } - } - # ...likewise the delay is propagated to subsequent stops. - - # Next information update on the vehicle's schedule - stop_time_update { - # selected by stop_sequence. It will update the vehicle's arrival time - stop_sequence: 10 - # with the default delay of 0 (on time) and propagate this update - # for the rest of the vehicle's stops. - } - } -} - -# second entity containing update information for another trip -entity { - id: "3" - trip_update { - trip { - # frequency based trips are defined by their - # trip_id in GTFS and - trip_id: "frequency-expanded-trip" - # start_time - start_time: "11:15:35" - } - stop_time_update { - stop_sequence: 1 - arrival { - # negative delay means vehicle is 2 seconds ahead of schedule - delay: -2 - } - } - stop_time_update { - stop_sequence: 9 - } - } -} - diff --git a/transit/gtfs-realtime/spec/en/feed-entities.md b/transit/gtfs-realtime/spec/en/feed-entities.md deleted file mode 100644 index 43fff457f..000000000 --- a/transit/gtfs-realtime/spec/en/feed-entities.md +++ /dev/null @@ -1,54 +0,0 @@ -GTFS Realtime supports three distinct types of realtime data, that can be -combined witin a single realtime feed. Summaries are given below, with full -documentation given in the relevant section. - -## Trip Updates - -#### "Bus X is delayed by 5 minutes" - -Trip updates represent fluctuations in the timetable. We would expect to receive -trip updates for all trips you have scheduled that are realtime-capable. These -updates would give a predicted arrival or departure for stops along the route. -Trip updates can also provide for more complex scenarios where trips are -canceled, added to the schedule, or even re-routed. - -[More about Trip Updates...](trip-updates.md) - -## Service Alerts - -#### "Station Y is closed due to construction" - -Service alerts represent higher level problems with a particular entity and are -generally in the form of a textual description of the disruption. - -They could represent problems with: - -* Stations -* Lines -* The whole network -* etc. - -A service alert will usually consist of some text which will describe the -problem, and we also allow for URLs for more information as well as more -structured information to help us understand who this service alert affects. - -[More about Service Alerts...](service-alerts.md) - -## Vehicle Positions - -#### "This bus is at position X at time Y" - -Vehicle position represents a few basic pieces of information about a particular -vehicle on the network. - -Most important are the latitude and longitude the vehicle is at, but we can also -use data on current speed and odometer readings from the vehicle. - -[More about Vehicle Position updates...](vehicle-positions.md) - -## Historical remark on feed types - -Early versions of GTFS Realtime Specification required each feed to only contain -single type of entities. An example tool to convert from merged to the -feed-per-type schema is located at -https://github.com/bliksemlabs/gtfsrt-examples/blob/master/split_by_entitytype.py diff --git a/transit/gtfs-realtime/spec/en/reference.md b/transit/gtfs-realtime/spec/en/reference.md deleted file mode 100644 index aa03be1ee..000000000 --- a/transit/gtfs-realtime/spec/en/reference.md +++ /dev/null @@ -1,380 +0,0 @@ -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 1.0 of the feed specification is discussed and documented on this site. - -### Term Definitions - -* **required**: Exactly one -* **repeated**: Zero or more -* **message**: Complex type -* **enum**: List of fixed values -* **experimental**: Experimental field, subject to change. It may be formally adopted in the future. - -## Element Index - -* [FeedMessage](#message-feedmessage) - * [FeedHeader](#message-feedheader) - * [Incrementality](#enum-incrementality) - * [FeedEntity](#message-feedentity) - * [TripUpdate](#message-tripupdate) - * [TripDescriptor](#message-tripdescriptor) - * [ScheduleRelationship](#enum-schedulerelationship-1) - * [VehicleDescriptor](#message-vehicledescriptor) - * [StopTimeUpdate](#message-stoptimeupdate) - * [StopTimeEvent](#message-stoptimeevent) - * [ScheduleRelationship](#enum-schedulerelationship) - * [VehiclePosition](#message-vehicleposition) - * [TripDescriptor](#message-tripdescriptor) - * [ScheduleRelationship](#enum-schedulerelationship-1) - * [VehicleDescriptor](#message-vehicledescriptor) - * [Position](#message-position) - * [VehicleStopStatus](#enum-vehiclestopstatus) - * [CongestionLevel](#enum-congestionlevel) - * [OccupancyStatus](#enum-occupancystatus) - * [Alert](#message-alert) - * [TimeRange](#message-timerange) - * [EntitySelector](#message-entityselector) - * [TripDescriptor](#message-tripdescriptor) - * [ScheduleRelationship](#enum-schedulerelationship-1) - * [Cause](#enum-cause) - * [Effect](#enum-effect) - * [TranslatedString](#message-translatedstring) - * [Translation](#message-translation) - -# Elements - -## _message_ FeedMessage - -The contents of a feed message. Each message in the stream is obtained as a response to an appropriate HTTP GET request. A realtime feed is always defined with relation to an existing GTFS feed. All the entity ids are resolved with respect to the GTFS feed. - -#### Fields - -|_**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|-----------------|------------|-------------------|-------------------| -|**header** | [FeedHeader](#message-feedheader) | required | Metadata about this feed and feed message. | -|**entity** | [FeedEntity](#message-feedentity) | repeated | Contents of the feed. | - -## _message_ FeedHeader - -Metadata about a feed, included in feed messages. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | Version of the feed specification. The current version is 1.0. | -| **incrementality** | [Incrementality](#enum-incrementality) | optional | -| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | This timestamp identifies the moment when the content of this feed has been created (in server time). In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). To avoid time skew between systems producing and consuming realtime information it is strongly advised to derive timestamp from a time server. It is completely acceptable to use Stratum 3 or even lower strata servers since time differences up to a couple of seconds are tolerable. | - -## _enum_ Incrementality - -Determines whether the current fetch is incremental. - -* **FULL_DATASET**: this feed update will overwrite all preceding realtime information for the feed. Thus this update is expected to provide a full snapshot of all known realtime information. -* **DIFFERENTIAL**: currently, this mode is **unsupported** and behavior is **unspecified** for feeds that use this mode. There are discussions on the [GTFS Realtime mailing list](http://groups.google.com/group/gtfs-realtime) around fully specifying the behavior of DIFFERENTIAL mode and the documentation will be updated when those discussions are finalized. - -#### Values - -| _**Value**_ | -|-------------| -| **FULL_DATASET** | -| **DIFFERENTIAL** | - -## _message_ FeedEntity - -A definition (or update) of an entity in the transit feed. If the entity is not being deleted, exactly one of 'trip_update', 'vehicle' and 'alert' fields should be populated. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | Feed-unique identifier for this entity. The ids are used only to provide incrementality support. The actual entities referenced by the feed must be specified by explicit selectors (see EntitySelector below for more info). | -| **is_deleted** | [bool](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Whether this entity is to be deleted. Relevant only for incremental fetches. | -| **trip_update** | [TripUpdate](#message-tripupdate) | optional | Data about the realtime departure delays of a trip. | -| **vehicle** | [VehiclePosition](#message-vehicleposition) | optional | Data about the realtime position of a vehicle. | -| **alert** | [Alert](#message-alert) | optional | Data about the realtime alert. | - -## _message_ TripUpdate - -Realtime update on the progress of a vehicle along a trip. Please also refer to the general discussion of the [trip updates entities](trip-updates.md). - -Depending on the value of ScheduleRelationship, a TripUpdate can specify: - -* A trip that proceeds along the schedule. -* A trip that proceeds along a route but has no fixed schedule. -* A trip that has been added or removed with regard to schedule. - -The updates can be for future, predicted arrival/departure events, or for past events that already occurred. In most cases information about past events is a measured value thus its uncertainty value is recommended to be 0\. Although there could be cases when this does not hold so it is allowed to have uncertainty value different from 0 for past events. If an update's uncertainty is not 0, either the update is an approximate prediction for a trip that has not completed or the measurement is not precise or the update was a prediction for the past that has not been verified after the event occurred. - -Note that the update can describe a trip that has already completed.To this end, it is enough to provide an update for the last stop of the trip. If the time of arrival at the last stop is in the past, the client will conclude that the whole trip is in the past (it is possible, although inconsequential, to also provide updates for preceding stops). This option is most relevant for a trip that has completed ahead of schedule, but according to the schedule, the trip is still proceeding at the current time. Removing the updates for this trip could make the client assume that the trip is still proceeding. Note that the feed provider is allowed, but not required, to purge past updates - this is one case where this would be practically useful. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **trip** | [TripDescriptor](#message-tripdescriptor) | required | The Trip that this message applies to. There can be at most one TripUpdate entity for each actual trip instance. If there is none, that means there is no prediction information available. It does *not* mean that the trip is progressing according to schedule. | -| **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | optional | Additional information on the vehicle that is serving this trip. | -| **stop_time_update** | [StopTimeUpdate](#message-stoptimeupdate) | repeated | Updates to StopTimes for the trip (both future, i.e., predictions, and in some cases, past ones, i.e., those that already happened). The updates must be sorted by stop_sequence, and apply for all the following stops of the trip up to the next specified one. | -| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Moment at which the vehicle's real-time progress was measured. In POSIX time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC). | -| **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional |The current schedule deviation for the trip. Delay should only be specified when the prediction is given relative to some existing schedule in GTFS.
Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time.
Delay information in StopTimeUpdates take precedent of trip-level delay information, such that trip-level delay is only propagated until the next stop along the trip with a StopTimeUpdate delay value specified.
Feed providers are strongly encouraged to provide a TripUpdate.timestamp value indicating when the delay value was last updated, in order to evaluate the freshness of the data.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| - -## _message_ StopTimeEvent - -Timing information for a single predicted event (either arrival or departure). Timing consists of delay and/or estimated time, and uncertainty. - -* delay should be used when the prediction is given relative to some existing schedule in GTFS. -* time should be given whether there is a predicted schedule or not. If both time and delay are specified, time will take precedence (although normally, time, if given for a scheduled trip, should be equal to scheduled time in GTFS + delay). - -Uncertainty applies equally to both time and delay. The uncertainty roughly specifies the expected error in true delay (but note, we don't yet define its precise statistical meaning). It's possible for the uncertainty to be 0, for example for trains that are driven under computer timing control. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time. | -| **time** | [int64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Event as absolute time. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | -| **uncertainty** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | If uncertainty is omitted, it is interpreted as unknown. To specify a completely certain prediction, set its uncertainty to 0. | - -## _message_ StopTimeUpdate - -Realtime update for arrival and/or departure events for a given stop on a trip. Please also refer to the general discussion of stop time updates in the [TripDescriptor](#message-tripdescriptor) and [trip updates entities](trip-updates.md) documentation. - -Updates can be supplied for both past and future events. The producer is allowed, although not required, to drop past events. -The update is linked to a specific stop either through stop_sequence or stop_id, so one of these fields must necessarily be set. If the same stop_id is visited more than once in a trip, then stop_sequence should be provided in all StopTimeUpdates for that stop_id on that trip. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Must be the same as in stop_times.txt in the corresponding GTFS feed. | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Must be the same as in stops.txt in the corresponding GTFS feed. | -| **arrival** | [StopTimeEvent](#message-stoptimeevent) | optional | -| **departure** | [StopTimeEvent](#message-stoptimeevent) | optional | -| **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | optional | The default relationship is SCHEDULED. | - -## _enum_ ScheduleRelationship - -The relation between this StopTime and the static schedule. - -#### Values - -| _**Value**_ | _**Comment**_ | -|-------------|---------------| -| **SCHEDULED** | The vehicle is proceeding in accordance with its static schedule of stops, although not necessarily according to the times of the schedule. This is the **default** behavior. At least one of arrival and departure must be provided. If the schedule for this stop contains both arrival and departure times then so must this update. | -| **SKIPPED** | The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional. | -| **NO_DATA** | No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied. | - -## _message_ VehiclePosition - -Realtime positioning information for a given vehicle. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **trip** | [TripDescriptor](#message-tripdescriptor) | optional | The Trip that this vehicle is serving. Can be empty or partial if the vehicle can not be identified with a given trip instance. | -| **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | optional | Additional information on the vehicle that is serving this trip. Each entry should have a **unique** vehicle id. | -| **position** | [Position](#message-position) | optional | Current position of this vehicle. | -| **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The stop sequence index of the current stop. The meaning of current_stop_sequence (i.e., the stop that it refers to) is determined by current_status. If current_status is missing IN_TRANSIT_TO is assumed. | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. | -| **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | optional | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | -| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | -| **congestion_level** | [CongestionLevel](#enum-congestionlevel) | optional | -| _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _optional_ |The degree of passenger occupancy of the vehicle.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| - -## _enum_ VehicleStopStatus - -#### Values - -| _**Value**_ | _**Comment**_ | -|-------------|---------------| -| **INCOMING_AT** | The vehicle is just about to arrive at the stop (on a stop display, the vehicle symbol typically flashes). | -| **STOPPED_AT** | The vehicle is standing at the stop. | -| **IN_TRANSIT_TO** | The vehicle has departed the previous stop and is in transit. | - -## _enum_ CongestionLevel - -Congestion level that is affecting this vehicle. - -#### Values - -| _**Value**_ | -|-------------| -| **UNKNOWN_CONGESTION_LEVEL** | -| **RUNNING_SMOOTHLY** | -| **STOP_AND_GO** | -| **CONGESTION** | -| **SEVERE_CONGESTION** | - -## _enum OccupancyStatus_ - -The degree of passenger occupancy for the vehicle. - -**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. - -#### _Values_ - -| _**Value**_ | _**Comment**_ | -|-------------|---------------| -| _**EMPTY**_ | _The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ | -| _**MANY_SEATS_AVAILABLE**_ | _The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ | -| _**FEW_SEATS_AVAILABLE**_ | _The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ | -| _**STANDING_ROOM_ONLY**_ | _The vehicle can currently accomodate only standing passengers._ | -| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle can currently accomodate only standing passengers and has limited space for them._ | -| _**FULL**_ | _The vehicle is considered full by most measures, but may still be allowing passengers to board._ | -| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle can not accept passengers._ | - -## _message_ Alert - -An alert, indicating some sort of incident in the public transit network. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **active_period** | [TimeRange](#message-timerange) | repeated | Time when the alert should be shown to the user. If missing, the alert will be shown as long as it appears in the feed. If multiple ranges are given, the alert will be shown during all of them. | -| **informed_entity** | [EntitySelector](#message-entityselector) | repeated | Entities whose users we should notify of this alert. | -| **cause** | [Cause](#enum-cause) | optional | -| **effect** | [Effect](#enum-effect) | optional | -| **url** | [TranslatedString](#message-translatedstring) | optional | The URL which provides additional information about the alert. | -| **header_text** | [TranslatedString](#message-translatedstring) | optional | Header for the alert. This plain-text string will be highlighted, for example in boldface. | -| **description_text** | [TranslatedString](#message-translatedstring) | optional | 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. | - -## _enum_ Cause - -Cause of this alert. - -#### Values - -| _**Value**_ | -|-------------| -| **UNKNOWN_CAUSE** | -| **OTHER_CAUSE** | -| **TECHNICAL_PROBLEM** | -| **STRIKE** | -| **DEMONSTRATION** | -| **ACCIDENT** | -| **HOLIDAY** | -| **WEATHER** | -| **MAINTENANCE** | -| **CONSTRUCTION** | -| **POLICE_ACTIVITY** | -| **MEDICAL_EMERGENCY** | - -## _enum_ Effect - -The effect of this problem on the affected entity. - -#### Values - -| _**Value**_ | -|-------------| -| **NO_SERVICE** | -| **REDUCED_SERVICE** | -| **SIGNIFICANT_DELAYS** | -| **DETOUR** | -| **ADDITIONAL_SERVICE** | -| **MODIFIED_SERVICE** | -| **OTHER_EFFECT** | -| **UNKNOWN_EFFECT** | -| **STOP_MOVED** | - -## _message_ TimeRange - -A time interval. The interval is considered active at time `t` if `t` is greater than or equal to the start time and less than the end time. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **start** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Start time, in POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). If missing, the interval starts at minus infinity. | -| **end** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | End time, in POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). If missing, the interval ends at plus infinity. | - -## _message_ Position - -A geographic position of a vehicle. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **latitude** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | Degrees North, in the WGS-84 coordinate system. | -| **longitude** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | Degrees East, in the WGS-84 coordinate system. | -| **bearing** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Bearing, in degrees, clockwise from True North, i.e., 0 is North and 90 is East. This can be the compass bearing, or the direction towards the next stop or intermediate location. This should not be deduced from the sequence of previous positions, which clients can compute from previous data. | -| **odometer** | [double](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Odometer value, in meters. | -| **speed** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Momentary speed measured by the vehicle, in meters per second. | - -## _message_ TripDescriptor - -A descriptor that identifies an instance of a GTFS trip, or all instances of a trip along a route. To specify a single trip instance, the trip_id (and if necessary, start_time) is set. If route_id is also set, then it should be same as one that the given trip corresponds to. To specify all the trips along a given route, only the route_id should be set. Note that if the trip_id is not known, then station sequence ids in TripUpdate are not sufficient, and stop_ids must be provided as well. In addition, absolute arrival/departure times must be provided. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The trip_id from the GTFS feed that this selector refers to. For non frequency-based trips, this field is enough to uniquely identify the trip. For frequency-based trip, start_time and start_date might also be necessary. | -| **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The route_id from the GTFS that this selector refers to. | -| **direction_id** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The direction_id from the GTFS feed trips.txt file, indicating the direction of travel for trips this selector refers to.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
| -| **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The initially scheduled start time of this trip instance. When the trip_id corresponds to a non-frequency-based trip, this field should either be omitted or be equal to the value in the GTFS feed. When the trip_id correponds to a frequency-based trip, the start_time must be specified for trip updates and vehicle positions. If the trip corresponds to exact_times=1 GTFS record, then start_time must be some multiple (including zero) of headway_secs later than frequencies.txt start_time for the corresponding time period. If the trip corresponds to exact_times=0, then its start_time may be arbitrary, and is initially expected to be the first departure of the trip. Once established, the start_time of this frequency-based trip should be considered immutable, even if the first departure time changes -- that time change may instead be reflected in a StopTimeUpdate. Format and semantics of the field is same as that of GTFS/frequencies.txt/start_time, e.g., 11:15:35 or 25:15:35. | -| **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The scheduled start date of this trip instance. This field must be provided to disambiguate trips that are so late as to collide with a scheduled trip on a next day. For example, for a train that departs 8:00 and 20:00 every day, and is 12 hours late, there would be two distinct trips on the same time. This field can be provided but is not mandatory for schedules in which such collisions are impossible - for example, a service running on hourly schedule where a vehicle that is one hour late is not considered to be related to schedule anymore. In YYYYMMDD format. | -| **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship-1) | optional | - -## _enum_ ScheduleRelationship - -The relation between this trip and the static schedule. If a trip is done in accordance with temporary schedule, not reflected in GTFS, then it shouldn't be marked as SCHEDULED, but marked as ADDED. - -#### Values - -| _**Value**_ | _**Comment**_ | -|-------------|---------------| -| **SCHEDULED** | Trip that is running in accordance with its GTFS schedule, or is close enough to the scheduled trip to be associated with it. | -| **ADDED** | An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to respond to sudden passenger load. | -| **UNSCHEDULED** | A trip that is running with no schedule associated to it, for example, if there is no schedule at all. | -| **CANCELED** | A trip that existed in the schedule but was removed. | - -## _message_ VehicleDescriptor - -Identification information for the vehicle performing the trip. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field | -| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle. | -| **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The license plate of the vehicle. | - -## _message_ EntitySelector - -A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, then the matching has to apply to all the given specifiers. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **agency_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | -| **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | -| **route_type** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | -| **trip** | [TripDescriptor](#message-tripdescriptor) | optional | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | - -## _message_ TranslatedString - -An internationalized message containing per-language versions of a snippet of text or a URL. One of the strings from a message will be picked up. The resolution proceeds as follows: If the UI language matches the language code of a translation, the first matching translation is picked. If a default UI language (e.g., English) matches the language code of a translation, the first matching translation is picked. If some translation has an unspecified language code, that translation is picked. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **translation** | [Translation](#message-translation) | repeated | At least one translation must be provided. | - -## _message_ Translation - -A localized string mapped to a language. - -#### Fields - -| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ | -|------------------|------------|-------------------|-------------------| -| **text** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | required | A UTF-8 string containing the message. | -| **language** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | BCP-47 language code. Can be omitted if the language is unknown or if no internationalization is done at all for the feed. At most one translation is allowed to have an unspecified language tag. | diff --git a/transit/gtfs-realtime/spec/en/service-alerts.md b/transit/gtfs-realtime/spec/en/service-alerts.md deleted file mode 100644 index c27031ecc..000000000 --- a/transit/gtfs-realtime/spec/en/service-alerts.md +++ /dev/null @@ -1,56 +0,0 @@ -Service alerts allow you to provide updates whenever there is disruption on the network. Delays and cancellations of individual trips should usually be communicated using [Trip updates](trip-updates.md). - -You have the option to provide the following: - -* URL - link to your site explaining more about the alert -* Header text - a summary of the alert -* Description - a full description of the alert, which will always be shown alongside the header (so should not repeat this information). - -### Time Range - -The alert will be displayed where appropriate within the given time range. This range should cover the entire time that the alert is useful for the passenger to see. - -If no time is given, we will display the alert for as long as it is in the feed. If multiple ranges are given, we will display during all of them. - -### Entity Selector - -Entity selector allows you specify exactly which parts of the network this alert affects, so that we can display only the most appropriate alerts to the user. You may include multiple entity selectors for alerts which affect multiple entities. - -Entities are selected using their GTFS identifiers, and you can select any of the following: - -* Agency - affects the whole network -* Route - affects the whole route -* Route type - affects any route of this type. e.g. all subways. -* Trip - affects a particular trip -* Stop - affects a particular stop - -### Cause - -What is the cause of this alert? You may specify one of the following: - -* Unknown cause -* Other cause (not represented by any of these options) -* Technical problem -* Strike -* Demonstration -* Accident -* Holiday -* Weather -* Maintenance -* Construction -* Police activity -* Medical emergency - -### Effect - -What effect does this problem have on the specified entity? You may specify one of the following: - -* No service -* Reduced service -* Significant delays (insignificant delays should only be provided through [Trip updates](trip-updates.md)). -* Detour -* Additional service -* Modified service -* Stop moved -* Other effect (not represented by any of these options) -* Unknown effect diff --git a/transit/gtfs-realtime/spec/en/trip-updates.md b/transit/gtfs-realtime/spec/en/trip-updates.md deleted file mode 100644 index 60933605f..000000000 --- a/transit/gtfs-realtime/spec/en/trip-updates.md +++ /dev/null @@ -1,100 +0,0 @@ -Trip updates represent fluctuations in the timetable. We would expect to receive trip updates for all trips you have scheduled that are realtime-capable. These updates would give a predicted arrival or departure time for stops along the route. Trip updates can also provide for more complex scenarios where trips are canceled or added to the schedule, or even re-routed. - -**Reminder:** In [GTFS](https://developers.google.com/transit/gtfs/), a trip is a sequence of two of more stops occurring at a specific time. - -There should be **at most** one trip update for each scheduled trip. In case there is no trip update for a scheduled trip, it will be concluded that no realtime data is available for the trip. The data consumer should **not** assume that the trip is running on time. - -## Stop Time Updates - -A trip update consists of one or more updates to vehicle stop times, which are referred to as [StopTimeUpdates](reference.md#StopTimeUpdate). These can be supplied for past and future stop times. You are allowed, but not required, to drop past stop times. Producers should not drop a past `StopTimeUpdate` if it refers to a stop with a scheduled arrival time in the future for the given trip (i.e. the vehicle has passed the stop ahead of schedule), as otherwise it will be concluded that there is no update for this stop. - -For example, if the following data appears in the GTFS-rt feed: - -* Stop 4 – Predicted at 10:18am (scheduled at 10:20am – 2 min early) -* Stop 5 – Predicted at 10:30am (scheduled at 10:30am – on time) - -...the prediction for Stop 4 cannot be dropped from the feed until 10:21am, even if the bus actually passes the stop at 10:18am. If the `StopTimeUpdate` for Stop 4 was dropped from the feed at 10:18am or 10:19am, and the scheduled arrival time is 10:20am, then the consumer should assume that no real-time information exists for Stop 4 at that time, and schedule data from GTFS should be used. - -Each [StopTimeUpdate](reference.md#StopTimeUpdate) is linked to a stop. Ordinarily this can be done using either a GTFS stop_sequence or a GTFS stop_id. However, in the case you are providing an update for a trip without a GTFS trip_id, you must specify stop_id as stop_sequence has no value. The stop_id must still reference a stop_id in GTFS. If the same stop_id is visited more than once in a trip, then stop_sequence should be provided in all StopTimeUpdates for that stop_id on that trip. - -The update can provide a exact timing for **arrival** and/or **departure** at a stop in [StopTimeUpdates](reference.md#StopTimeUpdate) using [StopTimeEvent](reference.md#StopTimeEvent). This should contain either an absolute **time** or a **delay** (i.e. an offset from the scheduled time in seconds). Delay can only be used in case the trip update refers to a scheduled GTFS trip, as opposed to a frequency-based trip. In this case, time should be equal to scheduled time + delay. You may also specify **uncertainty** of the prediction along with [StopTimeEvent](reference.md#StopTimeEvent), which is discussed in more detail in section [Uncertainty](#uncertainty) further down the page. - -For each [StopTimeUpdate](reference.md#StopTimeUpdate), the default schedule relationship is **scheduled**. (Note that this is different from the schedule relationship for the trip). You may change this to **skipped** if the stop will not be stopped at, or **no data** if you only have realtime data for some of the trip. - -**Updates should be sorted by stop_sequence** (or stop_ids in the order they occur in the trip). - -If one or more stops are missing along the trip the update is propagated to all subsequent stops. This means that updating a stop time for a certain stop will change all subsequent stops in the absence of any other information. - -**Example 1** - -For a trip with 20 stops, a [StopTimeUpdate](reference.md#StopTimeUpdate) with arrival delay and departure delay of 0 ([StopTimeEvents](reference.md#StopTimeEvent)) for stop_sequence of the current stop means that the trip is exactly on time. - -**Example 2** - -For the same trip instance, three [StopTimeUpdates](reference.md#StopTimeUpdate) are provided: - -* delay of 300 seconds for stop_sequence 3 -* delay of 60 seconds for stop_sequence 8 -* delay of unspecified duration for stop_sequence 10 - -This will be interpreted as: - -* stop_sequences 1,2 have unknown delay. -* stop_sequences 3,4,5,6,7 have delay of 300 seconds. -* stop_sequences 8,9 have delay of 60 seconds. -* stop_sequences 10,..,20 have unknown delay. - -### Trip Descriptor - -The information provided by the trip descriptor depends on the schedule relationship of trip you are updating. There are a number of options for you to set: - -|_**Value**_|_**Comment**_| -|-----------|-------------| -| **Scheduled** | This trip is running according to a GTFS schedule, or is close enough to still be associated with it. | -| **Added** | This trip was not scheduled and has been added. For example, to cope with demand, or replace a broken down vehicle. | -| **Unscheduled** | This trip is running and is never associated with a schedule. For example, if there is no schedule and the buses run on a shuttle service. | -| **Canceled** | This trip was scheduled, but is now removed. | - -In most cases, you should provide the trip_id of the scheduled trip in GTFS that this update relates to. - -#### Systems with repeated trip_ids - -For systems using repeated trip_ids, for example trips modeled using frequencies.txt, that is frequency-based trips, the trip_id is not in itself a unique identifier of a single journey, as it lacks a -specific time component. In order to uniquely identify such trips within a -TripDescriptor, a triple of identifiers must be provided: - -* __trip_id__ -* __start_time__ -* __start_date__ - -start_time should be first published, and any subsequent feed updates should use -that same start_time when referring to the same journey. StopTimeUpdates -should be used to indicate adjustments; start_time does not have to be precisely -the departure time from the first station, although it should be pretty close to -that time. - -For example, let’s say we decide at 10:00, May, 25th 2015, that a trip with -trip_id=T will start at start_time=10:10:00, and provide this information via -realtime feed at 10:01. By 10:05 we suddenly know that the trip will start not -at 10:10 but at 10:13. In our new realtime feed we can still identify this trip -as (T, 2015-05-25, 10:10:00) but provide a StopTimeUpdate with departure from -first stop at 10:13:00. - -#### Alternative trip matching - -Trips which are not frequency based may also be uniquely identified by a -TripDescriptor including the combination of: - -* __route_id__ -* __direction_id__ -* __start_time__ -* __start_date__ - -where start_time is the scheduled start time as defined in the static schedule, as long as the combination of ids provided resolves to a unique trip. - - -## Uncertainty - -Uncertainty applies to both the time and the delay value of a [StopTimeUpdate](reference.md#StopTimeUpdate). The uncertainty roughly specifies the expected error in true delay as an integer in seconds (but note, the precise statistical meaning is not defined yet). It's possible for the uncertainty to be 0, for example for trains that are driven under computer timing control. - -As an example a long-distance bus that has an estimated delay of 15 minutes arriving to its next stop within a 4 minute window of error (that is +2 / -2 minutes) will have an Uncertainty value of 240. diff --git a/transit/gtfs-realtime/spec/en/vehicle-positions.md b/transit/gtfs-realtime/spec/en/vehicle-positions.md deleted file mode 100644 index 62da24dd7..000000000 --- a/transit/gtfs-realtime/spec/en/vehicle-positions.md +++ /dev/null @@ -1,59 +0,0 @@ -Vehicle position is used to provide automatically generated information on the location of a vehicle, such as from a GPS device on board. A single vehicle position should be provided for every vehicle that is capable of providing it. - -The trip that the vehicle is currently serving should be given through a [trip descriptor](reference.md#TripDescriptor). You can also provide a [vehicle descriptor](reference.md#VehicleDescriptor), which specifies a precise physical vehicle that you are providing updates about. Documentation is provided below. - -A **timestamp** denoting the time when the position reading was taken can be provided. Note that this is different from the timestamp in the feed header, which is the time that this message was generated by the server. - -**Current passage** can also be provided (either as a `stop_sequence` or `stop_id`). This is a reference to the stop that the vehicle is either on its way to, or already stopped at. - -## Position - -Position contains the location data within Vehicle Position. Latitude and longitude are required, the other fields are optional. These types of data are: - -* **Latitude** - degrees North, in the WGS-84 coordinate system -* **Longitude** - degrees East, in the WGS-84 coordinate system -* **Bearing** - direction that the vehicle is facing -* **Odometer** - the distance that the vehicle has travelled -* **Speed** - momentary speed measured by the vehicle, in meters per second - -## Congestion Level - -Vehicle position also allows the agency to specify the congestion level that the vehicle is currently experiencing. Congestion can be classed under the following categories: - -* Unknown congestion level -* Running smoothly -* Stop and go -* Congestion -* Severe congestion - -It is up to the agency to classify what you class as each type of congestion. Our guidance is that severe congestion is only used in situations where the traffic is so congested that people are leaving their cars. - -## Occupancy status - -Vehicle position also allows the agency to specify the degree of passenger occupancy for the vehicle. Occupancy status can be classed under the following categories: - -* Empty -* Many seats available -* Few seats available -* Standing room only -* Crushed standing room only -* Full -* Not accepting passengers - -This field is still **experimental**, and subject to change. It may be formally adopted in the future. - -## VehicleStopStatus - -Vehicle stop status gives more meaning to the status of a vehicle in relation with a stop that it is currently approaching or is at. It can be set to any of these values. - -* **Incoming at** - the vehicle is about to arrive at the referenced stop -* **Stopped at** - the vehicle is stopped at the referenced stop -* **In transit to** - the referenced stop is the next stop for the vehicle - **default** - -## Vehicle Descriptor - -Vehicle descriptor describes a precise physical vehicle and can contain any of the following attributes: - -* **ID** - internal system of identification for the vehicle. Should be unique to the vehicle -* **Label** - a user visible label - for example the name of a train -* **License plate** - the actual license plate of the vehicle diff --git a/transit/gtfs-realtime/spec/es/README.md b/transit/gtfs-realtime/spec/es/README.md deleted file mode 100644 index ac2154f95..000000000 --- a/transit/gtfs-realtime/spec/es/README.md +++ /dev/null @@ -1,50 +0,0 @@ -GTFS en tiempo real es una especificación de feed que permite que las empresas de tranporte público proporcionen actualizaciones en tiempo real sobre su flota a los programadores de la aplicación. Es una extensión de [GTFS](https://developers.google.com/transit/gtfs/reference) (Especificación general de feeds de transporte público), un formato de datos abierto para los horarios de transporte público y la información geográfica asociada. GTFS en tiempo real fue diseñado en torno a la facilidad de implementación, buena interoperabilidad GTFS y un enfoque en la información al pasajero. - -La especificación fue diseñada a través de una asociación de las empresas miembro de las [Actualizaciones del transporte público en tiempo real](https://developers.google.com/transit/google-transit#LiveTransitUpdates) iniciales, diferentes programadores de transporte público y Google. La especificación está publicada bajo la licencia [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0). - -## ¿Cómo empiezo? - -1. Sigue leyendo el resumen general a continuación. -2. Decide qué [tipos de feed](feed-types.md) proporcionarás. -3. Consulta los [ejemplos de feeds](examples/). -4. Crea tus propios feeds mediante la [referencia](reference.md). -5. Publica tu feed. - -## Resumen general de los tipos de feed GTFS en tiempo real - -La especificación es compatible actualmente con los siguientes tipos de información: - -* **Actualizaciones de viaje**: retrasos, cancelaciones, cambios de ruta -* **Alertas del servicio**: traslados de paradas o eventos imprevistos que afectan una estación, ruta o toda la red -* **Posiciones del vehículo**: información sobre los vehículos, incluidos la ubicación y el nivel de congestión - -Las actualizaciones de cada tipo se proporcionan en un feed separado. Los feeds se muestran a través de HTTP y se actualizan con frecuencia. El archivo en sí es un archivo binario normal, por lo que cualquier tipo de servidor web puede alojar y mostrar el archivo (es posible utilizar otros protocolos de transferencia también). Alternativamente, los servidores de aplicaciones web también se podrían utilizar, los cuales devolverán el feed como una respuesta a una solicitud GET de HTTP válida. No hay limitaciones en cuanto a la frecuencia ni al método exacto de cómo el feed debe ser actualizado o recuperado. - -Ya que GTFS en tiempo real te permite presentar el estado _real_ de tu flota, el feed debe ser actualizado con frecuencia, de preferencia cuando se ingresen nuevos datos de tu sistema de ubicación automática de vehículos. - -[Más información sobre los tipos de feed...](feed-types.md) - -## Formato de los datos - -El formato de intercambio de datos de GTFS en tiempo real se basa en [Búferes de protocolo](https://developers.google.com/protocol-buffers/). - -Los búferes de protocolo son un mecanismo de lenguaje y plataforma neutral para serializar datos estructurados (como XML, pero más pequeño, rápido y simple). La estructura de datos se define en un archivo [gtfs-realtime.proto](gtfs-realtime.proto), que luego se utiliza para generar el código fuente para leer y escribir fácilmente tus datos estructurados desde y hacia una variedad de flujos de datos, mediante diferentes lenguajes, por ejemplo Java, C++ o Python. - -[Más información sobre los búferes de protocolo](https://developers.google.com/protocol-buffers/)... - -## Estructura de los datos - -La jerarquía de los elementos y las definiciones de su tipo están especificadas en el archivo [gtfs-realtime.proto](gtfs-realtime.proto). - -Este archivo de texto se utiliza para generar las bibliotecas necesarias en tu lenguaje de programación seleccionado. Estas bibliotecas proporcionan las clases y funciones necesarias para generar feeds GTFS en tiempo real válidos. Las bibliotecas no solo hacen que la creación del feed sea más fácil, sino que también garantizan que solo se produzcan feeds válidos. - -[Más información sobre la estructura de los datos.](reference.md) - -## Obtener ayuda - -Para participar en los debates sobre GTFS en tiempo real y sugerir cambios y adiciones a la especificación, únete al [grupo de debate de GTFS en tiempo real](http://groups.google.com/group/gtfs-realtime). - -## Google Maps y Actualizaciones de transporte público en tiempo real - -Una de las posibles aplicaciones que utiliza GTFS en tiempo real es [Actualizaciones de transporte público en tiempo real](https://developers.google.com/transit/google-transit#LiveTransitUpdates), una función de Google Maps que proporciona a los usuarios información de transporte público en tiempo real. Si trabajas para una empresa de transporte público que está interesada en proporcionar actualizaciones en tiempo real para Google Maps, visita la [Página de socios de Google Transit](http://maps.google.com/help/maps/transit/partners/live-updates.html). - diff --git a/transit/gtfs-realtime/spec/es/examples/README.md b/transit/gtfs-realtime/spec/es/examples/README.md deleted file mode 100644 index 7db8d1e27..000000000 --- a/transit/gtfs-realtime/spec/es/examples/README.md +++ /dev/null @@ -1,4 +0,0 @@ -Los siguientes ejemplos muestran una representación textual de los feeds. Durante el desarrollo, es más conveniente producir una salida de búfer del protocolo ASCII para una depuración más fácil. Puedes comparar tu salida de texto con estos ejemplos para comprobar la validez de los datos. - -* [Alertas de Google](alerts.asciipb) -* [Actualización de viaje (conjunto de datos completo)](trip-updates-full.asciipb) diff --git a/transit/gtfs-realtime/spec/es/examples/alerts.asciipb b/transit/gtfs-realtime/spec/es/examples/alerts.asciipb deleted file mode 100644 index 663c405db..000000000 --- a/transit/gtfs-realtime/spec/es/examples/alerts.asciipb +++ /dev/null @@ -1,72 +0,0 @@ -# Información del encabezado -header { - # Versión de la especificación de velocidad. Actualmente "1.0". - gtfs_realtime_version: "1.0" - - # Determina si el conjunto de datos se completó o tiene un incremento gradual. - incrementality: FULL_DATASET - - # La hora en la que se generó el conjunto de datos en el servidor - # para determinar la secuencia de feeds de alerta. - timestamp: 1284457468 -} -# Se pueden incluir varias entidades en el feed. -entity { - # Identificador único para la entidad - id: "0" - - # "Tipo" de la entidad - alert { - # Se pueden definir varios períodos cuando la alerta está activa. - active_period { - # Hora de inicio en formato epoch POSIX - start: 1284457468 - # Hora de fin en formato epoch POSIX - end: 1284468072 - } - # Selecciona qué entidades GTFS serán afectadas. - informed_entity { - # Parámetros válidos: agency_id, route_id, route_type, - # stop_id, viaje (consultar TripDescriptor) - route_id: "219" - } - # Se pueden entregar selectores múltiples (informed_entity). - informed_entity { - stop_id: "16230" - } - - # Causa de la alerta: consultar gtfs-realtime.proto para valores válidos - cause: CONSTRUCTION - # Efecto de la alerta: consultar gtfs-realtime.proto para valores reales - effect: DETOUR - - # La URL dada proporciona información adicional. - url { - # Varios idiomas/traducciones compatibles - translation { - # La página está alojada fuera de Google (en el proveedor o la empresa, etc.). - text: "http://www.sometransitagency/alerts" - language: "es" - } - } - - # El encabezado para la alerta será destacado. - header_text { - # Varios idiomas o traducciones son compatibles. - translation { - text: "La parada en Elm street está cerrada, detenerse temporalmente en Oak street" - language: "es" - } - } - - # Descripción de la alerta. Información adicional al texto del encabezado. - description_text { - # Varios idiomas o traducciones son compatibles. - translation { - text: "Debido a una construcción en Elm street, la parada está cerrada. La parada temporal se puede encontrar a 300 metros al norte de Oak street." - language: "es" - } - } - } -} - diff --git a/transit/gtfs-realtime/spec/es/examples/trip-updates-full.asciipb b/transit/gtfs-realtime/spec/es/examples/trip-updates-full.asciipb deleted file mode 100644 index f8e653964..000000000 --- a/transit/gtfs-realtime/spec/es/examples/trip-updates-full.asciipb +++ /dev/null @@ -1,79 +0,0 @@ -# Información del encabezado -header { - # Especificación de la versión de la velocidad. La versión "1.0" actual - gtfs_realtime_version: "1.0" - # determina si el conjunto de datos se completó o continúa creciendo - incrementality: FULL_DATASET - # en el momento en el que se generó en el servidor. - timestamp: 1284457468 -} - -# Se pueden incluir varias entidades en el -entity { - # identificador único del feed correspondiente a la entidad - id: "simple-trip" - - # "tipo" de la entidad. - trip_update { - trip { - # Selecciona qué entidad GTFS (viaje) se verá afectada. - trip_id: "trip-1" - } - # Actualización de la información del programa - stop_time_update { - # Se selecciona qué parada se ve afectada - stop_sequence: 3 - # para que el vehículo llegue - arrival { - # cinco segundos tarde. - delay: 5 - } - } - # La demora de este vehículo se extiende a las siguientes paradas. - - # Próxima actualización de la información acerca del programa del vehículo - stop_time_update { - # según el campo stop_sequence. Se actualizará - stop_sequence: 8 - # el horario de llegada original del vehículo (programado) con una - arrival { - # demora de un segundo. - delay: 1 - } - } - # ...Asimismo, la demora se extiende a las siguientes paradas. - - # Próxima actualización de la información acerca del programa del vehículo - stop_time_update { - # según el campo stop_sequence. Se actualizará el horario de llegada del vehículo - stop_sequence: 10 - # con la demora predeterminada de cero segundos (a tiempo) y se extenderá esta actualización - # al resto de las paradas del vehículo. - } - } -} - -# Segunda entidad con información acerca de la actualización de otro viaje -entity { - id: "3" - trip_update { - trip { - # En función de su frecuencia, los viajes se definen según el - # trip_id de la especificación GTFS y el campo - trip_id: "frequency-expanded-trip" - # start_time - start_time: "11:15:35" - } - stop_time_update { - stop_sequence: 1 - arrival { - # Una demora negativa se produce cuando el vehículo se adelanta dos segundos según lo establecido en el programa. - delay: -2 - } - } - stop_time_update { - stop_sequence: 9 - } - } -} - diff --git a/transit/gtfs-realtime/spec/es/feed-types.md b/transit/gtfs-realtime/spec/es/feed-types.md deleted file mode 100644 index 13b44f804..000000000 --- a/transit/gtfs-realtime/spec/es/feed-types.md +++ /dev/null @@ -1,36 +0,0 @@ -La especificación GTFS en tiempo real admite el envío de tres tipos diferentes de datos en tiempo real. Si bien la sintaxis del archivo [gtfs-realtime.proto](gtfs-realtime.proto) permite que se mezclen distintos tipos de entidades para un feed, solo se puede usar un tipo de entidad por feed. Los resúmenes se ofrecen a continuación, con la documentación completa proporcionada en la sección correspondiente. - -## Actualizaciones de viaje - -#### "El autobús X tiene una demora de cinco minutos". - -Las actualizaciones de viaje ofrecen información acerca de fluctuaciones en el horario. Esperamos recibir actualizaciones de viaje para todos los viajes programados cuya duración se puede predecir en tiempo real. Estas actualizaciones ofrecerían un horario de llegada o salida para las diferentes paradas de la ruta. Las actualizaciones de viaje también pueden brindar información en situaciones más complejas, como cuando los viajes se cancelan o agregan al programa, o como cuando su trayecto se modifica. - -[Más información acerca de las Actualizaciones de viaje...](trip-updates.md) - -## Alertas de servicio - -#### "La estación Y está cerrada por tareas de construcción". - -Las alertas de servicio ofrecen información acerca de los problemas más graves que puede sufrir una entidad en particular. En general, se expresan a través de una descripción textual de la interrupción. - -Pueden representar los problemas que sufren: - -* las estaciones, -* las líneas, -* la red completa, -* etc. - -Una alerta de servicio a menudo consiste en una descripción textual del problema. También permitimos que se incluyan las URL de los sitios en los que se ofrecen más detalles e información más estructurada para poder entender a quién afecta una alerta de servicio. - -[Más información acerca de las Alertas de servicio...](service-alerts.md) - -## Posiciones de los vehículos - -#### "Este autobús se encuentra en la posición X a la hora Y". - -La posición de un vehículo ofrece datos básicos acerca de un vehículo en particular de la red. - -La información más importante consiste en la latitud y longitud donde se encuentra el vehículo. Sin embargo, también podemos usar datos acerca de las lecturas del cuentakilómetros y velocidad actuales del vehículo. - -[Más información acerca las actualizaciones de las Posiciones de los vehículos...](vehicle-positions.md) diff --git a/transit/gtfs-realtime/spec/es/gtfs-realtime.proto b/transit/gtfs-realtime/spec/es/gtfs-realtime.proto deleted file mode 100644 index cc2925333..000000000 --- a/transit/gtfs-realtime/spec/es/gtfs-realtime.proto +++ /dev/null @@ -1,569 +0,0 @@ -// Copyright 2015 The GTFS Specifications Authors. -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -// Archivo de definición de protocolo para GTFS en tiempo real. -// -// GTFS en tiempo real permite que las agencias de transporte público brinden a -// los consumidores información en tiempo real acerca de las interrupciones de -// sus servicios (estaciones cerradas, líneas que no funcionan, demoras -// importantes, etc.), la ubicación de sus vehículos y los horarios de llegada -// esperados. -// -// Este protocolo se publica en: -// https://github.com/google/transit/tree/master/gtfs-realtime - -syntax = "proto2"; - -option java_package = "com.google.transit.realtime"; -package transit_realtime; - -// El contenido de un mensaje de feed -// Un feed es un flujo continuo de mensajes de feed. Cada mensaje del flujo se -// obtiene como una respuesta a una solicitud HTTP GET adecuada. -// Un feed en tiempo real siempre se define con relación a un feed GTFS -// existente. Todos los ID de entidad se resuelven con respecto al feed GTFS. -// -// Un feed depende de cierta configuración externa: -// - El feed GTFS correspondiente. -// - Aplicación del feed (actualizaciones, posiciones o alertas). Un feed solo -// debe contener elementos de una aplicación especificada; todas las demás -// entidades se ignorarán. -// - Frecuencia de sondeo. -message FeedMessage { - // Metadatos acerca de este feed y mensaje de feed - required FeedHeader header = 1; - - // Contenido del feed - repeated FeedEntity entity = 2; -} - -// Metadatos acerca de un feed, incluidos en mensajes de feed -message FeedHeader { - // Versión de la especificación de feed - // La versión actual es 1.0. - required string gtfs_realtime_version = 1; - - // Determina si la búsqueda actual es incremental. Actualmente, el modo - // DIFFERENTIAL no es admitido y no se especifica para feeds que usan este - // modo. Existen foros de debate en la lista de correo de GTFS en tiempo real - // sobre la especificación completa del comportamiento del modo DIFFERENTIAL y - // la documentación se actualizará cuando esos foros de debate finalicen. - enum Incrementality { - FULL_DATASET = 0; - DIFFERENTIAL = 1; - } - optional Incrementality incrementality = 2 [default = FULL_DATASET]; - - // Esta marca de tiempo identifica el momento en que se creó el contenido de - // este feed (en tiempo del servidor). En tiempo POSIX (es decir, la cantidad - // de segundos desde el 1.º de enero de 1970 00:00:00 UTC). - optional uint64 timestamp = 3; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; -} - -// Una definición (o actualización) de una entidad en el feed de transporte -// público. -message FeedEntity { - // Los ID se usan solo para proporcionar asistencia sobre el aumento - // incremental. El ID debe ser único dentro de un FeedMessage. Los - // FeedMessages consiguientes pueden contener FeedEntities con el mismo ID. En - // el caso de una actualización DIFFERENTIAL, la nueva FeedEntity con algunos - // ID reemplazará a la antigua FeedEntity con el mismo ID (o la eliminará: - // consulta is_deleted a continuación). Las entidades de GTFS reales (p. ej., - // estaciones, rutas, viajes) a las que hace referencia el feed deben estar - // especificadas por selectores explícitos (consulta EntitySelector a - // continuación para obtener más información). - required string id = 1; - - // Establece si esta entidad debe eliminarse. Relevante solo para búsquedas - // incrementales. - optional bool is_deleted = 2 [default = false]; - - // Datos acerca de la propia entidad. Exactamente uno de los siguientes campos - // debe estar presente (a menos que se esté eliminando la entidad). - optional TripUpdate trip_update = 3; - optional VehiclePosition vehicle = 4; - optional Alert alert = 5; -} - -// -// Entidades usadas en el feed. -// - -// La actualización en tiempo real del progreso de un vehículo a lo largo de un -// viaje. Dependiendo del valor de ScheduleRelationship, un TripUpdate puede -// especificar: -// - Un viaje que continúa según el programa. -// - Un viaje que continúa por la ruta, pero no tiene un programa fijo. -// - Un viaje que se agregó o eliminó con respecto al programa. -// -// Las actualizaciones pueden ser para eventos de llegada/salida futuros -// previstos o para eventos pasados que ya ocurrieron. -// Normalmente, las actualizaciones deben ser más precisas y más certeras -// (consulta incertidumbre a continuación) a medida que los eventos se acercan -// al momento actual. -// Aun cuando eso no sea posible, la información para eventos pasados debe ser -// precisa y certera. En particular, si una actualización apunta a un momento -// pasado, pero la incertidumbre de su actualización no es 0, el cliente debe -// concluir que la actualización es una predicción (errónea) y que el viaje aún -// no se ha completado. -// -// Ten en cuenta que la actualización puede describir un viaje que ya se ha -// completado. A este fin, proporcionar una actualización para la última parada -// del viaje es suficiente. Si tal momento está en el pasado, el cliente -// concluirá que todo el viaje está en el pasado (es posible, aunque ilógico, -// proporcionar también actualizaciones para las paradas precedentes). Esta -// opción es más relevante para un viaje que se ha completado con anticipación a -// lo programado, pero que, de acuerdo con el programa, el viaje todavía -// continúa en este momento. Si se eliminan las actualizaciones para este viaje, -// el cliente puede asumir que el viaje todavía continúa. Ten en cuenta que al -// proveedor del feed se le permite, pero no está obligado a, purgar -// actualizaciones pasadas: en este caso, esto sería útil en la práctica. -message TripUpdate { - // El viaje al que se aplica este mensaje. Puede haber como máximo una - // entidad TripUpdate para cada instancia de viaje real. - // Si no hay ninguna, eso significa que no hay información de predicción - // disponible. *No* significa que el viaje se está realizando de acuerdo con - // la programación. - required TripDescriptor trip = 1; - - // Información adicional sobre el vehículo que está realizando el viaje. - optional VehicleDescriptor vehicle = 3; - - // Información sobre los tiempos para un solo evento previsto (ya sea llegada - // o salida). - // Los horarios consisten en la información sobre demoras o tiempos estimados - // y la incertidumbre. La demora (delay) debe usarse cuando la predicción se - // realiza con relación a una programación existente en GTFS. - // - El tiempo (time) debe darse aunque no haya una programación prevista. Si - // se especifican tanto el tiempo como la demora, el tiempo será prioritario - // (aunque, por lo general, el tiempo, si se otorga para un viaje - // programado, debe ser igual al tiempo programado en GTFS + la demora). - // - // La incertidumbre se aplica de la misma forma tanto al tiempo como a la - // demora. La incertidumbre especifica el error esperado en una demora real - // (pero ten en cuenta, que todavía no definimos su significado estadístico - // preciso). Es posible que la incertidumbre sea 0, por ejemplo, para los - // trenes que funcionan con un control de horarios por computadora. - message StopTimeEvent { - // La demora (en segundos) puede ser positiva (significa que el vehículo - // está retrasado) o negativa (significa que el vehículo está adelantado). - // Una demora de 0 significa que el vehículo está yendo a tiempo. - optional int32 delay = 1; - - // El evento como tiempo absoluto - // En tiempo Unix (es decir, la cantidad de segundos desde el 1.º de enero - // de 1970 00:00:00 UTC). - optional int64 time = 2; - - // Si se omite la incertidumbre, se interpreta como desconocida. - // Si la predicción es desconocida o demasiado incierta, el campo demora (o - // tiempo) debe estar vacío. En tal caso, el campo incertidumbre se ignora. - // Para especificar una predicción completamente cierta, configura su - // incertidumbre en 0. - optional int32 uncertainty = 3; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; - } - - // Actualización en tiempo real para eventos de llegada o salida para una - // determinada parada en un viaje. Se pueden suministrar actualizaciones tanto - // para eventos pasados como para eventos futuros. Al productor se le - // permite, aunque no está obligado a, proporcionar eventos pasados. - message StopTimeUpdate { - // La actualización está vinculada con una parada específica ya sea mediante - // stop_sequence o stop_id, de manera que necesariamente debe configurarse - // uno de los campos que aparecen a continuación. Consulta la documentación - // en TripDescriptor para obtener más información. - - // Debe ser la misma que la de stop_times.txt en el feed GTFS - // correspondiente. - optional uint32 stop_sequence = 1; - // Debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. - optional string stop_id = 4; - - optional StopTimeEvent arrival = 2; - optional StopTimeEvent departure = 3; - - // La relación entre este StopTime y el programa estático. - enum ScheduleRelationship { - // El vehículo continúa conforme a su programa estático de paradas, aunque - // no necesariamente de acuerdo a los horarios del programa. - // Se debe proporcionar al menos uno de los horarios de llegada y salida. - // Si el programa para esta parada contiene los horarios tanto de llegada - // como de salida, entonces esta actualización también debe tenerlos. Una - // actualización con solo una llegada, por ejemplo, cuando el programa - // tiene ambos, indica que el viaje está terminando temprano en esta - // parada. - SCHEDULED = 0; - - // La parada se omite, es decir, el vehículo no se detendrá en esta - // parada. La llegada y la salida son opcionales. - SKIPPED = 1; - - // No hay datos para esta parada. La intención principal de este valor es - // brindar predicciones solo para parte de un viaje, es decir, si la - // última actualización para un viaje tiene un especificador NO_DATA, - // entonces se considerará que tampoco se especifican StopTimes para el - // resto de las paradas del viaje. No se debe suministrar ni la llegada - // ni la salida. - NO_DATA = 2; - } - optional ScheduleRelationship schedule_relationship = 5 - [default = SCHEDULED]; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; - } - - // Actualizaciones a StopTimes para el viaje (tanto futuras, es decir, - // predicciones, como, en algunos casos, pasadas, es decir, aquellas que ya - // ocurrieron). - // Las actualizaciones se deben clasificar por stop_sequence y aplicarse a - // todas las paradas siguientes del viaje hasta la próxima especificada. - // - // Ejemplo 1: - // Para un viaje con 20 paradas, una StopTimeUpdate con demora de llegada y - // demora de salida de 0 para una stop_sequence de la parada actual significa - // que el viaje está llegando exactamente a horario. - // - // Ejemplo 2: - // Para la misma instancia de viaje, se proporcionan 3 StopTimeUpdates: - // - demora de 5 minutos para la stop_sequence 3 - // - demora de 1 minuto para la stop_sequence 8 - // - demora de duración no especificada para la stop_sequence 10 - // Esto se interpretará como: - // - las stop_sequences 3,4,5,6,7 tienen una demora de 5 minutos. - // - las stop_sequences 8,9 tienen una demora de 1 minuto. - // - las stop_sequences 10,... tienen una demora desconocido. - repeated StopTimeUpdate stop_time_update = 2; - - // Momento en el cual se midió el progreso en tiempo real del vehículo. En - // tiempo POSIX (es decir, la cantidad de segundos desde el 1º de enero de - // 1970 00:00:00 UTC). - optional uint64 timestamp = 4; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; -} - -// Información de posicionamiento en tiempo real de un vehículo dado. -message VehiclePosition { - // El viaje que este vehículo está realizando. - // Puede estar vacío o ser parcial si el vehículo no se puede identificar con - // una instancia de viaje dada. - optional TripDescriptor trip = 1; - - // Información adicional sobre el vehículo que está realizando este viaje. - optional VehicleDescriptor vehicle = 8; - - // Posición actual de este vehículo. - optional Position position = 2; - - // El índice de la secuencia de parada de la parada actual. El significado de - // current_stop_sequence (es decir, la parada a la que hace referencia) lo - // determina current_status. - // Si falta current_status, se asume IN_TRANSIT_TO. - optional uint32 current_stop_sequence = 3; - // Identifica la parada actual. El valor debe ser el mismo que el de stops.txt - // en el feed GTFS correspondiente. - optional string stop_id = 7; - - enum VehicleStopStatus { - // El vehículo está a punto de llegar a la parada (en una visualización de - // la parada, el símbolo del vehículo, por lo general, parpadea). - INCOMING_AT = 0; - - // El vehículo está detenido en la parada. - STOPPED_AT = 1; - - // El vehículo ha partido y está en tránsito hacia la siguiente parada. - IN_TRANSIT_TO = 2; - } - // El estado exacto del vehículo con respecto a la parada actual. - // Se ignora si falta el valor en current_stop_sequence. - optional VehicleStopStatus current_status = 4 [default = IN_TRANSIT_TO]; - - // Momento en el cual se midió la posición del vehículo. En tiempo POSIX (es - // decir, la cantidad de segundos desde el 1º de enero de 1970 00:00:00 UTC). - optional uint64 timestamp = 5; - - // El nivel de congestión que está afectando a este vehículo. - enum CongestionLevel { - UNKNOWN_CONGESTION_LEVEL = 0; - RUNNING_SMOOTHLY = 1; - STOP_AND_GO = 2; - CONGESTION = 3; - SEVERE_CONGESTION = 4; // Personas que dejan sus autos. - } - optional CongestionLevel congestion_level = 6; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; -} - -// Una alerta, que indica que existe algún tipo de incidente en la red de -// transporte público. -message Alert { - // Tiempo durante el cual la alerta debe mostrarse al usuario. Si falta, la - // alerta se mostrará durante todo el tiempo en que aparezca en el feed. - // Si se proporcionan múltiples intervalos, la alerta se mostrará durante - // todos ellos. - repeated TimeRange active_period = 1; - - // Entidades a cuyos usuarios debemos notificar esta alerta. - repeated EntitySelector informed_entity = 5; - - // Causa de esta alerta. - enum Cause { - UNKNOWN_CAUSE = 1; - OTHER_CAUSE = 2; // No representable mediante máquina. - TECHNICAL_PROBLEM = 3; - STRIKE = 4; // Los empleados de las empresas de transporte público dejaron de trabajar. - DEMONSTRATION = 5; // Las personas están bloqueando las calles. - ACCIDENT = 6; - HOLIDAY = 7; - WEATHER = 8; - MAINTENANCE = 9; - CONSTRUCTION = 10; - POLICE_ACTIVITY = 11; - MEDICAL_EMERGENCY = 12; - } - optional Cause cause = 6 [default = UNKNOWN_CAUSE]; - - // El efecto de este problema en la entidad afectada. - enum Effect { - NO_SERVICE = 1; - REDUCED_SERVICE = 2; - - // No nos preocupan las demoras NO significativas: son difíciles de - // detectar, tienen un pequeño impacto sobre el usuario y desordenarían los - // resultados ya que son demasiado frecuentes. - SIGNIFICANT_DELAYS = 3; - - DETOUR = 4; - ADDITIONAL_SERVICE = 5; - MODIFIED_SERVICE = 6; - OTHER_EFFECT = 7; - UNKNOWN_EFFECT = 8; - STOP_MOVED = 9; - } - optional Effect effect = 7 [default = UNKNOWN_EFFECT]; - - // La URL que proporciona información adicional acerca de la alerta. - optional TranslatedString url = 8; - - // Encabezado de la alerta. Contiene un breve resumen del texto de la alerta - // como texto simple. - optional TranslatedString header_text = 10; - - // Descripción completa de la alerta como texto simple. La información de la - // descripción debe agregar a la información del encabezado. - optional TranslatedString description_text = 11; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; -} - -// -// Estructuras de datos de bajo nivel que se utilizaron más arriba. -// - -// Un intervalo de tiempo. El intervalo se considera activo a la hora 't' si 't' -// es mayor o igual que la hora de inicio y menor que la hora de finalización. -message TimeRange { - // Hora de inicio, en tiempo POSIX (es decir, la cantidad de segundos desde el - // 1º de enero de 1970 00:00:00 UTC). - // Si falta esta información, el intervalo comienza en el infinito negativo. - optional uint64 start = 1; - - // Hora de finalización, en tiempo POSIX (es decir, la cantidad de segundos - // desde el 1º de enero de 1970 00:00:00 UTC). - // Si falta esta información, el intervalo finaliza en el infinito positivo. - optional uint64 end = 2; -} - -// Una posición. -message Position { - // Grados al Norte, en el sistema de coordenadas WGS-84. - required float latitude = 1; - - // Grados al Este, en el sistema de coordenadas WGS-84 - required float longitude = 2; - - // Orientación, en grados, en el sentido de las agujas del reloj desde el - // Norte, es decir, 0 es Norte y 90 es Este. Esto puede ser la orientación de - // la brújula o la dirección hacia la siguiente parada o la ubicación - // intermedia. - // Esto no debe deducirse de las instrucciones de la secuencia de posiciones - // anteriores, que puede calcularse a partir de los datos anteriores. - optional float bearing = 3; - - // Valor del odómetro, en metros. - optional double odometer = 4; - // Velocidad momentánea medida por el vehículo, en metros por segundo. - optional float speed = 5; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; -} - -// Un descriptor que identifica una instancia de un viaje de GTFS, o todas las -// instancias de un viaje por una ruta. -// - Para especificar una sola instancia de viaje, se establece el trip_id (y, -// en caso de ser necesario, el start_time). Si también se establece el -// route_id, entonces debe ser el mismo al que corresponde el viaje dado. -// - Para especificar todos los viajes por una ruta dada, solo se debe -// establecer el route_id. Ten en cuenta que si el trip_id no se conoce, -// entonces los identificadores de secuencia de parada en TripUpdate no son -// suficientes y los stop_ids también se deben proporcionar. Además, se deben -// proporcionar las horas absolutas de llegada/salida. -message TripDescriptor { - // El trip_id del feed GTFS al cual hace referencia este selector. - // Para viajes sin frecuencia expandida, este campo es suficiente para - // identificar de forma unívoca al viaje. Para viajes con frecuencia - // expandida, start_time y start_date también podrían ser necesarios. - optional string trip_id = 1; - - // El route_id de GTFS al cual hace referencia este selector. - optional string route_id = 5; - - // La hora de inicio programada de esta instancia de viaje. - // Este campo debe proporcionarse solo si el viaje es de frecuencia expandida - // en el feed GTFS. El valor debe corresponder precisamente a la start_time - // especificada para la ruta del feed GTFS más algún múltiplo de headway_secs. - // El formato del campo es el mismo que el de GTFS/frequencies.txt/start_time, - // p. ej., 11:15:35 o 25:15:35. - optional string start_time = 2; - - // La fecha de inicio programada de esta instancia de viaje. - // Se debe proporcionar para desambiguar los viajes que están tan retrasados - // que pueden colisionar con un viaje programado para el día siguiente. Por - // ejemplo, para un tren que sale a las 8:00 y a las 20:00 todos los días, y - // que tiene una demora de 12 horas, habrá dos viajes diferentes a la misma - // hora. - // Este campo se puede proporcionar pero no es obligatorio para los programas - // en los cuales tales colisiones son imposibles: por ejemplo, un servicio que - // funciona según una programación por hora donde un vehículo que tiene una - // demora de una hora ya deja de considerarse relacionado con el programa. - // En formato AAAAMMDD. - optional string start_date = 3; - - // La relación entre este viaje y el programa estático. Si un viaje se realiza - // de acuerdo con un programa temporal, no se refleja en GTFS, entonces - // no debe marcarse como SCHEDULED, sino como ADDED. - enum ScheduleRelationship { - // Viaje que se está ejecutando de acuerdo con su programa de GTFS,o que es - // lo suficientemente parecido al viaje programado como para asociarse a él. - SCHEDULED = 0; - - // Un viaje adicional que se ha agregado a un programa en ejecución, por - // ejemplo, para reemplazar un vehículo averiado o para responder a una - // carga repentina de un pasajero. - ADDED = 1; - - // Un viaje que se está ejecutando sin ningún programa asociado, por - // ejemplo, cuando no existe ningún programa. - UNSCHEDULED = 2; - - // Un viaje que existió en el programa, pero se eliminó. - CANCELED = 3; - } - optional ScheduleRelationship schedule_relationship = 4; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; -} - -// Información de identificación para el vehículo que realiza el viaje. -message VehicleDescriptor { - // Identificación interna del sistema para el vehículo. Debe ser única para el - // vehículo y se puede usar para realizar un seguimiento del vehículo a medida - // que avanza en el sistema. - optional string id = 1; - - // Etiqueta visible para el usuario, es decir, algo que se debe mostrar al - // pasajero para ayudarlo a identificar el vehículo correcto. - optional string label = 2; - - // La patente del vehículo. - optional string license_plate = 3; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; -} - -// Un selector para una entidad en un feed GTFS. -message EntitySelector { - // Los valores de los campos deben corresponder a los campos apropiados en el - // feed GTFS. - // Se debe brindar, al menos, un especificador. Si se proporcionan varios, - // entonces el que coincide debe aplicarse a todos los especificadores dados. - optional string agency_id = 1; - optional string route_id = 2; - // corresponde a route_type en GTFS. - optional int32 route_type = 3; - optional TripDescriptor trip = 4; - optional string stop_id = 5; - - // El espacio de nombres de extensiones permite a los programadores externos - // extender la especificación de GTFS en tiempo real para agregar y evaluar - // nuevas funciones y modificaciones a la especificación. - extensions 1000 to 1999; -} - -// Un mensaje internacionalizado que contiene versiones por idioma de un -// fragmento de texto o una URL. -// Se seleccionará una de las cadenas de un mensaje. La resolución se realiza de -// la siguiente manera: -// 1. Si el idioma de la interfaz de usuario coincide con el código de idioma de -// una traducción, se elige la primera traducción coincidente. -// 2. Si un idioma de interfaz de usuario predeterminado (p. ej., inglés) -// coincide con el código de idioma de una traducción, se elige la primera -// traducción coincidente. -// 3. Si alguna traducción tiene un código de idioma no especificado, se elige -// esa traducción. -message TranslatedString { - message Translation { - // Una cadena UTF-8 que contiene el mensaje. - required string text = 1; - // Código de idioma BCP-47. Se puede omitir si el idioma es desconocido o si - // no se realiza ningún i18n para el feed. Como máximo, se permite que - // una traducción tenga una etiqueta de idioma no especificado. - optional string language = 2; - } - // Se debe proporcionar al menos una traducción. - repeated Translation translation = 1; -} diff --git a/transit/gtfs-realtime/spec/es/reference.md b/transit/gtfs-realtime/spec/es/reference.md deleted file mode 100644 index 0b8c2e70a..000000000 --- a/transit/gtfs-realtime/spec/es/reference.md +++ /dev/null @@ -1,361 +0,0 @@ -Un feed GTFS en tiempo real permite que las empresas de transporte público brinden a los consumidores información en tiempo real acerca de las interrupciones de sus servicios (estaciones cerradas, líneas que no funcionan, demoras importantes, etc.), la ubicación de sus vehículos y tiempos de llegada esperados. - -Las especificaciones de la versión 1.0 del feed se abordan y documentan en este sitio. - -### Definiciones de términos - -* **obligatorio**: uno -* **repetido**: cero o más -* **mensaje**: tipo complejo -* **enum.**: lista de valores fijos - -## Índice de elementos - -* [FeedMessage](#FeedMessage) - * [FeedHeader](#FeedHeader) - * [Incrementality](#Incrementality) - * [FeedEntity](#FeedEntity) - * [TripUpdate](#TripUpdate) - * [TripDescriptor](#TripDescriptor) - * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) - * [VehicleDescriptor](#VehicleDescriptor) - * [StopTimeUpdate](#StopTimeUpdate) - * [StopTimeEvent](#StopTimeEvent) - * [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) - * [VehiclePosition](#VehiclePosition) - * [TripDescriptor](#TripDescriptor) - * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) - * [Position](#Position) - * [Alert](#Alert) - * [TimeRange](#TimeRange) - * [EntitySelector](#EntitySelector) - * [TripDescriptor](#TripDescriptor) - * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) - * [Cause](#Cause) - * [Effect](#Effect) - * [TranslatedString](#TranslatedString) - * [Translation](#Translation) - -# Elementos - -## _mensaje_ FeedMessage - -El contenido de un mensaje de feed. Cada mensaje en el flujo de datos se obtiene como una respuesta a una solicitud HTTP GET adecuada. Un feed en tiempo real siempre se define en relación con un feed GTFS existente. Todos los ID de entidades se resuelven en relación con el feed GTFS. - -Un feed depende de algunas configuraciones externas: - -* El feed GTFS correspondiente. -* La aplicación del feed (actualizaciones, posiciones o alertas). Un feed debe contener únicamente elementos de las aplicaciones correspondientes; todas las otras entidades se ignorarán. -* Frecuencia de sondeo, controlada por min_update_delay, max_update_delay. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **header** | [FeedHeader](#FeedHeader) | obligatorio | Metadatos sobre este feed y mensaje del feed | -| **entity** | [FeedEntity](#FeedEntity) | repetido | Contenido del feed | - -## _mensaje_ FeedHeader - -Metadatos sobre un feed, incluido en los mensajes del feed - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Especificación de la versión del feed. La versión actual es 1.0. | -| **incrementality** | [Incrementality](#Incrementality) | opcional | -| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Esta marca de tiempo identifica el momento en que se ha creado el contenido de este feed (en la hora del servidor). En la hora de POSIX (es decir, cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Para evitar el desvío de tiempos entre los sistemas que producen y que consumen información en tiempo real, se recomienda derivar la marca de tiempo desde un servidor de tiempo. Es absolutamente aceptable usar servidores de estrato 3 o, incluso, inferiores, porque las diferencias de tiempo de hasta un par de segundos son tolerables. | - -## _enum._ Incrementality - -Determina si la búsqueda actual es incremental. - -* **FULL_DATASET**: la actualización de este feed sobrescribirá toda la información en tiempo real anterior para el feed. Por lo tanto, se espera que esta actualización proporcione un resumen completo de toda la información en tiempo real conocida. -* **DIFFERENTIAL**: en este momento, este modo **no está admitido** y su comportamiento **no se especifica** para los feeds que usan este modo. Existen debates sobre la [lista de correo](http://groups.google.com/group/gtfs-realtime) de GTFS en tiempo real, relacionados con la especificación completa del comportamiento del modo DIFFERENTIAL, y la documentación se actualizará cuando esos debates finalicen. - -### Valores - -| _**Valor**_ | -|-------------| -| **FULL_DATASET** | -| **DIFFERENTIAL** | - -## _mensaje_ FeedEntity - -La definición (o actualización) de una entidad en el feed de transporte público. Si la entidad no se elimina, uno de los campos "trip_update", "vehicle" y "alert" debe completarse. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Identificador único del feed para esta entidad. Los identificadores se usan solamente para proporcionar soporte de incrementalidad. Las entidades reales a las que hace referencia el feed deben especificarse mediante selectores explícitos (ver EntitySelector más adelante para obtener más información). | -| **is_deleted** | [bool](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Establece si esta entidad debe eliminarse. Es relevante solo para las búsquedas incrementales. | -| **trip_update** | [TripUpdate](#TripUpdate) | opcional | Datos sobre las demoras de salida en tiempo real de un viaje. | -| **vehicle** | [VehiclePosition](#VehiclePosition) | opcional | Datos sobre la posición en tiempo real de un vehículo. | -| **alert** | [Alert](#Alert) | opcional | Datos sobre las alertas en tiempo real. | - -## _mensaje_ TripUpdate - -Actualización en tiempo real del progreso de un vehículo en un viaje. También consulta el debate general del [tipo de feed de actualizaciones del viaje](./trip-updates). - -Según el valor de ScheduleRelationship, TripUpdate puede especificar lo siguiente: - -* Un viaje que avanza según la programación. -* Un viaje que avanza por una ruta, pero que no tiene una programación fija. -* Un viaje que se ha agregado o se ha quitado en relación con una programación. - -Las actualizaciones pueden ser para eventos de llegada/salida futuros y previstos, o para eventos pasados que ya ocurrieron. En la mayoría de los casos, la información sobre los eventos pasados es un valor medido, por lo tanto, se recomienda que su valor de incertidumbre sea 0\. Aunque puede haber algunos casos en que esto no sea así, por lo que se admiten valores de incertidumbre distintos de 0 para los eventos pasados. Si el valor de incertidumbre de una actualización no es 0, entonces la actualización es una predicción aproximada para un viaje que no se ha completado o la medición no es precisa o la actualización fue una predicción para el pasado que no se ha verificado después de que ocurrió el evento. - -Ten en cuenta que la actualización puede describir un viaje que ya se ha completado. En este caso, es suficiente con proporcionar una actualización para la última parada del viaje. Si el tiempo de llegada para la última parada es en el pasado, el cliente concluirá que todo el viaje es pasado (es posible, aunque inconsecuente, proporcionar también actualizaciones para las paradas anteriores). Esta opción es más relevante para un viaje que se ha completado antes de lo que establecía la programación, pero que según esta, el viaje todavía se está realizando en este momento. Quitar las actualizaciones de este viaje podría hacer que el cliente considere que el viaje todavía se está realizando. Ten en cuenta que el proveedor del feed tiene permitido, aunque no está obligado, a purgar las actualizaciones pasadas (en este caso esto sería útil). - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **trip** | [TripDescriptor](#TripDescriptor) | obligatorio | El viaje al cual se aplica este mensaje. Puede haber una entidad de TripUpdate, como máximo, para cada instancia de viaje real. Si no hay ninguna, entonces no habrá información de predicciones disponible. *No* significa que el viaje se está realizando de acuerdo con la programación. | -| **vehicle** | [VehicleDescriptor](#VehicleDescriptor) | opcional | Información adicional sobre el vehículo con el cual se está realizando este viaje. | -| **stop_time_update** | [StopTimeUpdate](#StopTimeUpdate) | repetido | Las actualizaciones de StopTimes para el viaje (futuras, como las predicciones, y, en algunos casos, pasadas, es decir, aquellas que ya ocurrieron). Las actualizaciones deben ordenarse por secuencia de parada y deben aplicarse a todas las siguientes paradas del viaje hasta la próxima especificada. | -| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Momento en el que se midió el progreso en tiempo real del vehículo. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). | - -## _mensaje_ StopTimeEvent - -Información de horarios para un único evento previsto (sea la llegada o la salida). Los horarios consisten en la información sobre demoras o tiempos estimados y la incertidumbre. - -* La demora (delay) debe usarse cuando la predicción se realiza con relación a una programación existente en GTFS. -* El tiempo (time) debe darse aunque no haya una programación prevista. Si se especifican tanto el tiempo como la demora, el tiempo será prioritario (aunque, por lo general, el tiempo, si se otorga para un viaje programado, debe ser igual al tiempo programado en GTFS + la demora). - -La incertidumbre se aplica de la misma forma tanto al tiempo como a la demora. La incertidumbre especifica el error esperado en una demora real (pero ten en cuenta, que todavía no definimos su significado estadístico preciso). Es posible que la incertidumbre sea 0, por ejemplo, para los trenes que funcionan con un control de horarios por computadora. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La demora (en segundos) puede ser positiva (significa que el vehículo está retrasado) o negativa (significa que el vehículo está adelantado). Una demora de 0 significa que el vehículo está yendo a tiempo. | -| **time** | [int64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Evento como tiempo absoluto. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). | -| **uncertainty** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Si se omite la incertidumbre, se interpreta como desconocida. Para especificar una predicción completamente certera, establece la incertidumbre en 0. | - -## _mensaje_ StopTimeUpdate - -La actualización en tiempo real para los eventos de llegada o de salida para una determinada parada de un viaje. Consulta el debate general de las actualizaciones de tiempos de parada en la documentación de [TripDescriptor](#TripDescriptor) y [del tipo de feed de actualizaciones de viaje](./trip-updates). - -Las actualizaciones se pueden proporcionar tanto para eventos pasados como futuros. El productor tiene permitido, aunque no está obligado, a desestimar los eventos pasados. - La actualización está vinculada a una parada específica sea a través de stop_sequence o de stop_id, de manera que uno de estos campos debe definirse, necesariamente. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Debe ser la misma que la de stop_times.txt en el feed GTFS correspondiente. | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. | -| **arrival** | [StopTimeEvent](#StopTimeEvent) | opcional | -| **departure** | [StopTimeEvent](#StopTimeEvent) | opcional | -| **schedule_relationship** | [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) | opcional | La relación predeterminada es SCHEDULED. | - -## _enum._ ScheduleRelationship - -La relación entre este StopTime y la programación estática - -### Valores - -| _**Valor**_ | _**Comentario**_ | -|-------------|------------------| -| **SCHEDULED** | El vehículo está avanzando según su programación estática de paradas, aunque no necesariamente de acuerdo con los tiempos de la programación. Este es el comportamiento **predeterminado**. Al menos debe proporcionarse uno de los valores de llegada y de salida. Si la programación para esta parada contiene los tiempos de llegada y de salida, entonces también debe contener estos dos valores la actualización. Una actualización son solo una salida, digamos, cuando la programación tiene ambos datos, indica que el viaje se termina antes en esta parada. | -| **SKIPPED** | La parada se omite, es decir, el vehículo no se detendrá en esta parada. Los valores de llegada y salida son opcionales. | -| **NO_DATA** | No se proporcionan datos para esta parada. Esto indica que no hay información en tiempo real disponible. Cuando se establece NO_DATA, esto se propaga en las siguientes paradas, de manera que esta es la forma recomendada de especificar desde qué parada no tienes información en tiempo real. Cuando se establece NO_DATA, no se deben proporcionar los datos de llegada ni de salida. | - -## _mensaje_ VehiclePosition - -Información de posicionamiento en tiempo real para un vehículo dado - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **trip** | [TripDescriptor](#TripDescriptor) | opcional | El viaje que está haciendo este vehículo. Puede estar vacío o parcialmente vacío si el vehículo no puede identificarse con una instancia de viaje dada. | -| **vehicle** | [VehicleDescriptor](#VehicleDescriptor) | opcional | Información adicional sobre el vehículo que está realizando el viaje. Cada entrada debe tener un ID de vehículo **único**. | -| **position** | [Position](#Position) | opcional | Posición actual de este vehículo. | -| **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El índice de la secuencia de parada de la parada actual. El significado de current_stop_sequence (es decir, la parada a la que hace referencia) está determinado por current_status. Si falta el valor en current_status, se asume IN_TRANSIT_TO. | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Identifica la parada actual. El valor debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. | -| **current_status** | [VehicleStopStatus](#VehicleStopStatus) | opcional | El estado exacto del vehículo con respecto a la parada actual. Se ignora si falta el valor en current_stop_sequence. | -| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Momento en el cual se midió la posición del vehículo. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). | -| **congestion_level** | [CongestionLevel](#CongestionLevel) | opcional | - -## _enum._ VehicleStopStatus - -### Valores - -| _**Valor**_ | _**Comentario**_ | -|-------------|------------------| -| **INCOMING_AT** | El vehículo está a punto de llegar a la parada (en la visualización de la parada, el símbolo del vehículo, por lo general, parpadea). | -| **STOPPED_AT** | El vehículo está detenido en la parada. | -| **IN_TRANSIT_TO** | El vehículo ha salido de la parada anterior y está en tránsito. | - -## _enum._ CongestionLevel - -El nivel de congestión que está afectando al vehículo. - -### Valores - -| _**Valor**_ | -|-------------| -| **UNKNOWN_CONGESTION_LEVEL** | -| **RUNNING_SMOOTHLY** | -| **STOP_AND_GO** | -| **CONGESTION** | -| **SEVERE_CONGESTION** | - -## _mensaje_ Alert - -Una alerta que indica que existe algún tipo de incidente en la red de transporte público. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **active_period** | [TimeRange](#TimeRange) | repetido | Tiempo durante el cual debe mostrarse la alerta al usuario. Si falta, la alerta se mostrará durante todo el tiempo que aparezca en el feed. Si se otorgan varios intervalos, la alerta se mostrará durante todos ellos. | -| **informed_entity** | [EntitySelector](#EntitySelector) | repetido | Entidades a cuyos usuarios debemos notificar esta alerta. | -| **cause** | [Cause](#Cause) | opcional | -| **effect** | [Effect](#Effect) | opcional | -| **url** | [TranslatedString](#TranslatedString) | opcional | La URL que proporciona información adicional sobre la alerta. | -| **header_text** | [TranslatedString](#TranslatedString) | opcional | Encabezado de la alerta. Esta cadena de texto sin formato se resaltará, por ejemplo, en negrita. | -| **description_text** | [TranslatedString](#TranslatedString) | opcional | Descripción de la alerta. A esta cadena de texto sin formato se le aplicará el formato del cuerpo de la alerta (o se mostrará en una solicitud explícita de "expansión" realizada por el usuario
). La información de la descripción debe completar la información del encabezado. | - -## _enum._ Cause - -Causa de la alerta - -### Valores - -| _**Valor**_ | -|-------------| -| **UNKNOWN_CAUSE** | -| **OTHER_CAUSE** | -| **TECHNICAL_PROBLEM** | -| **STRIKE** | -| **DEMONSTRATION** | -| **ACCIDENT** | -| **HOLIDAY** | -| **WEATHER** | -| **MAINTENANCE** | -| **CONSTRUCTION** | -| **POLICE_ACTIVITY** | -| **MEDICAL_EMERGENCY** | - -## _enum._ Effect - -El efecto de este problema en la entidad afectada. - -### Valores - -| _**Valor**_ | -|-------------| -| **NO_SERVICE** | -| **REDUCED_SERVICE** | -| **SIGNIFICANT_DELAYS** | -| **DETOUR** | -| **ADDITIONAL_SERVICE** | -| **MODIFIED_SERVICE** | -| **OTHER_EFFECT** | -| **UNKNOWN_EFFECT** | -| **STOP_MOVED** | - -## _mensaje_ TimeRange - -Un intervalo de tiempo. El intervalo se considera activo `t` si `t` es mayor o igual que la hora de inicio y mejor que la hora de finalización. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **start** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Hora de inicio, en tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Si falta esta información, el intervalo comienza con el valor infinito negativo. | -| **end** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Hora de finalización, en tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Si falta esta información, el intervalo finaliza con el valor infinito positivo. | - -## _mensaje_ Position - -La posición geográfica de un vehículo - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **latitude** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Grados norte, en el sistema de coordenadas WGS-84 | -| **longitude** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Grados este, en el sistema de coordenadas WGS-84 | -| **bearing** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Orientación, en grados, en el sentido de las agujas del reloj desde el norte verdadero, es decir, 0 es el norte y 90 es el este. Esta puede ser la orientación de la brújula, o la dirección hacia la próxima parada o la ubicación intermedia. Esto no debe deducirse a partir de la secuencia de posiciones anteriores, que los clientes pueden calcular a partir de los datos anteriores. | -| **odometer** | [double](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El valor del odómetro en metros. | -| **speed** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Velocidad momentánea medida por el vehículo, en metros por segundo. | - -## _mensaje_ TripDescriptor - -Un descriptor que identifica una instancia de un viaje de GTFS o todas las instancias de un viaje por una ruta. Para especificar una sola instancia de viaje, se define trip_id (y si fuera necesario, start_time). Si también se define route_id, debe ser el mismo que uno a los cuales corresponda el viaje dado. Para especificar todos los viajes de una determinada ruta, solo se debe definir route_id. Ten en cuenta que si no se conoce el trip_id, entonces los identificadores de la secuencia de la estación en TripUpdate no son suficientes y, también, se deberán proporcionar los identificadores de parada. Además, se deben proporcionar las horas absolutas de llegada/salida. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El identificador de viaje del feed GTFS al cual hace referencia este selector. Para los viajes sin frecuencia extendida, este campo es suficiente para identificar de forma unívoca al viaje. Para los viajes con frecuencia extendida, también podrían necesitarse start_time y start_date. | -| **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El identificador de la ruta de GTFS al que hace referencia este selector. | -| **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La hora de inicio programada de esta instancia de viaje. Este campo debe proporcionarse solo si el viaje tiene frecuencia extendida en el feed GTFS. El valor debe corresponder precisamente a la hora de inicio especificada para la ruta del feed GTFS más algunos múltiplos de headway_secs. El formato del campo es el mismo que el de GTFS/frequencies.txt/start_time, es decir, 11:15:35 o 25:15:35. | -| **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La fecha de inicio programada de esta instancia de viaje. Este campo debe proporcionarse para desambiguar los viajes que están tan retrasados que pueden superponerse con un viaje programado para el día siguiente. Por ejemplo, para un tren que sale a las 8:00 y a las 20:00 todos los días, y está 12 horas retrasado, habrá dos viajes distintos a la misma hora. Este campo puede proporcionarse, pero no es obligatorio para las programaciones en las cuales las superposiciones son imposibles, por ejemplo, un servicio que funciona según una programación horaria donde un vehículo que está una hora retrasado deja de considerarse relacionado a la programación. En formato AAAAMMDD. | -| **schedule_relationship** | [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) | opcional | - -## _enum._ ScheduleRelationship - -La relación entre este viaje y la programación estática. Si un viaje se realiza de acuerdo con la programación temporal, no se refleja en GTFS, y por lo tanto, no debe marcarse como SCHEDULED, sino como ADDED. - -### Valores - -| _**Valor**_ | _**Comentario**_ | -|-------------|------------------| -| **SCHEDULED** | Viaje que se está realizando de acuerdo con su programación de GTFS, o que está realizándose tan parecido al viaje programado que se puede asociar con él. | -| **ADDED** | Un viaje adicional que se agregó además de una programación existente, por ejemplo, para reemplazar un vehículo averiado o para responder a una carga repentina de pasajeros. | -| **UNSCHEDULED** | Un viaje que se está realizando sin ninguna programación asociada, por ejemplo, cuando no existe ninguna programación. | -| **CANCELED** | Un viaje que existió en la programación, pero que luego se eliminó. | -| **REPLACEMENT** | Un viaje que reemplaza una parte de la programación estática. Si el selector de viaje identifica determinada instancia de viaje, entonces solamente esa instancia se reemplaza. Si el selector identifica una ruta, entonces todos los viajes de la ruta se reemplazan.
El reemplazo se aplica solamente a la parte del viaje que se suministra. Por ejemplo, consideremos una ruta que pasa por las paradas A,B,C,D,E,F y un viaje REPLACEMENT proporciona datos para las paradas A,B,C. Entonces, los horarios para las paradas D,E,F todavía se toman de la programación estática.
Un feed debe suministrar varios viajes REPLACEMENT. En este caso, la parte de la programación estática que se reemplaza es la suma de las definiciones de todos los feeds. Por lo general, todos los viajes REPLACEMENT deben corresponder a la misma ruta o a instancias de viaje individuales. | - -## _mensaje_ VehicleDescriptor - -Información de identificación para el vehículo que realiza el viaje. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Identificación interna del sistema para el vehículo. Debe ser **única** para cada vehículo y se usa para hacer un seguimiento del vehículo en la medida en que avanza en el sistema. Este identificador debe ser visible para el usuario final; para ello debes usar el campo **label** | -| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Etiqueta visible para el usuario, es decir, que se debe mostrar al pasajero para ayudarlo a identificar el vehículo correcto. | -| **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La patente del vehículo. | - -## _mensaje_ EntitySelector - -Un selector para una entidad en un feed GTFS. Los valores de los campos deben coincidir con los campos correspondientes del feed GTFS. Debe otorgarse al menos un especificador. Si se otorgan muchos, entonces la coincidencia debe hacerse con todos los especificadores dados. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **agency_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | -| **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | -| **route_type** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | -| **trip** | [TripDescriptor](#TripDescriptor) | opcional | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | - -## _mensaje_ TranslatedString - -Un mensaje internacionalizado que contiene versiones por idioma de un fragmento de texto o una URL. Se seleccionará una de las cadenas de un mensaje. La resolución se realiza de la siguiente manera: si el idioma de la IU coincide con el código de idioma de una traducción, se elije la primera traducción coincidente. Si un idioma de IU predetermiando (por ejemplo, inglés) coincide con el código de idioma de una traducción, se elije la primera traducción coincidente. Si alguna traducción tiene un código de idioma no especificado, se elija esa traducción. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **translation** | [Translation](#Translation) | repetido | Se debe proporcionar al menos una traducción. | - -## _mensaje_ Translation - -Una cadena localizada asignada a un idioma. - -### Campos - -| _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | -|------------------------|------------|--------------------|-------------------| -| **text** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Una cadena UTF-8 que contiene el mensaje. | -| **language** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Código de idioma BCP-47\. Se puede omitir si el idioma es desconocido o si no se realiza ninguna internacionalización para el feed. Al menos una traducción puede tener una etiqueta de idioma no especificado. | diff --git a/transit/gtfs-realtime/spec/es/service-alerts.md b/transit/gtfs-realtime/spec/es/service-alerts.md deleted file mode 100644 index aa9903b26..000000000 --- a/transit/gtfs-realtime/spec/es/service-alerts.md +++ /dev/null @@ -1,56 +0,0 @@ -Las alertas de servicio te permiten proporcionar actualizaciones cada vez que se produce una interrupción en la red. Las demoras y cancelaciones de viajes individuales a menudo se deben comunicar a través de las [Actualizaciones de viaje](trip-updates.md). - -Puedes proporcionar la siguiente información: - -* la URL del sitio en el que se ofrecen más detalles acerca de la alerta, -* el texto del encabezado a modo de resumen de la alerta, -* la descripción completa de la alerta que se mostrará junto al encabezado (la información no debe ser la misma en ambas partes). - -### Período - -La alerta aparecerá cuando corresponda en el transcurso del período establecido. Este período debe cubrir en su totalidad el lapso en el que el pasajero necesita la alerta. - -Si no se establece ningún período, mostraremos la alerta el tiempo que esta se encuentre en el feed. Si se establecen varios períodos, mostraremos la alerta durante todos ellos. - -### Selector de entidad - -El selector de entidad te permite especificar exactamente qué partes de la red afecta una alerta, a fin de que le podamos mostrar al usuario solo las alertas más adecuadas. Puedes incluir varios selectores de entidad en el caso de las alertas que afectan muchas entidades. - -Las entidades se seleccionan a través de los identificadores de la especificación GTFS y puedes elegir cualquiera de los siguientes: - -* Empresa: afecta toda la red. -* Ruta: afecta toda la ruta. -* Tipo de ruta: afecta cualquier ruta del tipo seleccionado; p. ej., todos los metros. -* Viaje: afecta un viaje en particular. -* Parada: afecta una parada en particular. - -### Causa - -¿Cuál es la causa de esta alerta? Puedes especificar cualquiera de las siguientes: - -* causa desconocida, -* otra causa (que no se ve representada por ninguna de estas opciones), -* problema técnico, -* huelga, -* manifestación, -* accidente, -* feriado, -* clima, -* tareas de mantenimiento, -* tareas de construcción, -* actividad policial, -* emergencia médica. - -### Efecto - -¿Qué efecto tiene este problema en la entidad seleccionada? Puedes especificar cualquiera de los siguientes: - -* sin servicio, -* servicio reducido, -* demoras importantes (aquellas poco importantes se deben informar a través de las [Actualizaciones de viaje](trip-updates.md)), -* desvío, -* servicio adicional, -* servicio modificado, -* traslado de parada, -* otro efecto (que no se ve representado por ninguna de estas opciones), -* efecto desconocido. diff --git a/transit/gtfs-realtime/spec/es/trip-updates.md b/transit/gtfs-realtime/spec/es/trip-updates.md deleted file mode 100644 index 20c2e8433..000000000 --- a/transit/gtfs-realtime/spec/es/trip-updates.md +++ /dev/null @@ -1,56 +0,0 @@ -Las actualizaciones de viaje representan fluctuaciones en el horario. Esperamos recibir actualizaciones de viaje para todos los viajes que has programado, que sean aptos para tiempo real. Estas actualizaciones brindarían un horario de llegada o salida previsto para las paradas a lo largo de la ruta. Las actualizaciones de viaje también pueden prever escenarios más complejos en los cuales se cancelen o agreguen viajes al programa, o incluso se redirijan. - -**Recordatorio:** En [GTFS](https://developers.google.com/transit/gtfs/), un viaje es una secuencia de dos o más paradas que tienen lugar a una hora específica. - -Debe haber **como máximo** una actualización de viaje para cada viaje programado. En caso de que no haya ninguna actualización de viaje para un viaje programado, se concluirá que no hay datos en tiempo real disponibles para el viaje. El consumidor de datos **no** debe asumir que el viaje se está realizando a horario. - -## Actualizaciones de horario de paradas - -Una actualización de viaje comprende una o más actualizaciones a los horarios de parada del vehículo, que se conocen como [StopTimeUpdates](reference.md#StopTimeUpdate). Pueden proporcionarse para horarios de paradas pasados y futuros. Tienes permitido brindar horarios de parada pasados, pero no es obligatorio que los brindes. Cuando lo hagas, ten en cuenta que no debes proporcionar una actualización pasada si se refiere a un viaje todavía no programado para haber terminado (es decir, que finalizó antes de lo programado), ya que, de lo contrario, se concluirá que no hay actualización de ese viaje. - -Cada [StopTimeUpdate](reference.md#StopTimeUpdate) está vinculada a una parada. Normalmente, esto se puede hacer usando un GTFS stop_sequence o un GTFS stop_id. Sin embargo, en caso de que estés suministrando una actualización para un viaje sin un trip_id de GTFS, debes especificar el stop_id ya que stop_sequence no tiene valor. El stop_id todavía debe hacer referencia a un stop_id en GTFS. - -La actualización puede proporcionar un horario exacto para la **llegada** o la **salida** en una parada en [StopTimeUpdates](reference.md#StopTimeUpdate) mediante [StopTimeEvent](reference.md#StopTimeUpdate). Esto debe contener un **horario** absoluto o un **retraso** (es decir, una compensación desde el horario programado en segundos). El retraso solo se puede utilizar en caso de que la actualización de viaje se refiera a un viaje de GTFS programado, en contraposición con un viaje basado en la frecuencia. En este caso, el horario debe ser igual al horario programado + el retraso. También debes especificar la **incertidumbre** de la predicción junto con [StopTimeEvent](reference.md#StopTimeUpdate), que se analiza más detalladamente en la sección [Incertidumbre](#Incertidumbre) más abajo en la página. - -Para cada [StopTimeUpdate](reference.md#StopTimeUpdate), la relación de programación predeterminada es **programada**. (Ten en cuenta que es diferente de la relación de programación para el viaje). Puedes cambiarla a **omitida** si la parada no se va a utilizar o a **sin datos** si solo tienes datos en tiempo real para parte del viaje. - -**Las actualizaciones se deben clasificar por stop_sequence** (o stop_id, en el orden en que tienen lugar en el viaje). - -Si faltan una o más paradas a lo largo del viaje, la actualización se propaga a todas las paradas subsiguientes. Esto significa que, en caso de no haber otra información, al actualizar un horario de parada para una cierta parada, se cambiarán todas las paradas subsiguientes. - -**Ejemplo 1** - -Para un viaje con 20 paradas, una [StopTimeUpdate](reference.md#StopTimeUpdate) con retraso de llegada y retraso de salida de 0 ([StopTimeEvents](reference.md#StopTimeEvent)) para la stop_sequence de la parada actual, significa que el viaje está exactamente a horario. - -**Ejemplo 2** - -Para la misma instancia de viaje, se proporcionan tres [StopTimeUpdates](reference.md#StopTimeUpdate): - -* retraso de 300 segundos para la stop_sequence 3 -* retraso de 60 segundos para la stop_sequence 8 -* retraso de duración no especificada para la stop_sequence 10 - -Esto se interpretará como: - -* las stop_sequences 3,4,5,6,7 tienen un retraso de 300 segundos. -* las stop_sequences 8,9 tienen un retraso de 60 segundos. -* las stop_sequences 10,..,20 tienen un retraso desconocido. - -### Descriptor de viajes - -La información suministrada por el descriptor de viajes depende de la relación de programación del viaje que estás actualizando. Hay una cantidad de opciones que puedes configurar: - -| _**Valor**_ | _**Comentario**_ | -|-------------|------------------| -| **Programado** | Este viaje se está ejecutando de acuerdo con un programa de GTFS o se asemeja lo suficiente como para seguir estando asociado a él. | -| **Agregado** | Este viaje no estaba programado y se ha agregado. Por ejemplo, para hacer frente a la demanda o reemplazar un vehículo averiado. | -| **Sin programar** | Este viaje se está ejecutando y nunca se asocia con un programa. Por ejemplo, si no hay programa y los autobuses operan en un servicio de traslados. | -| **Cancelado** | Este viaje se programó pero ahora se eliminó. | - -En la mayoría de los casos, debes proporcionar el trip_id del viaje programado en GTFS con el que se relaciona esta actualización. En caso de que no puedas vincular esta actualización con un viaje en GTFS, puedes brindar un route_id de GTFS, y una fecha y hora de inicio para el viaje. Generalmente, este es el caso de los viajes agregados, sin programar y de algunos tipos de viajes de reemplazo. - -## Incertidumbre - -La incertidumbre se aplica tanto al horario como al valor de retraso de una [StopTimeUpdate](reference.md#StopTimeUpdate). La incertidumbre especifica, en términos generales, el error esperado en retraso verdadero como un entero en segundos (pero ten en cuenta que, el significado estadístico preciso todavía no está definido). Es posible que la incertidumbre sea 0, por ejemplo, para los trenes conducidos bajo control de horarios por computadora. - -Como ejemplo, un autobús de larga distancia que tiene un retraso estimado de 15 minutos y llega a su siguiente parada con una ventana de error de 4 minutos (es decir, +2/-2 minutos) tendrá un valor de Incertidumbre de 240. diff --git a/transit/gtfs-realtime/spec/es/vehicle-positions.md b/transit/gtfs-realtime/spec/es/vehicle-positions.md deleted file mode 100644 index a6fafad97..000000000 --- a/transit/gtfs-realtime/spec/es/vehicle-positions.md +++ /dev/null @@ -1,45 +0,0 @@ -La posición del vehículo se utiliza para proporcionar información generada automáticamente sobre la ubicación de un vehículo, como de un dispositivo GPS a bordo. Se debe proporcionar una sola posición del vehículo para cada vehículo que puede proporcionarla. - -El viaje que el vehículo está realizando actualmente se debe proporcionar a través de un [descriptor de viaje](reference.md#VehicleDescriptor). También puedes proporcionar un [descriptor de vehículo](reference.md#VehicleDescriptor) que especifique un vehículo físico preciso sobre el cual estás proporcionando actualizaciones. La documentación se proporciona a continuación. - -Se puede proporcionar una **marca de tiempo** que indique el momento en el que se tomó la lectura de la posición. Ten en cuenta que esto es diferente de la marca de tiempo en el encabezado del feed, que es el tiempo en el que el servidor generó este mensaje. - -También se puede proporcionar un **paso actual** (ya sea como stop_sequence o stop_id). Esto es una referencia a la parada a la que el vehículo se está dirigiendo o en la que ya se detuvo. - -## Posición - -La posición contiene los datos de ubicación dentro de Posición del vehículo. Los campos de latitud y longitud son obligatorios; los demás campos son opcionales. Estos tipos de datos son: - -* **Latitud**: grados Norte, en el sistema de coordenadas WGS-84. -* **Longitud**: grados Este, en el sistema de coordenadas WGS-84. -* **Rumbo**: la dirección en la que el vehículo se orienta. -* **Odómetro**: la distancia que el vehículo ha recorrido. -* **Velocidad**: velocidad instantánea medida por el vehículo, en metros por segundo. - -## Nivel de congestión - -La posición del vehículo también permite que la empresa especifique el nivel de congestión que el vehículo está experimentando en el momento. La congestión se puede clasificar en las siguientes categorías: - -* Nivel de congestión desconocido -* Tráfico fluido -* Tráfico intermitente -* Congestión -* Congestión grave - -A la empresa le corresponde clasificar lo que clasificas como cada tipo de congestión. Nuestra orientación es que la congestión grave solo se utiliza en situaciones en las que el tráfico está tan congestionado que las personas están abandonando sus vehículos. - -## VehicleStopStatus - -El estado de parada del vehículo le da más significado al estado de un vehículo en relación con una parada a la que se está aproximando o en la que ya está. Se puede ajustar a cualquiera de estos valores. - -* **Llegando a**: el vehículo está a punto de llegar a la parada indicada. -* **Detenido en**: el vehículo está detenido en la parada indicada. -* **En camino a**: la parada indicada es la siguiente parada para el vehículo: **predeterminado**. - -## Descriptor de vehículo - -El descriptor de vehículo describe un vehículo físico preciso y puede contener cualquiera de los siguientes atributos: - -* **ID**: sistema interno de identificación del vehículo. Debe ser único para el vehículo. -* **Etiqueta**: una etiqueta visible para el usuario, por ejemplo el nombre de un tren. -* **Placa**: la placa real del vehículo. diff --git a/transit/gtfs/CHANGES.md b/transit/gtfs/CHANGES.md deleted file mode 100644 index 83379ba3a..000000000 --- a/transit/gtfs/CHANGES.md +++ /dev/null @@ -1,199 +0,0 @@ -The GTFS Specification is not set in stone. Instead, it is an open specification developed and maintained by the community of transit agencies, developers, and other stakeholders who use GTFS. It is expected that this community of producers and consumers of GTFS data will have proposals for extending the spec to enable new capabilities. To help manage that process, the following procedures and guidelines have been established. - -### Specification amendment process -The official specification, reference and documentation are written in English. If a translation to a different language differs from the English original, the latter takes precedence. All communication is performed 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. -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. -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). -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. - 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. -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. - 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. -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 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. - -### Guiding Principles -In order to preserve the original vision of GTFS, a number of guiding principles have been established to take into consideration when extending the spec: - -#### Feeds should be easy to create and edit -We chose CSV as the basis for the specification because it's easy to view and edit using spreadsheet programs and text editors, which is helpful for smaller agencies. It's also straightforward to generate from most programming languages and databases, which is good for publishers of larger feeds. - -#### Feeds should be easy to parse -Feed readers should be able to extract the information they're looking for with as little work as possible. Changes and additions to the feed should be as broadly useful as possible, to minimize the number of code paths that readers of the feed need to implement. (However, making creation easier should be given precedence, since there will ultimately be more feed publishers than feed readers.) - -#### Changes to the spec should be backwards-compatible -When adding features to the specification, we want to avoid making changes that will make existing feeds invalid. We don't want to create more work for existing feed publishers until they want to add capabilities to their feeds. Also, whenever possible, we want existing parsers to be able to continue to read the older parts of newer feeds. - -#### Speculative features are discouraged -Every new feature adds complexity to the creation and reading of feeds. Therefore, we want to take care to only add features that we know to be useful. Ideally, any proposal will have been tested by generating data for a real transit system that uses the new feature and writing software to read and display it. Note that the GTFS readily allows for extensions to the format through the addition of extra columns and files that are ignored by the official parsers & validators, so proposals can be easily prototyped and tested on existing feeds. - -### Revision History - -#### March 16, 2016 - -* Transition of GTFS documentation to Github at https://github.com/google/transit - -#### February 2, 2015 - -* Added stop_times.txt 'timepoint' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/Ah-J9JP2rJY) - -#### February 17, 2014 - -* Added trips.txt 'bikes_allowed' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/rEiSeKNc4cs) - -#### October 15, 2012 - -Added trips.txt 'wheelchair_accessible' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/ASxItgsQlh4) - -#### June 20, 2012 - -* Added 'wheelchair_boarding' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/ASxItgsQlh4) - -#### February 2, 2012 - -* Added 'stop_timezone' proposal to spec: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/2Il0Q9OXqu4) - -#### January 18, 2012 - -* Migrated documentation from old code.google.com to their new location at developers.google.com. - -#### September 26, 2011 - -* Added 'feed_info' proposal to spec: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/Sh0e4o9o2Gw) - -#### September 6, 2011 - -* Added 'agency_fare_url' proposal to spec: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/Zp9rPG07CgE) -* Added 'exact_times' proposal to spec: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/nZF9lbQ7TQs) - -#### March 30, 2009 - -* A new section on making a transit feed publicly available. This wasn't previously discussed on the group, because it wasn't strictly a change to how the data is interpreted or written. However, some of the folks at Google thought that it would be informative to include discussion of non-Google uses of GTFS, since there are an increasing number of applications that can make use of GTFS-formatted data. -* CSV format clarifications: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/03qz5aTA2mk). -* Additional guidance on how to pick contrasting colors in the descriptions of the route_color and route_text_color fields. -* trip_short_name, as proposed and tested in these threads: a and b. -* A fix for a minor error in the sample data included at the end of the document (giving stop S7 the parent_station S8). -* Added "agency_lang" information to the sample data at the end of the document, as suggested by Marcy during the comment period: [discussion](https://groups.google.com/forum/#!topic/gtfs-changes/5qP1kDUFqx0). -* Updated the link to OCTA's GTFS feed in the sidebar -* See [original summary](https://groups.google.com/forum/#!topic/gtfs-changes/cL1E4oKKpKw). - -#### February 26, 2009 - -* Removed most of the Google-specific feed submission instructions, since there are many other applications that consume GTFS data at this point. -* Fixed a broken link in the sidebar to Orange County OCTA's public feed. - -#### August 7, 2008 - -* Restored the stop_url field, which was accidentally omitted in the August 6 version -* Added agency_phone to sample data -* Added a mention of the data use agreement when submitting a feed to Google - -#### August 6, 2008 - -* Added transfers.txt file, allowing the feed publishers to provide hints on preferred transfer behavior ([original proposal](https://groups.google.com/forum/#!topic/gtfs-changes/cL1E4oKKpKw)) -* Added location_type and parent_station fields to stops.txt, allowing stop points to be grouped into stations ([original proposal](https://groups.google.com/forum/#!topic/gtfs-changes/ScGAyZ9a_yw)) -* Added agency_phone field for providing voice telephone number for an agency ([original proposal](https://groups.google.com/forum/#!topic/gtfs-changes/8Itt58ueyqA)) -* Added "Testing Your Feeds" section mentioning open-source testing tools -* Added clarifications about CSV format, agency_timezone, agency_lang, route_color, route_text_color, arrival_time, departure_time, calendar.txt vs. calendar_dates.txt, fare tables, and frequencies.txt -* Added link to feed history document, and corrected some public feed links -* Updated example images to depict the current Google Maps UI -* Updated/fixed sample data in document - -#### February 29, 2008 - -* Added the stop_code field in stops.txt to allow for the specification of rider-facing stop codes ([original proposal](https://groups.google.com/forum/#!topic/gtfs-changes/k9A95fYZexc)) -* Clarified the descriptions of route_short_name and route_long_name in routes.txt -* Clarified the descriptions of arrival_time and departure_time in stop_times.txt -* Fixed typos in the Sample Data section - -#### November 20, 2007 - -* Clarified block_id description -* Changed language to de-emphasize Google Transit (since non-Google applications are using GTFS, and transit routing is now an integrated feature of Google Maps), and to fix assorted typos -* Updated example screenshots to reflect the presentation of GTFS fields in the current Google Maps UI -* Updated the Google contact email address for transit data providers -* Updated formatting - -#### October 5, 2007 - -* Changed stop_sequence and shape_pt_sequence to allow for any increasing non-negative integers -* Clarified descriptions and fixed typos - -#### May 31, 2007 - -* Updated page style, made HTML cleaner and more accessible -* Added links to public feed examples and other useful sites -* Removed examples from individual field descriptions - -#### April 9, 2007 - -* Added section on [submitting a feed](https://developers.google.com/transit/google-transit#SubmitFeedToGoogle). -* Added the [Example Demo Transit Agency feed](https://developers.google.com/transit/gtfs/examples/gtfs-feed). -* Added note that calendar.txt can be omitted if all the service dates are defined in calendar_dates.txt. -* Made the agency_id field optional in feeds containing only one agency. This allows existing feeds without agency_id to remain valid. -* Added fuller specification of agency_url, stop_url, and route_url, and additional example values for those fields. -* Added 6 (Gondola) and 7 (Funicular) as valid route_type values. - -#### March 8, 2007 - -* Minor edit to move the stop_url field from stop_times.txt, where it was incorrectly specified in the Feb. 28 update, to stops.txt, where it belongs. - -#### March 5, 2007 - -* Minor edit to clarify the description of the route_long_name field. - -#### February 28, 2007 - -* Addition of frequencies.txt for headway-based schedule support. -* Multiple agencies now allowed in the the same feed. Also added new agency_id field in both agencies.txt and routes.txt that lets you specify which route is operated by which agency. -* Addition of per-route and per-stop URLs. -* Addition of direction_id field in trips.txt. -* Support for mid-trip headsign changes with addition of stop_headsign field in stop_times.txt. -* Support for route colors with addition of optional route_color and route_text_color in routes.txt. -* Removed the ability to specify stops using street addresses. The previous version of the spec allowed you to give the location of a transit stop using a street address in the stop_street, stop_city, stop_region, stop_postcode, and stop_country fields. Now stop locations must be given using stop_lat for latitude and stop_lon for longitude, which are more useful for most applications. -* Addition of cable car vehicle type for route_type field in routes.txt. -* See the original [Headway blog post](http://headwayblog.com/2007/03/02/google-feed-spec-update-2007-02/) summary of the changes. - -#### November 29, 2006 - -* Added support for trip shape information via shapes.txt -* Clarified the definition of stop_sequence -* Marked pickup_type and drop_off_type optional - -#### October 31, 2006 - -* Added support for fare information -* Removed dates from individual file names -* Changed the route_type value definitions -* Allowed for multiple feed files to be posted at the same time, as long as their service periods didn't overlap -* Fixed block_id in trips.txt so that it was correctly marked Optional -* Noted that column headers must be included - -#### September 29, 2006 - -* Minor edit to fix a couple errors in the examples. - -#### September 25, 2006 - -* Initial version. diff --git a/transit/gtfs/README.md b/transit/gtfs/README.md deleted file mode 100644 index 0b9b7d109..000000000 --- a/transit/gtfs/README.md +++ /dev/null @@ -1,5 +0,0 @@ -This directory contains GTFS Specification and documentation. - -### Quick links -- [Documentation](spec/en) -- [How to change the specification?](CHANGES.md) \ No newline at end of file diff --git a/transit/gtfs/spec/en/README.md b/transit/gtfs/spec/en/README.md deleted file mode 100644 index b86e258f5..000000000 --- a/transit/gtfs/spec/en/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# What is GTFS? - -The General Transit Feed Specification (GTFS) defines a common format for public transportation schedules and associated geographic information. GTFS "feeds" allow public transit agencies to publish their transit data and developers to write applications that consume that data in an interoperable way. - -## How do I start? - -1. Continue reading the overview below. -1. Take a look at the [example feeds](examples/). -1. Create your own feeds using the [reference](reference.md) as a guide. -1. Test your feed using [validation tools](tools.md). -1. Publish your feed. - -## Overview of a GTFS feed - -A GTFS feed is composed of a series of text files collected in a ZIP file. Each file models a particular aspect of transit information: stops, routes, trips, and other schedule data. The details of each file are defined in the [GTFS reference](reference.md). An example feed can be found in the [GTFS examples](examples/). A transit agency can produce a GTFS feed to share their public transit information with developers, who write tools that consume GTFS feeds to incorporate public transit information into their applications. GTFS can be used to power trip planners, time table publishers, and a variety of applications, too diverse to list here, that use public transit information in some way. - -## Making a Transit Feed Publicly Available - -Many applications are compatible with data in the GTFS format. The simplest way to make a feed public is to host it on a web server and publish an announcement that makes it available for use. - -Here are a few ways that interested software developers learn about public feeds: - -* A list of transit agencies who provide public feeds is available on the [TransitWiki.org "Publicly-accessible public transportation data" page](http://www.transitwiki.org/TransitWiki/index.php?title=Publicly-accessible_public_transportation_data). -* Several websites allows developers to subscribe to announcements about new and updated feeds, and serve as a registry of feeds: - * [Gtfs Data Exchange.com](http://www.gtfs-data-exchange.com/) - * [TransitFeeds.com](http://transitfeeds.com/) - * [Transit.land](https://transit.land/feed-registry/) - -## Submitting a Transit Feed to Google - -If you're at a public agency that oversees public transportation for your city, you can use the GTFS specification to provide schedules and geographic information to Google Maps and other Google applications that show transit information. For full details, please refer to the [Google Transit Partners Program website](http://maps.google.com/help/maps/mapcontent/transit/participate.html). - -## Getting Help - -To participate in discussions around GTFS and suggest changes and additions to the specification, join the [GTFS changes mailing list](http://groups.google.com/group/gtfs-changes). - -*Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.* \ No newline at end of file diff --git a/transit/gtfs/spec/en/community.md b/transit/gtfs/spec/en/community.md deleted file mode 100644 index e13c65c28..000000000 --- a/transit/gtfs/spec/en/community.md +++ /dev/null @@ -1,25 +0,0 @@ -## Community - -### Mailing Lists - -There are a number of mailing lists that can be good resources when you have questions about public transit data, software, formats like GTFS and GTFS-realtime, and other issues: - -* transitfeed: discussion of the open-source transitfeed project, as well of discussion of the GTFS specification and associated tools. -* gtfs-realtime: discussion of the GTFS-realtime specification. -* gtfs-changes: discussion of proposal for extending the GTFS specification, as outlined in the GTFS Changes document. -* transit-developers: general transit developer discussions. Many transit agencies also have their own developer mailing lists specific to the agency. For example: - * NYC MTA - * Portland, OR - * BART - San Francisco, CA - * MassDOT - -Check with your local transit agency to see if they have a mailing list of their own. - -## Other Resources - -* [TransitWiki.org "General Transit Feed Specification" page](http://www.transitwiki.org/TransitWiki/index.php?title=General_Transit_Feed_Specification) -* Public GTFS feed list - [TransitWiki.org "Publicly-accessible public transportation data" page](http://www.transitwiki.org/TransitWiki/index.php?title=Publicly-accessible_public_transportation_data). -* Several websites serve as a registry of feeds: - * [Gtfs Data Exchange.com](http://www.gtfs-data-exchange.com/) - * [TransitFeeds.com](http://transitfeeds.com/) - * [Transit.land](https://transit.land/feed-registry/) \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/README.md b/transit/gtfs/spec/en/examples/README.md deleted file mode 100644 index 0f5d73817..000000000 --- a/transit/gtfs/spec/en/examples/README.md +++ /dev/null @@ -1,130 +0,0 @@ -## Example GTFS Feed - -This example GTFS feed shows comma-delimited data samples for each file in a transit feed. The sample data files shown here aren't all related to each other. You can also [download a complete GTFS feed](sample-feed-1.zip) in final form to work with as well, or browse the individual files of that same feed online [here](sample-feed-1). - -### agency.txt - -~~~ -agency_id,agency_name,agency_url,agency_timezone,agency_phone,agency_lang -FunBus,The Fun Bus,http://www.thefunbus.org,America/Los_Angeles,(310) 555-0222,en -~~~ - -### stops.txt - -~~~ -stop_id,stop_name,stop_desc,stop_lat,stop_lon,stop_url,location_type,parent_station -S1,Mission St. & Silver Ave.,The stop is located at the southwest corner of the intersection.,37.728631,-122.431282,,, -S2,Mission St. & Cortland Ave.,The stop is located 20 feet south of Mission St.,37.74103,-122.422482,,, -S3,Mission St. & 24th St.,The stop is located at the southwest corner of the intersection.,37.75223,-122.418581,,, -S4,Mission St. & 21st St.,The stop is located at the northwest corner of the intersection.,37.75713,-122.418982,,, -S5,Mission St. & 18th St.,The stop is located 25 feet west of 18th St.,37.761829,-122.419382,,, -S6,Mission St. & 15th St.,The stop is located 10 feet north of Mission St.,37.766629,-122.419782,,, -S7,24th St. Mission Station,,37.752240,-122.418450,,,S8 -S8,24th St. Mission Station,,37.752240,-122.418450,http://www.bart.gov/stations/stationguide/stationoverview_24st.asp,1, -~~~ - -### routes.txt - -~~~ -route_id,route_short_name,route_long_name,route_desc,route_type -A,17,Mission,"The ""A"" route travels from lower Mission to Downtown.",3 -~~~ - -### trips.txt - -~~~ -route_id,service_id,trip_id,trip_headsign,block_id -A,WE,AWE1,Downtown,1 -A,WE,AWE2,Downtown,2 -~~~ - -### stop_times.txt - -~~~ -trip_id,arrival_time,departure_time,stop_id,stop_sequence,pickup_type,drop_off_type -AWE1,0:06:10,0:06:10,S1,1,0,0 -AWE1,,,S2,2,1,3 -AWE1,0:06:20,0:06:30,S3,3,0,0 -AWE1,,,S5,4,0,0 -AWE1,0:06:45,0:06:45,S6,5,0,0 -AWD1,0:06:10,0:06:10,S1,1,0,0 -AWD1,,,S2,2,0,0 -AWD1,0:06:20,0:06:20,S3,3,0,0 -AWD1,,,S4,4,0,0 -AWD1,,,S5,5,0,0 -AWD1,0:06:45,0:06:45,S6,6,0,0 -~~~ - -### calendar.txt - -~~~ -service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date -WE,0,0,0,0,0,1,1,20060701,20060731 -WD,1,1,1,1,1,0,0,20060701,20060731 -~~~ - -### calendar_dates.txt - -This example shows service exceptions for the Independence Day holiday in 2006. On Monday July 3, 2006, regular weekday service (`service_id=WD`) is interrupted (`exception_type=2`). Instead, weekend service (`service_id=WE`) runs on that date (`exception_type=1`). The same change applies on Tuesday July 4, as well. - -~~~ -service_id,date,exception_type -WD,20060703,2 -WE,20060703,1 -WD,20060704,2 -WE,20060704,1 -~~~ - -### fare_attributes.txt - -~~~ -fare_id,price,currency_type,payment_method,transfers,transfer_duration -1,0.00,USD,0,0,0 -2,0.50,USD,0,0,0 -3,1.50,USD,0,0,0 -4,2.00,USD,0,0,0 -5,2.50,USD,0,0,0 -~~~ - -### fare_rules.txt - -~~~ -fare_id,route_id,origin_id,destination_id,contains_id -a,TSW,1,1, -a,TSE,1,1, -a,GRT,1,1, -a,GRJ,1,1, -a,SVJ,1,1, -a,JSV,1,1, -a,GRT,2,4, -a,GRJ,4,2, -b,GRT,3,3, -c,GRT,,,6 -~~~ - -### shapes.txt - -~~~ -shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled -A_shp,37.61956,-122.48161,1,0 -A_shp,37.64430,-122.41070,2,6.8310 -A_shp,37.65863,-122.30839,3,15.8765 -~~~ - -### frequencies.txt - -~~~ -trip_id,start_time,end_time,headway_secs -AWE1,05:30:00,06:30:00,300 -AWE1,06:30:00,20:30:00,180 -AWE1,20:30:00,28:00:00,420 -~~~ - -### transfers.txt - -~~~ -from_stop_id,to_stop_id,transfer_type,min_transfer_time -S6,S7,2,300 -S7,S6,3, -S23,S7,1, -~~~ diff --git a/transit/gtfs/spec/en/examples/sample-feed-1.zip b/transit/gtfs/spec/en/examples/sample-feed-1.zip deleted file mode 100644 index 79819e21ad51d7b0dcf0aeb51a298437df4bdfc3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3217 zcmZ{m3pAAL8pppGmzc!3rnE^W83xld<5IH8WS6DlTib5Yz3J|5a3=>0? z66^dH9;3#1Gv*S&DcRPx6|xX?$Nq#-??W;E$PAI>AK=wF9rB8tP9neEt{L} zk||l3C~s$*)R62@dSoy|SeP-LDa>#>(Q{3KcsQqBx2I*@_7<$z$`#7FD#|PQ%4XfI zkJ55Nn{v1zUSO9Ao#@d-i`;9;%5)Fw4L^6RiR~U1!DO)z$(gkej z4VFCEbPtou@?`ROT=vdjqDdyj)l6hB-?6BmF&?xlF ze(jg~sV5n&!xD7vY6**IBiiK(S@Q9iZQ<(mKB9_$7TA1Vrxtf=sO=B(qwHsm!K$U# zT@Uwve}S6Q77Mg}grZETK-Uhir2p2&4faJ8BN@oriYSI|%X$o-CZ-#fy*53i&GZviJ`+YJd{O9^QS0fWLwF&- z=1q#)oRV6gWMiP0YY0%`ih>{+SP7RE7!1xf8zJQ_kitMn(ZRP7;=%F3>rn~X3HrA? z=ntrO>>`OI2YJUfd7T$Yjz^Pfqb!cE3hpS8lH%L6v`VxQD~ZH@?kA}Pa&&v1d!8Fw zc1xQ?b>`_KVoq&x+AQ&h(RR&@mQHBTReX_0C@ym2o&K@rQkm*ijFW5aQ&k4iME^Qd zvlB@I=UyaB(0dIC-vori6Up_T*Hx^^e9iP!bIf5P)@mv$q!m@<<#T}VEnD}hD6umu z+Q^wrCTTMKpOY#5WA~0t)c~xxka@ZmoS;P3h&;&010s5f=;keqEO)vuD}yi34wESU*fnF(Z>} zw&`Xz(UAk64>~68m9ZBdBpa~c4-fKY1|XVM0h;x1WV7zt5NzOK$BS>k*bWBC*`*oH zgh|*3?qjm|?ci!V;nr5v;I5z5DkD(VQN$2cE(BF}zi?4K1yuNe=K9*<)uSy&etqK|x+2N!es1zq?sCNaH%B=UjF}U{w z-?GQQ>ZGTh@2*u%ou0(gL{kR|!(l7?Zn;|4pQrZ|yVX=;O|Edz1`|&yK_?}#VcyAW zTm&!5RzC_dnDTrWVdfoEH{m7oLrY++Qfq!%r)p=32gW;w@2oCgrLkw}3MNU5wX3?e?NIMTO#(#>Avy@mcCLxGVb?p zwsxRM!pGWv^)jJ26jjTx-*i8%3StHOwlRx$ih;WQJq(tjUB7Ksby;; z2zAP64RWS^wP{HBy#oW+s~bt>YW+i#g|{OIFAVk+_MM^K&AxhL_*{+bXWN%_XG;T; zlg5iialeoc`-dIVG*OP}LzlyFY<%~KX1UGGO55Hs&5WwgVjl}nyi%DPb~oT+=(dgr z?x33CQwIZg1$WKA!*T{qigg7fJvi`A(kvJFMyJB^igjYpUDwp67E#5%94 z#2&0Y*gMYtS{I*#^++*05fpA^qHBLhA(^zr``oGU9N9QZ;salU#O1q`3o72!GrmYS zjq@p@H!lsln3ezeqSG_r5IRBWK&|u617`B)Sg~X2`fcRjs-d$eSobZPYnbz0~&I5cB%2Tb!h&>FZcz@iXs;e+`?wk0K%E*(Y0#!PAUMT&H6>0DZA zDJTDIS|pIAo!q$%zalZAx>{E#!P$PN{mY&mp41R={c^t2YkZLYvfD!&bQG*~+E-$z zxhevmxJ$OfA%|QNnt!>oH`#*wgtNiRMD&bEA3j*aqY1r5d7zc4Dd^fwNFr=rWvo(@ z6IZ;!TAj~&KNPB(dsO|A&~p=7h2>WuJnWODpTToVT6H)V`>s*deahE!U*)P4x2byN z-g9ZcH`3LbRikX5C9YPq9k_V;Lp^2YX|&#twrzA$AHxoXUM})aIcpgx3Iu_wKxZT2 zCuHgpn@wHLp%A#T<{*nB5fYLQAoBwfz`y}%4)af`1&J{QlK#dZGYo*i8DMT5SJF&|?_1Fbn_^90nGW7W*-h zlpzAmb7ug7-FYEov9}>1Nx*=RP6r^c(=CK7_ADf18ip)zFaUxbY$0gzb%_Kui_e1o qcXPC8(~lRnE31AGWt3Vw>9czYz_xBmiKz-WR1 diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/agency.txt b/transit/gtfs/spec/en/examples/sample-feed-1/agency.txt deleted file mode 100644 index eb24555d0..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/agency.txt +++ /dev/null @@ -1,2 +0,0 @@ -agency_id,agency_name,agency_url,agency_timezone -DTA,Demo Transit Authority,http://google.com,America/Los_Angeles \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/calendar.txt b/transit/gtfs/spec/en/examples/sample-feed-1/calendar.txt deleted file mode 100644 index b95f2a7c6..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/calendar.txt +++ /dev/null @@ -1,3 +0,0 @@ -service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date -FULLW,1,1,1,1,1,1,1,20070101,20101231 -WE,0,0,0,0,0,1,1,20070101,20101231 \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/calendar_dates.txt b/transit/gtfs/spec/en/examples/sample-feed-1/calendar_dates.txt deleted file mode 100644 index 51c495bf8..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/calendar_dates.txt +++ /dev/null @@ -1,2 +0,0 @@ -service_id,date,exception_type -FULLW,20070604,2 \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/fare_attributes.txt b/transit/gtfs/spec/en/examples/sample-feed-1/fare_attributes.txt deleted file mode 100644 index 9c3b421fc..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/fare_attributes.txt +++ /dev/null @@ -1,3 +0,0 @@ -fare_id,price,currency_type,payment_method,transfers,transfer_duration -p,1.25,USD,0,0, -a,5.25,USD,0,0, \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/fare_rules.txt b/transit/gtfs/spec/en/examples/sample-feed-1/fare_rules.txt deleted file mode 100644 index acf470ddc..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/fare_rules.txt +++ /dev/null @@ -1,5 +0,0 @@ -fare_id,route_id,origin_id,destination_id,contains_id -p,AB,,, -p,STBA,,, -p,BFC,,, -a,AAMV,,, \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/frequencies.txt b/transit/gtfs/spec/en/examples/sample-feed-1/frequencies.txt deleted file mode 100644 index 47941ef36..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/frequencies.txt +++ /dev/null @@ -1,12 +0,0 @@ -trip_id,start_time,end_time,headway_secs -STBA,6:00:00,22:00:00,1800 -CITY1,6:00:00,7:59:59,1800 -CITY2,6:00:00,7:59:59,1800 -CITY1,8:00:00,9:59:59,600 -CITY2,8:00:00,9:59:59,600 -CITY1,10:00:00,15:59:59,1800 -CITY2,10:00:00,15:59:59,1800 -CITY1,16:00:00,18:59:59,600 -CITY2,16:00:00,18:59:59,600 -CITY1,19:00:00,22:00:00,1800 -CITY2,19:00:00,22:00:00,1800 \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/routes.txt b/transit/gtfs/spec/en/examples/sample-feed-1/routes.txt deleted file mode 100644 index 398ba162c..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/routes.txt +++ /dev/null @@ -1,6 +0,0 @@ -route_id,agency_id,route_short_name,route_long_name,route_desc,route_type,route_url,route_color,route_text_color -AB,DTA,10,Airport - Bullfrog,,3,,, -BFC,DTA,20,Bullfrog - Furnace Creek Resort,,3,,, -STBA,DTA,30,Stagecoach - Airport Shuttle,,3,,, -CITY,DTA,40,City,,3,,, -AAMV,DTA,50,Airport - Amargosa Valley,,3,,, \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/shapes.txt b/transit/gtfs/spec/en/examples/sample-feed-1/shapes.txt deleted file mode 100644 index aa62a022a..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/shapes.txt +++ /dev/null @@ -1 +0,0 @@ -shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/stop_times.txt b/transit/gtfs/spec/en/examples/sample-feed-1/stop_times.txt deleted file mode 100644 index 90c649cf4..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/stop_times.txt +++ /dev/null @@ -1,29 +0,0 @@ -trip_id,arrival_time,departure_time,stop_id,stop_sequence,stop_headsign,pickup_type,drop_off_type,shape_dist_traveled -STBA,6:00:00,6:00:00,STAGECOACH,1,,,, -STBA,6:20:00,6:20:00,BEATTY_AIRPORT,2,,,, -CITY1,6:00:00,6:00:00,STAGECOACH,1,,,, -CITY1,6:05:00,6:07:00,NANAA,2,,,, -CITY1,6:12:00,6:14:00,NADAV,3,,,, -CITY1,6:19:00,6:21:00,DADAN,4,,,, -CITY1,6:26:00,6:28:00,EMSI,5,,,, -CITY2,6:28:00,6:30:00,EMSI,1,,,, -CITY2,6:35:00,6:37:00,DADAN,2,,,, -CITY2,6:42:00,6:44:00,NADAV,3,,,, -CITY2,6:49:00,6:51:00,NANAA,4,,,, -CITY2,6:56:00,6:58:00,STAGECOACH,5,,,, -AB1,8:00:00,8:00:00,BEATTY_AIRPORT,1,,,, -AB1,8:10:00,8:15:00,BULLFROG,2,,,, -AB2,12:05:00,12:05:00,BULLFROG,1,,,, -AB2,12:15:00,12:15:00,BEATTY_AIRPORT,2 -BFC1,8:20:00,8:20:00,BULLFROG,1 -BFC1,9:20:00,9:20:00,FUR_CREEK_RES,2 -BFC2,11:00:00,11:00:00,FUR_CREEK_RES,1 -BFC2,12:00:00,12:00:00,BULLFROG,2 -AAMV1,8:00:00,8:00:00,BEATTY_AIRPORT,1 -AAMV1,9:00:00,9:00:00,AMV,2 -AAMV2,10:00:00,10:00:00,AMV,1 -AAMV2,11:00:00,11:00:00,BEATTY_AIRPORT,2 -AAMV3,13:00:00,13:00:00,BEATTY_AIRPORT,1 -AAMV3,14:00:00,14:00:00,AMV,2 -AAMV4,15:00:00,15:00:00,AMV,1 -AAMV4,16:00:00,16:00:00,BEATTY_AIRPORT,2 diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/stops.txt b/transit/gtfs/spec/en/examples/sample-feed-1/stops.txt deleted file mode 100644 index 8ed623d08..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/stops.txt +++ /dev/null @@ -1,10 +0,0 @@ -stop_id,stop_name,stop_desc,stop_lat,stop_lon,zone_id,stop_url -FUR_CREEK_RES,Furnace Creek Resort (Demo),,36.425288,-117.133162,, -BEATTY_AIRPORT,Nye County Airport (Demo),,36.868446,-116.784582,, -BULLFROG,Bullfrog (Demo),,36.88108,-116.81797,, -STAGECOACH,Stagecoach Hotel & Casino (Demo),,36.915682,-116.751677,, -NADAV,North Ave / D Ave N (Demo),,36.914893,-116.76821,, -NANAA,North Ave / N A Ave (Demo),,36.914944,-116.761472,, -DADAN,Doing Ave / D Ave N (Demo),,36.909489,-116.768242,, -EMSI,E Main St / S Irving St (Demo),,36.905697,-116.76218,, -AMV,Amargosa Valley (Demo),,36.641496,-116.40094,, \ No newline at end of file diff --git a/transit/gtfs/spec/en/examples/sample-feed-1/trips.txt b/transit/gtfs/spec/en/examples/sample-feed-1/trips.txt deleted file mode 100644 index 7ee117edc..000000000 --- a/transit/gtfs/spec/en/examples/sample-feed-1/trips.txt +++ /dev/null @@ -1,12 +0,0 @@ -route_id,service_id,trip_id,trip_headsign,direction_id,block_id,shape_id -AB,FULLW,AB1,to Bullfrog,0,1, -AB,FULLW,AB2,to Airport,1,2, -STBA,FULLW,STBA,Shuttle,,, -CITY,FULLW,CITY1,,0,, -CITY,FULLW,CITY2,,1,, -BFC,FULLW,BFC1,to Furnace Creek Resort,0,1, -BFC,FULLW,BFC2,to Bullfrog,1,2, -AAMV,WE,AAMV1,to Amargosa Valley,0,, -AAMV,WE,AAMV2,to Airport,1,, -AAMV,WE,AAMV3,to Amargosa Valley,0,, -AAMV,WE,AAMV4,to Airport,1,, \ No newline at end of file diff --git a/transit/gtfs/spec/en/reference.md b/transit/gtfs/spec/en/reference.md deleted file mode 100644 index 8d1387af3..000000000 --- a/transit/gtfs/spec/en/reference.md +++ /dev/null @@ -1,429 +0,0 @@ -## General Transit Feed Specification Reference - -**Revised August 4, 2016. 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. - -## Table of Contents - -1. [Term Definitions](#term-definitions) -2. [Feed Files](#feed-files) -3. [File Requirements](#file-requirements) -4. [Field Definitions](#field-definitions) - - [agency.txt](#agencytxt) - - [stops.txt](#stopstxt) - - [routes.txt](#routestxt) - - [trips.txt](#tripstxt) - - [stop\_times.txt](#stop_timestxt) - - [calendar.txt](#calendartxt) - - [calendar\_dates.txt](#calendar_datestxt) - - [fare\_attributes.txt](#fare_attributestxt) - - [fare\_rules.txt](#fare_rulestxt) - - [shapes.txt](#shapestxt) - - [frequencies.txt](#frequenciestxt) - - [transfers.txt](#transferstxt) - - [feed\_info.txt](#feed_infotxt) - -## Term Definitions - -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. -* **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. - -## Feed Files - -This specification defines the following files along with their associated content: - -| 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. | -| [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) | **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. | -| [calendar_dates.txt](#calendar_datestxt) | Optional | Exceptions for the service IDs defined in the [calendar.txt](#calendartxt) file. If [calendar.txt](#calendartxt) includes ALL dates of service, this file may be specified instead of [calendar.txt](#calendartxt). | -| [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. | -| [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. | - -## File Requirements - -The following requirements apply to the format and contents of your 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 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. -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. - -## Field Definitions - -### agency.txt - -File: **Required** - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| agency_id | Optional | The **agency_id** field is an ID that uniquely identifies a transit agency. A transit feed may represent data from more than one agency. The **agency_id** is dataset unique. This field is optional for transit feeds that only contain data for a single agency. | -| agency_name | Required | The **agency_name** field contains the full name of the transit agency. Google Maps will display this name. | -| agency_url | Required | The **agency_url** field contains the URL of the transit agency. The value must be 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. | -| agency_timezone | Required | The **agency_timezone** field contains the timezone where the transit agency is located. Timezone names never contain the space character but may contain an underscore. Please refer to http://en.wikipedia.org/wiki/List_of_tz_zones for a list of valid values. If multiple agencies are specified in the feed, each must have the same agency_timezone. | -| agency_lang | Optional | The **agency_lang field** contains a two-letter ISO 639-1 code for the primary language used by this transit agency. The language code is case-insensitive (both en and EN are accepted). This setting defines capitalization rules and other language-specific settings for all text contained in this transit agency's feed. Please refer to http://www.loc.gov/standards/iso639-2/php/code_list.php for a list of valid values. | -| agency_phone | 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 | 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. The value must be 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. | -| agency_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. | - -### stops.txt - -File: **Required** - -| Field Name | Required | Details | | | -| ------ | ------ | ------ | ------ | ------ | -| stop_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. The **stop_id** is used by systems as an internal identifier of this record (e.g., primary key in database), and therefore the **stop_id** must be dataset unique. | | | -| stop_code | 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 | **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 | 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 | **Required** | The **stop_lat** field contains the latitude of a stop, station, or station entrance. The field value must be a valid WGS 84 latitude. | | | -| stop_lon | **Required** | The **stop_lon** field contains the longitude of a stop, station, or station entrance. The field value must be a valid WGS 84 longitude value from -180 to 180. | | | -| zone_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 | 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. The value must be 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. | | | -| location_type | 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 | 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. | | | -| | | **This stop ID represents...** | **This entry's location type...** | **This entry's parent_station field contains...** | -| | | A stop located inside a station. | 0 or blank | The stop ID of the station where this stop is located. The stop referenced by parent_station must have location_type=1. | -| | | A stop located outside a station. | 0 or blank | A blank value. The parent_station field doesn't apply to this stop. | -| | | A station. | 1 | A blank value. Stations can't contain other stations. | -| stop_timezone | Optional | The **stop_timezone** field contains the timezone in which this stop, station, or station entrance is located. Please refer to [Wikipedia List of Timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of valid values. 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 | 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 | | | - -### routes.txt - -File: **Required** - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| route_id | **Required** | The **route_id** field contains an ID that uniquely identifies a route. The route_id is dataset unique. | -| agency_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 | **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 | **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 | 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 | **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 | Optional | The **route_url** field contains the URL of a web page about that particular route. This should be different from the agency_url. The value must be 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. | -| route_color | Optional | In systems that have colors assigned to routes, the **route_color** field defines a color that corresponds to a route. The color must be provided as a six-character hexadecimal number, for example, 00FFFF. 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 | 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. The color must be provided as a six-character hexadecimal number, for example, FFD700. 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. | - -### trips.txt - -File: **Required** - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| route_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 | **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 | **Required** | The **trip_id** field contains an ID that identifies a trip. The **trip_id** is dataset unique. | -| trip_headsign | 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 the **stop_headsign** field in [stop_times.txt](#stop_timestxt). | -| trip_short_name | 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 | 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 | 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 | 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 | 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 | 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 - -The example below is valid, with distinct blocks every day of the week. - -| route_id | trip_id | service_id | block_id | *(first stop time)* | *(last stop time)* | -|----------|---------|--------------------------------|----------|-----------------------------------------|-------------------------| -| red | trip_1 | mon-tues-wed-thurs-fri-sat-sun | red_loop | 22:00:00 | 22:55:00 | -| red | trip_2 | fri-sat-sun | red_loop | 23:00:00 | 23:55:00 | -| red | trip_3 | fri-sat | red_loop | 24:00:00 | 24:55:00 | -| red | trip_4 | mon-tues-wed-thurs | red_loop | 20:00:00 | 20:50:00 | -| 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. - -### stop_times.txt - -File: **Required** - -| Field Name | Required | Details | | -| ------ | ------ | ------ | ------ | -| trip_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 | **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 | **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 | **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 | **Required** | The **stop_sequence** field identifies the order of the stops for a particular trip. The values for **stop_sequence** must be non-negative integers, and they 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 | 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 | 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 | 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 | 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 | 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. | | - -### calendar.txt - -File: **Required** - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| service_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 | **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 | **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 | **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 | **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 | **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 | **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 | **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 | **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 | **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. | - -### calendar_dates.txt - -File: **Optional** - -The calendar_dates table allows you to explicitly activate or disable service IDs by date. You can use it 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 accomodate 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. - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| service_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 | **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 | **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. | - -### fare_attributes.txt - -File: **Optional** - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| fare_id | **Required** | The **fare_id** field contains an ID that uniquely identifies a fare class. The **fare_id** is dataset unique. | -| price | **Required** | The **price** field contains the fare price, in the unit specified by **currency_type**. | -| currency_type | **Required** | The **currency_type** field defines the currency used to pay the fare. Please use the ISO 4217 alphabetical currency codes which can be found at the following URL: http://en.wikipedia.org/wiki/ISO_4217. | -| payment_method | **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 | **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 | 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 | 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_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: - -* 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. - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| fare_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 | 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 | 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 | 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 | 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. | - -### 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. - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| shape_id | **Required** | The **shape_id** field contains an ID that uniquely identifies a shape. | -| shape_pt_lat | **Required** | The **shape_pt_lat** field associates a shape point's latitude with a shape ID. The field value must be a valid WGS 84 latitude. 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 | **Required** | The **shape_pt_lon** field associates a shape point's longitude with a shape ID. The field value must be a valid WGS 84 longitude value from -180 to 180. 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 | **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 be non-negative integers, and they 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 | 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` | - -### 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. - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| trip_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 | **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 | **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 | **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 | 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**. | - -### 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. - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| from_stop_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 | **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 | **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 | 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. | - -### 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. - -| Field Name | Required | Details | -| ------ | ------ | ------ | -| feed_publisher_name | **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 | **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).) The value must be 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_lang | Required | The **feed_lang** field contains a IETF BCP 47 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. 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/. | -| feed_start_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 are given as dates in YYYYMMDD format as for [calendar.txt](#calendartxt), or 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 | Optional | (see above) | -| feed_version | 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. | \ No newline at end of file diff --git a/transit/gtfs/spec/en/style-guide.md b/transit/gtfs/spec/en/style-guide.md deleted file mode 100644 index ab06b95e3..000000000 --- a/transit/gtfs/spec/en/style-guide.md +++ /dev/null @@ -1,33 +0,0 @@ -## GTFS Style Guide - -The GTFS specification provides a lot of flexibility in how a physical transit system is modeled. What is the best approach? In general, it is a good idea to keep the following guidelines in mind when developing a feed. - -### Route Organization - -The entries in [routes.txt](reference.md#routes.txt) should typically have the same organization as the physical routes communicated to riders by an agency. As an example, an agency will often first group their timetables by route when presenting them on a website or in a printed booklet. The entries in routes.txt should generally have a one-to-one correspondence to the timetable routes. It can be tempting for an agency to break a physical route into multiple entries in routes.txt in order to represent different route variations, such as direction of travel, but the preferred approach is to instead use features of [trips.txt](reference.md#trips.txt) to model those variations. Multiple entries in routes.txt with the same route short name or route long name are often an indication that routes have been needlessly subdivided. - -Do: - -~~~ -**routes.txt** -route_id,route_short_name,route_long_name,route_type -R10,10,Airport - Downtown,3 -~~~ - -~~~ -**trips.txt** -route_id,trip_id,trip_headsign,direction_id -R10,T-10-1,Airport,0 -R10,T-10-2,Downtown,1 -~~~ - -Don't: - -~~~ -**routes.txt** -route_id,route_short_name,route_long_name,route_type -R10-in,10,To Downtown,3 -R10-out,10,To Airport,3 -R20-in,20,To Downtown,3 -R20-out,20,To University,3 -~~~ \ No newline at end of file diff --git a/transit/gtfs/spec/en/tools.md b/transit/gtfs/spec/en/tools.md deleted file mode 100644 index bb1239378..000000000 --- a/transit/gtfs/spec/en/tools.md +++ /dev/null @@ -1,8 +0,0 @@ -## Tools - -### Testing Your GTFS Feeds - -Two Open Source tools are available for testing feeds in the GTFS format: - -* Use the [feedvalidator tool](https://github.com/google/transitfeed/wiki/FeedValidator) to verify that your feed data file matches the specification defined in this document. -* Use the [schedule_viewer application](https://github.com/google/transitfeed/wiki/ScheduleViewer) to see your feed data represented on a map. This is not representative of how your data will look in other applications; it is a basic tool for testing. Examine routes and schedules to ensure that the data feed correctly represents your system. \ No newline at end of file From 75829ddf7290a9a575b28c3d06b36a772e9c1861 Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Thu, 13 Jul 2017 11:53:23 +1000 Subject: [PATCH 08/10] Revert Spanish anchor fixes. This is in PR #67. --- gtfs-realtime/spec/es/reference.md | 96 +++++++++++++++--------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/gtfs-realtime/spec/es/reference.md b/gtfs-realtime/spec/es/reference.md index 956c85d15..3a519ab8e 100644 --- a/gtfs-realtime/spec/es/reference.md +++ b/gtfs-realtime/spec/es/reference.md @@ -11,14 +11,14 @@ Las especificaciones de la versión 1.0 del feed se abordan y documentan en este ## Índice de elementos -* [FeedMessage](#mensaje-feedmessage) - * [FeedHeader](#mensaje-feedheader) - * [Incrementality](#enum-incrementality) - * [FeedEntity](#mensaje-feedentity) - * [TripUpdate](#mensaje-tripupdate) - * [TripDescriptor](#mensaje-tripdescriptor) - * [ScheduleRelationship](#enum-schedulerelationship-1) - * [VehicleDescriptor](#mensaje-vehicledescriptor) +* [FeedMessage](#FeedMessage) + * [FeedHeader](#FeedHeader) + * [Incrementality](#Incrementality) + * [FeedEntity](#FeedEntity) + * [TripUpdate](#TripUpdate) + * [TripDescriptor](#TripDescriptor) + * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) + * [VehicleDescriptor](#VehicleDescriptor) * [CarriageDescriptor](#mensaje-carriagedescriptor) * [OccupancyStatus](#enum-occupancystatus) * [WheelchairAccessible](#enum-wheelchairaccessible) @@ -26,22 +26,22 @@ Las especificaciones de la versión 1.0 del feed se abordan y documentan en este * [WifiAvailability](#enum-wifiavailability) * [AirConditioning](#enum-airconditioning) * [BicyclesAllowed](#enum-bicyclesallowed) - * [StopTimeUpdate](#mensaje-stoptimeupdate) - * [StopTimeEvent](#mensaje-stoptimeevent) - * [ScheduleRelationship](#enum-schedulerelationship) - * [VehiclePosition](#mensaje-vehicleposition) - * [TripDescriptor](#mensaje-tripdescriptor) - * [ScheduleRelationship](#enum-schedulerelationship-1) - * [Position](#mensaje-position) - * [Alert](#mensaje-alert) - * [TimeRange](#mensaje-timerange) - * [EntitySelector](#mensaje-entitySelector) - * [TripDescriptor](#mensaje-tripdescriptor) - * [ScheduleRelationship](#enum-schedulerelationship-1) - * [Cause](#enum-cause) - * [Effect](#enum-effect) - * [TranslatedString](#mensaje-translatedstring) - * [Translation](#mensaje-translation) + * [StopTimeUpdate](#StopTimeUpdate) + * [StopTimeEvent](#StopTimeEvent) + * [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) + * [VehiclePosition](#VehiclePosition) + * [TripDescriptor](#TripDescriptor) + * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) + * [Position](#Position) + * [Alert](#Alert) + * [TimeRange](#TimeRange) + * [EntitySelector](#EntitySelector) + * [TripDescriptor](#TripDescriptor) + * [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) + * [Cause](#Cause) + * [Effect](#Effect) + * [TranslatedString](#TranslatedString) + * [Translation](#Translation) # Elementos @@ -59,8 +59,8 @@ Un feed depende de algunas configuraciones externas: | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **header** | [FeedHeader](#mensaje-feedheader) | obligatorio | Metadatos sobre este feed y mensaje del feed | -| **entity** | [FeedEntity](#mensaje-feedentity) | repetido | Contenido del feed | +| **header** | [FeedHeader](#FeedHeader) | obligatorio | Metadatos sobre este feed y mensaje del feed | +| **entity** | [FeedEntity](#FeedEntity) | repetido | Contenido del feed | ## _mensaje_ FeedHeader @@ -71,7 +71,7 @@ Metadatos sobre un feed, incluido en los mensajes del feed | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| | **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Especificación de la versión del feed. La versión actual es 1.0. | -| **incrementality** | [Incrementality](#enum-incrementality) | opcional | +| **incrementality** | [Incrementality](#Incrementality) | opcional | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Esta marca de tiempo identifica el momento en que se ha creado el contenido de este feed (en la hora del servidor). En la hora de POSIX (es decir, cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Para evitar el desvío de tiempos entre los sistemas que producen y que consumen información en tiempo real, se recomienda derivar la marca de tiempo desde un servidor de tiempo. Es absolutamente aceptable usar servidores de estrato 3 o, incluso, inferiores, porque las diferencias de tiempo de hasta un par de segundos son tolerables. | ## _enum._ Incrementality @@ -98,9 +98,9 @@ La definición (o actualización) de una entidad en el feed de transporte públi |------------------------|------------|--------------------|-------------------| | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | obligatorio | Identificador único del feed para esta entidad. Los identificadores se usan solamente para proporcionar soporte de incrementalidad. Las entidades reales a las que hace referencia el feed deben especificarse mediante selectores explícitos (ver EntitySelector más adelante para obtener más información). | | **is_deleted** | [bool](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Establece si esta entidad debe eliminarse. Es relevante solo para las búsquedas incrementales. | -| **trip_update** | [TripUpdate](#mensaje-tripupdate) | opcional | Datos sobre las demoras de salida en tiempo real de un viaje. | -| **vehicle** | [VehiclePosition](#mensaje-vehicleposition) | opcional | Datos sobre la posición en tiempo real de un vehículo. | -| **alert** | [Alert](#mensaje-alert) | opcional | Datos sobre las alertas en tiempo real. | +| **trip_update** | [TripUpdate](#TripUpdate) | opcional | Datos sobre las demoras de salida en tiempo real de un viaje. | +| **vehicle** | [VehiclePosition](#VehiclePosition) | opcional | Datos sobre la posición en tiempo real de un vehículo. | +| **alert** | [Alert](#Alert) | opcional | Datos sobre las alertas en tiempo real. | ## _mensaje_ TripUpdate @@ -120,9 +120,9 @@ Ten en cuenta que la actualización puede describir un viaje que ya se ha comple | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **trip** | [TripDescriptor](#mensaje-tripdescriptor) | obligatorio | El viaje al cual se aplica este mensaje. Puede haber una entidad de TripUpdate, como máximo, para cada instancia de viaje real. Si no hay ninguna, entonces no habrá información de predicciones disponible. *No* significa que el viaje se está realizando de acuerdo con la programación. | +| **trip** | [TripDescriptor](#TripDescriptor) | obligatorio | El viaje al cual se aplica este mensaje. Puede haber una entidad de TripUpdate, como máximo, para cada instancia de viaje real. Si no hay ninguna, entonces no habrá información de predicciones disponible. *No* significa que el viaje se está realizando de acuerdo con la programación. | | **vehicle** | [VehicleDescriptor](#VehicleDescriptor) | opcional | Información adicional sobre el vehículo con el cual se está realizando este viaje. | -| **stop_time_update** | [StopTimeUpdate](#mensaje-stoptimeupdate) | repetido | Las actualizaciones de StopTimes para el viaje (futuras, como las predicciones, y, en algunos casos, pasadas, es decir, aquellas que ya ocurrieron). Las actualizaciones deben ordenarse por secuencia de parada y deben aplicarse a todas las siguientes paradas del viaje hasta la próxima especificada. | +| **stop_time_update** | [StopTimeUpdate](#StopTimeUpdate) | repetido | Las actualizaciones de StopTimes para el viaje (futuras, como las predicciones, y, en algunos casos, pasadas, es decir, aquellas que ya ocurrieron). Las actualizaciones deben ordenarse por secuencia de parada y deben aplicarse a todas las siguientes paradas del viaje hasta la próxima especificada. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Momento en el que se midió el progreso en tiempo real del vehículo. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). | ## _mensaje_ StopTimeEvent @@ -144,7 +144,7 @@ La incertidumbre se aplica de la misma forma tanto al tiempo como a la demora. L ## _mensaje_ StopTimeUpdate -La actualización en tiempo real para los eventos de llegada o de salida para una determinada parada de un viaje. Consulta el debate general de las actualizaciones de tiempos de parada en la documentación de [TripDescriptor](#mensaje-tripdescriptor) y [del tipo de feed de actualizaciones de viaje](./trip-updates). +La actualización en tiempo real para los eventos de llegada o de salida para una determinada parada de un viaje. Consulta el debate general de las actualizaciones de tiempos de parada en la documentación de [TripDescriptor](#TripDescriptor) y [del tipo de feed de actualizaciones de viaje](./trip-updates). Las actualizaciones se pueden proporcionar tanto para eventos pasados como futuros. El productor tiene permitido, aunque no está obligado, a desestimar los eventos pasados. La actualización está vinculada a una parada específica sea a través de stop_sequence o de stop_id, de manera que uno de estos campos debe definirse, necesariamente. @@ -155,9 +155,9 @@ Las actualizaciones se pueden proporcionar tanto para eventos pasados como futur |------------------------|------------|--------------------|-------------------| | **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Debe ser la misma que la de stop_times.txt en el feed GTFS correspondiente. | | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. | -| **arrival** | [StopTimeEvent](#mensaje-stoptimeevent) | opcional | -| **departure** | [StopTimeEvent](#mensaje-stoptimeevent) | opcional | -| **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | opcional | La relación predeterminada es SCHEDULED. | +| **arrival** | [StopTimeEvent](#StopTimeEvent) | opcional | +| **departure** | [StopTimeEvent](#StopTimeEvent) | opcional | +| **schedule_relationship** | [ScheduleRelationship](#ScheduleRelationship_StopTimeUpdate) | opcional | La relación predeterminada es SCHEDULED. | ## _enum._ ScheduleRelationship @@ -179,9 +179,9 @@ Información de posicionamiento en tiempo real para un vehículo dado | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **trip** | [TripDescriptor](#mensaje-tripdescriptor) | opcional | El viaje que está haciendo este vehículo. Puede estar vacío o parcialmente vacío si el vehículo no puede identificarse con una instancia de viaje dada. | +| **trip** | [TripDescriptor](#TripDescriptor) | opcional | El viaje que está haciendo este vehículo. Puede estar vacío o parcialmente vacío si el vehículo no puede identificarse con una instancia de viaje dada. | | **vehicle** | [VehicleDescriptor](#VehicleDescriptor) | opcional | Información adicional sobre el vehículo que está realizando el viaje. Cada entrada debe tener un ID de vehículo **único**. | -| **position** | [Position](#mensaje-position) | opcional | Posición actual de este vehículo. | +| **position** | [Position](#Position) | opcional | Posición actual de este vehículo. | | **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El índice de la secuencia de parada de la parada actual. El significado de current_stop_sequence (es decir, la parada a la que hace referencia) está determinado por current_status. Si falta el valor en current_status, se asume IN_TRANSIT_TO. | | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | Identifica la parada actual. El valor debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. | | **current_status** | [VehicleStopStatus](#VehicleStopStatus) | opcional | El estado exacto del vehículo con respecto a la parada actual. Se ignora si falta el valor en current_stop_sequence. | @@ -220,13 +220,13 @@ Una alerta que indica que existe algún tipo de incidente en la red de transport | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **active_period** | [TimeRange](#mensaje-timerange) | repetido | Tiempo durante el cual debe mostrarse la alerta al usuario. Si falta, la alerta se mostrará durante todo el tiempo que aparezca en el feed. Si se otorgan varios intervalos, la alerta se mostrará durante todos ellos. | -| **informed_entity** | [EntitySelector](#mensaje-entitySelector) | repetido | Entidades a cuyos usuarios debemos notificar esta alerta. | -| **cause** | [Cause](#enum-cause) | opcional | -| **effect** | [Effect](#enum-effect) | opcional | -| **url** | [TranslatedString](#mensaje-translatedstring) | opcional | La URL que proporciona información adicional sobre la alerta. | -| **header_text** | [TranslatedString](#mensaje-translatedstring) | opcional | Encabezado de la alerta. Esta cadena de texto sin formato se resaltará, por ejemplo, en negrita. | -| **description_text** | [TranslatedString](#mensaje-translatedstring) | opcional | Descripción de la alerta. A esta cadena de texto sin formato se le aplicará el formato del cuerpo de la alerta (o se mostrará en una solicitud explícita de "expansión" realizada por el usuario
). La información de la descripción debe completar la información del encabezado. | +| **active_period** | [TimeRange](#TimeRange) | repetido | Tiempo durante el cual debe mostrarse la alerta al usuario. Si falta, la alerta se mostrará durante todo el tiempo que aparezca en el feed. Si se otorgan varios intervalos, la alerta se mostrará durante todos ellos. | +| **informed_entity** | [EntitySelector](#EntitySelector) | repetido | Entidades a cuyos usuarios debemos notificar esta alerta. | +| **cause** | [Cause](#Cause) | opcional | +| **effect** | [Effect](#Effect) | opcional | +| **url** | [TranslatedString](#TranslatedString) | opcional | La URL que proporciona información adicional sobre la alerta. | +| **header_text** | [TranslatedString](#TranslatedString) | opcional | Encabezado de la alerta. Esta cadena de texto sin formato se resaltará, por ejemplo, en negrita. | +| **description_text** | [TranslatedString](#TranslatedString) | opcional | Descripción de la alerta. A esta cadena de texto sin formato se le aplicará el formato del cuerpo de la alerta (o se mostrará en una solicitud explícita de "expansión" realizada por el usuario
). La información de la descripción debe completar la información del encabezado. | ## _enum._ Cause @@ -304,7 +304,7 @@ Un descriptor que identifica una instancia de un viaje de GTFS o todas las insta | **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | El identificador de la ruta de GTFS al que hace referencia este selector. | | **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La hora de inicio programada de esta instancia de viaje. Este campo debe proporcionarse solo si el viaje tiene frecuencia extendida en el feed GTFS. El valor debe corresponder precisamente a la hora de inicio especificada para la ruta del feed GTFS más algunos múltiplos de headway_secs. El formato del campo es el mismo que el de GTFS/frequencies.txt/start_time, es decir, 11:15:35 o 25:15:35. | | **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | La fecha de inicio programada de esta instancia de viaje. Este campo debe proporcionarse para desambiguar los viajes que están tan retrasados que pueden superponerse con un viaje programado para el día siguiente. Por ejemplo, para un tren que sale a las 8:00 y a las 20:00 todos los días, y está 12 horas retrasado, habrá dos viajes distintos a la misma hora. Este campo puede proporcionarse, pero no es obligatorio para las programaciones en las cuales las superposiciones son imposibles, por ejemplo, un servicio que funciona según una programación horaria donde un vehículo que está una hora retrasado deja de considerarse relacionado a la programación. En formato AAAAMMDD. | -| **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship-1) | opcional | +| **schedule_relationship** | [ScheduleRelationship](#ScheduleRelationship_TripDescriptor) | opcional | ## _enum._ ScheduleRelationship @@ -411,7 +411,7 @@ Un selector para una entidad en un feed GTFS. Los valores de los campos deben co | **agency_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | | **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | | **route_type** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | -| **trip** | [TripDescriptor](#mensaje-tripdescriptor) | opcional | +| **trip** | [TripDescriptor](#TripDescriptor) | opcional | | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | opcional | ## _mensaje_ TranslatedString @@ -422,7 +422,7 @@ Un mensaje internacionalizado que contiene versiones por idioma de un fragmento | _**Nombre del campo**_ | _**Tipo**_ | _**Cardinalidad**_ | _**Descripción**_ | |------------------------|------------|--------------------|-------------------| -| **translation** | [Translation](#mensaje-translation) | repetido | Se debe proporcionar al menos una traducción. | +| **translation** | [Translation](#Translation) | repetido | Se debe proporcionar al menos una traducción. | ## _mensaje_ Translation From 9acd8bcbfe76c3495cd1c454470e1cca0d52f3e1 Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Mon, 17 Jul 2017 10:51:25 +1000 Subject: [PATCH 09/10] Add carriage_sequence to explicitly define the carriage ordering. --- gtfs-realtime/proto/gtfs-realtime.proto | 24 ++++++++++++++++++------ gtfs-realtime/spec/en/reference.md | 3 ++- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 016746cc9..1615a415d 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -586,8 +586,20 @@ message VehicleDescriptor { // the carriage. optional string label = 2; + // Identifies the order of this carriage with respect to the other + // carriages in the vehicle's list of CarriageDescriptors. The values must + // be non-negative, and there cannot be duplicate values in the list of + // CarriageDescriptors. The values must be set such that the lowest value + // corresponds to the first carriage in the direction of travel, the + // second-lowest value corresponds to the second carriage in the direction + // of travel and so forth. For example, the first carriage in the direction + // of travel could have a carriage_sequence of 4, the second carriage could + // have a carriage_sequence of 10, the third carriage could have a + // carriage_sequence of 105, and so forth. + optional int32 carriage_sequence = 3; + // The degree of passenger occupancy of the carriage. - optional VehiclePosition.OccupancyStatus occupancy_status = 3; + optional VehiclePosition.OccupancyStatus occupancy_status = 4; // Whether the carriage is wheelchair accessible. enum WheelchairAccessible { @@ -602,7 +614,7 @@ message VehicleDescriptor { NOT_WHEELCHAIR_ACCESSIBLE = 2; } - optional WheelchairAccessible wheelchair_accessible = 4 [default = UNKNOWN]; + optional WheelchairAccessible wheelchair_accessible = 5 [default = UNKNOWN]; // Whether the carriage has toilet facilities onboard. enum ToiletFacilities { @@ -617,7 +629,7 @@ message VehicleDescriptor { NO_TOILET_ONBOARD = 2; } - optional ToiletFacilities toilet_facilities = 5 [default = UNKNOWN]; + optional ToiletFacilities toilet_facilities = 6 [default = UNKNOWN]; // Whether the carriage has WiFi onboard. enum WifiAvailability { @@ -634,7 +646,7 @@ message VehicleDescriptor { NO_WIFI = 3; } - optional WifiAvailability wifi_availability = 6 [default = UNKNOWN]; + optional WifiAvailability wifi_availability = 7 [default = UNKNOWN]; // Whether the carriage is air conditioned. enum AirConditioning { @@ -649,7 +661,7 @@ message VehicleDescriptor { NOT_AIR_CONDITIONED = 2; } - optional AirConditioning air_conditioning = 7 [default = UNKNOWN]; + optional AirConditioning air_conditioning = 8 [default = UNKNOWN]; // Whether bicycles are allowed in the carriage. enum BicyclesAllowed { @@ -669,7 +681,7 @@ message VehicleDescriptor { NOT_ALLOWED = 3; } - optional BicyclesAllowed bicycles_allowed = 8 [default = UNKNOWN]; + optional BicyclesAllowed bicycles_allowed = 9 [default = UNKNOWN]; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index fc92be290..98ad9bef9 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -357,7 +357,7 @@ Identification information for the vehicle performing the trip. | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field. | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle. | | **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The license plate of the vehicle. | -| **carriage_descriptor** | [CarriageDescriptor](#message-carriagedescriptor) | repeated | An ordered list of carriage information. | +| **carriage_descriptor** | [CarriageDescriptor](#message-carriagedescriptor) | repeated | A list of carriage information, ordered by carriage_sequence. The smallest carriage_sequence is the first carriage in the direction of travel, the second-smallest carriage_sequence is the second carriage in the direction of travel, and so forth. | ## _message_ CarriageDescriptor @@ -369,6 +369,7 @@ Information for a carriage that is part of a vehicle. |------------------|------------|-------------------|-------------------| | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the carriage. Should be **unique** per vehicle, and is used for tracking the carriage as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field. | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that can be shown to the passenger to help identify the correct carriage. | +| **carriage_sequence** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Identifies the order of this carriage with respect to the other carriages in the list of the vehicle's CarriageDescriptors. The values must be non-negative, and there cannot be duplicate values in the list of CarriageDescriptors. The values must be set such that the lowest value corresponds to the first carriage in the direction of travel, the second-lowest value corresponds to the second carriage in the direction of travel and so forth.| | _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _optional_ |The degree of passenger occupancy of the carriage.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| | **wheelchair_accessible** | [WheelchairAccessible](#enum-wheelchairaccessible) | optional | Whether the carriage is wheelchair accessible. | | **toilet_facilities** | [ToiletFacilities](#enum-toiletfacilities) | optional | Whether the carriage has toilet facilities onboard. | From 314773cd6daf58e25f19c5f3b2ca1fea14198c0b Mon Sep 17 00:00:00 2001 From: Rachael Morgan Date: Mon, 17 Jul 2017 11:01:12 +1000 Subject: [PATCH 10/10] Clarify that single-carriage vehicles (e.g. a standard bus) should have only 1 CarriageDescriptor. --- gtfs-realtime/proto/gtfs-realtime.proto | 6 ++---- gtfs-realtime/spec/en/reference.md | 4 ++-- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 1615a415d..471e93dcf 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -689,10 +689,8 @@ message VehicleDescriptor { extensions 1000 to 1999; } - // An ordered set of CarriageDescriptor. The first element maps to the first - // carriage a user will encounter if the vehicle is travelling in the - // direction of travel. Vehicles with only one compartment/carriage - // (e.g. a bus) will only have one CarriageDescriptor. + // A set of CarriageDescriptor. Vehicles with only one carriage/compartment + // (e.g. a standard bus) will only have one CarriageDescriptor. repeated CarriageDescriptor carriage_descriptor = 4; // The extensions namespace allows 3rd-party developers to extend the diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 98ad9bef9..f74c03579 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -357,7 +357,7 @@ Identification information for the vehicle performing the trip. | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field. | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle. | | **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The license plate of the vehicle. | -| **carriage_descriptor** | [CarriageDescriptor](#message-carriagedescriptor) | repeated | A list of carriage information, ordered by carriage_sequence. The smallest carriage_sequence is the first carriage in the direction of travel, the second-smallest carriage_sequence is the second carriage in the direction of travel, and so forth. | +| **carriage_descriptor** | [CarriageDescriptor](#message-carriagedescriptor) | repeated | A set of carriage information. Vehicles with only one carriage/compartment (e.g. a standard bus) will only have one CarriageDescriptor. When there are more than one CarriageInformation, **carriage_sequence** defines the ordering of the carriages. | ## _message_ CarriageDescriptor @@ -369,7 +369,7 @@ Information for a carriage that is part of a vehicle. |------------------|------------|-------------------|-------------------| | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the carriage. Should be **unique** per vehicle, and is used for tracking the carriage as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field. | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that can be shown to the passenger to help identify the correct carriage. | -| **carriage_sequence** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Identifies the order of this carriage with respect to the other carriages in the list of the vehicle's CarriageDescriptors. The values must be non-negative, and there cannot be duplicate values in the list of CarriageDescriptors. The values must be set such that the lowest value corresponds to the first carriage in the direction of travel, the second-lowest value corresponds to the second carriage in the direction of travel and so forth.| +| **carriage_sequence** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Identifies the order of this carriage with respect to the other carriages in the set of the vehicle's CarriageDescriptors. The values must be non-negative, and there cannot be duplicate values in the set of CarriageDescriptors. The values must be set such that the lowest value corresponds to the first carriage in the direction of travel, the second-lowest value corresponds to the second carriage in the direction of travel and so forth.| | _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _optional_ |The degree of passenger occupancy of the carriage.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| | **wheelchair_accessible** | [WheelchairAccessible](#enum-wheelchairaccessible) | optional | Whether the carriage is wheelchair accessible. | | **toilet_facilities** | [ToiletFacilities](#enum-toiletfacilities) | optional | Whether the carriage has toilet facilities onboard. |