Skip to content

transfer rules for routes and trips, and in-seat transfers #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
antrim wants to merge 2 commits into from
Closed

transfer rules for routes and trips, and in-seat transfers #32

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
77b3db9
Merge remote-tracking branch 'google/master'
antrim May 30, 2017
03a4592
all blocks/transfers change proposals - agency.txt, trips.txt, transf…
antrim May 30, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 28 additions & 4 deletions gtfs/spec/en/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,9 @@ File: **Required**
| 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. |
| block_transfer_default | Optional | Specifies whether in-seat transfers are allowed by default for the agency (see **block_id** field in [trips.txt](#tripstxt)). Overriding parameters are specified in [transfers.txt](#transferstxt).|
| | |* **0** or **(empty)** - In-seat transfers are allowed unless overriden. This is also the default if the field is not provided. |
| | |* **1** - In-seat transfers are disallowed unless overriden. |

### stops.txt

Expand Down Expand Up @@ -166,7 +169,7 @@ File: **Required**
| | | * `trip_id,...,trip_headsign,direction_id` |
| | | * `1234,...,to Airport,0` |
| | | * `1505,...,to 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)) |
| block_id | Optional | The **block_id** field identifies the block to which the trip belongs. A block consists of two or more sequential trips made using the same vehicle. The **block_id** must be referenced by two or more trips in trips.txt. The **block_transfer_default** field of [agency.txt](#agencytxt) specifies if passenger may transfer from one trip to the next just by staying in the vehicle (an "in-seat transfer") for an agency. [transfers.txt](#transferstxt) specifies whether in-seat transfers are allowed on at specific stops and on specific routes and trips. |
| 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 |
Expand Down Expand Up @@ -405,13 +408,34 @@ Trip planners normally calculate transfer points based on the relative proximity
| ------ | ------ | ------ |
| 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. |
| from_route_id | **Optional** | The from_route_id field can contain a route_id (as specified by [routes.txt](#routestxt)), reducing the scope to which the given transfer applies. If from_route_id is specified, the transfer will only apply to the arriving trip with the given route id, at the given from_stop_id. |
Copy link
Contributor

@barbeau barbeau May 24, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated to this proposal - needs to be removed from PR.

Copy link
Contributor Author

@antrim antrim May 30, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @barbeau : The additional transfer types are intended to be part of this proposal/PR. If block transfers are turned off by default for an agency (as many agencies will likely choose), then they will also need a way to override and allow block transfers in specific cases.

Copy link
Contributor

@barbeau barbeau May 30, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, thanks - makes sense.

| to_route_id | **Optional** | The to_route_id field can contain a route_id (as specified by [routes.txt](#routestxt)), reducing the scope to which the given transfer applies. If to_route_id is specified, the transfer will only apply to the departing trip with given route id, at the given to_stop_id. |
| from_trip_id | **Optional** | The from_trip_id and to_trip_id fields can contain a trip_id, as specified by [trips.txt](#tripstxt). If from_trip_id is given, from_route_id is ignored. If from_trip_id is specified, the transfer will only apply to the arriving trip with the given trip id, at the given from_stop_id. |
| to_trip_id | **Optional** | The to_trip_id field can contain a trip_id, as specified by [trips.txt](#tripstxt). If to_trip_id is given, to_route_id is ignored. If to_trip_id is specified, the transfer will only apply to the departing trip with the given trip id, at the given to_stop_id. |
| 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 two 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. |
Copy link
Contributor

@barbeau barbeau May 24, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated to this proposal - needs to be removed from PR.

Copy link
Contributor Author

@antrim antrim May 30, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intentional to provide additional capabilities to manage transfers broadly, and block transfers as a subset.

Copy link
Contributor

@barbeau barbeau May 30, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, right - gotcha.

| | | * **1** - This is a timed transfer point between two vehicles. 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. |
| | | * **3** - Transfers are not possible. |
| | | * **4** - Passengers can transfer from one route to another by staying onboard the same vehicle (an "in-seat transfer") in cases where sequential trips are made by the same vehicle (same **block_id**). In-seat transfer between these two stops / routes / trips is allowed. |
Copy link

@DaveBarker DaveBarker Dec 13, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the reference to block_id mean that block_id must be included to use this transfer_type?

Which of the following are valid uses of transfer_type 4?
A. transfers.txt contains route_id's and stop_id's. The trips on the routes do have block_id's.
B. transfers.txt contains trip_id's. The trips on the routes do have block_id's.
C. transfers.txt contains trip_id's. The trips on the routes DO NOT have block_id's.
D. transfers.txt contains route_id's and stop_id's. The trips on the routes DO NOT have block_id's.

Copy link
Contributor Author

@antrim antrim Jul 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @aybrd that all these uses should be valid.

@abyrd: I think you're right that block_id should not be required in the case that transfer_type=4 is specified, but I still anticipate that feed producers may want to supply block_id to propagate vehicle delays as you suggest, to configure real-time passenger information systems (e.g. @TheTransitClock), and for other purposes.

| | | * **5** - In-seat transfers are not allowed between sequential trips with the same **block_id**. The passenger must alight from the vehicle and re-board. |
| 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. |
| | | The **min_transfer_time** value must be entered in seconds, and must be a non-negative integer. |

**Specificity of a transfer**

Some transfers are more specific than others. The "specificity" of a transfer is defined thus in order to provide a ranking mechanism that determines when a transfer applies.

The specificity of the source of the transfer is 0 if only from_stop_id is given, 1 if **from_route_id** is specified, and 2 if **from_trip_id** is specified. The same applies for target: 0 if only **to_stop_id** is given, 1 if **to_route_id** is specified, and 2 if **to_trip_id** is specified. The sum of these 2 values gives the specificity of the transfer, between 0 and 4 inclusive. For a given ordered pair of arriving trip and departing trip, the transfer with the greatest specificity that applies between these 2 trips is chosen. So for any pair of trips, there should NOT be two transfers with equally maximal specificity that could apply.

Example of an ambiguous rule:

| from_stop_id | to_stop_id | from_route_id | to_route_id | transfer_type |
| --- | --- | --- | --- | --- |
| stopFrom | stopTo | routeFrom | | 0 |
| stopFrom | stopTo | | routeTo | 1 |

These two transfers both have a specificity of 1. But for transfers between a trip with **route_id** routeFrom arriving at stop stopFrom, to a trip with **route_id** routeTo arriving at stop stopTo, either of these two rules can apply.

### feed_info.txt

Expand Down