Pathways and levels

gtfs/spec/en/reference.md

@@ -23,6 +23,8 @@ This document defines the format and structure of the files that comprise a GTFS
     -   [shapes.txt](#shapestxt)
     -   [frequencies.txt](#frequenciestxt)
     -   [transfers.txt](#transferstxt)
+    -   [pathways.txt](#pathwaystxt)
+    -   [levels.txt](#levelstxt)
     -   [feed\_info.txt](#feed_infotxt)
 
 ## Term Definitions
@@ -76,6 +78,8 @@ This specification defines the following files:
 |  [shapes.txt](#shapestxt)  | Optional | Rules for mapping vehicle travel paths, sometimes referred to as route alignments. |
 |  [frequencies.txt](#frequenciestxt)  | Optional | Headway (time between trips) for headway-based service or a compressed representation of fixed-schedule service. |
 |  [transfers.txt](#transferstxt)  | Optional | Rules for making connections at transfer points between routes. |
+|  [pathways.txt](#pathwaystxt)  | Optional | Pathways linking together locations within stations. |
+|  [levels.txt](#levelstxt)  | Optional | Levels within stations. |
 |  [feed_info.txt](#feed_infotxt)  | Optional | Dataset metadata, including publisher, version, and expiration information. |
 
 ## File Requirements
@@ -121,16 +125,17 @@ File: **Required**
 |  ------ | ------ | ------ | ------ |
 |  `stop_id` | ID | **Required** | Identifies a stop, station, or station entrance. The term "station entrance" refers to both station entrances and station exits. Stops, stations or station entrances are collectively referred to as locations. Multiple routes may use the same stop. |
 |  `stop_code` | Text | Optional | Short text or a number that identifies the location for riders. These codes are often used in phone-based transit information systems or printed on signage to make it easier for riders to get information for a particular location. The `stop_code` can be the same as `stop_id` if it is public facing. This field should be left empty for locations without a code presented to riders. |
-|  `stop_name` | Text | **Required** | Name of the location. Use a name that people will understand in the local and tourist vernacular. |
+|  `stop_name` | Text | **Conditionally Required** | Name of the location. Use a name that people will understand in the local and tourist vernacular.<br><br>When the location is a boarding area (`location_type=4`), the `stop_name` should contains the name of the boarding area as displayed by the agency. It could be just one letter (like on some European intercity railway stations), or text like “Wheelchair boarding area” (NYC’s Subway) or “Head of short trains” (Paris’ RER).<br><br>Conditionally Required:<br>• **Required** for locations which are stops (`location_type=0`), stations (`location_type=1`) or entrances/exits (`location_type=2`).<br>• Optional for locations which are generic nodes (`location_type=3`) or boarding areas (`location_type=4`).|
 |  `stop_desc` | Text | Optional | Description of the location that provides useful, quality information. Do not simply duplicate the name of the location. |
-|  `stop_lat` | Latitude | **Required** | Latitude of the location. |
-|  `stop_lon` | Longitude | **Required** | Longitude of the location. |
+|  `stop_lat` | Latitude | **Conditionally Required** | Latitude of the location.<br><br>Conditionally Required:<br>• **Required** for locations which are stops (`location_type=0`), stations (`location_type=1`) or entrances/exits (`location_type=2`).<br>• Optional for locations which are generic nodes (`location_type=3`) or boarding areas (`location_type=4`).|
+|  `stop_lon` | Longitude | **Conditionally Required** | Longitude of the location.<br><br>Conditionally Required:<br>• **Required** for locations which are stops (`location_type=0`), stations (`location_type=1`) or entrances/exits (`location_type=2`).<br>• Optional for locations which are generic nodes (`location_type=3`) or boarding areas (`location_type=4`). | 
 |  `zone_id` | ID | **Conditionally Required** | Identifies the fare zone for a stop. This field is required if providing fare information using [fare_rules.txt](#fare_rulestxt), otherwise it is optional. If this record represents a station or station entrance, the `zone_id` is ignored. |
 |  `stop_url` | URL | Optional | URL of a web page about the location. This should be different from the `agency.agency_url` and the `routes.route_url` field values. |
-|  `location_type` | Enum | Optional | Indicates whether this `stop_id` represents a stop, station, or station entrance/exit (denoted as station entrance in this document). If `location_type` is omitted, all locations are treated as stops. Valid options are: <br><br>`0` or empty - Stop. A location where riders board or disembark from a transit vehicle.<br>`1` - Station. A physical structure or area that contains one or more stop.<br>`2` - Station entrance. A point where riders can enter or exit a station from the street. The record must also specify a parent station by setting `parent_station` equal to the relevant `stop_id`. |
-|  `parent_station` | ID referencing `stops.stop_id` | Optional | Identifies the station that a stop or station entrance is part of. This station-stop relationship, called a parent-child relationship, can only exist between a station (as the parent) and a stop or station entrance (as the child). These types are defined by location_type. If the stop or station identified in this record does not have a parent, leave `parent_station` empty. A station can never have a parent and a station entrance must always have a parent. |
+|  `location_type` | Enum | Optional | Type of the location:<br>• `0` (or blank): **Stop** (or **Platform**). A location where passengers board or disembark from a transit vehicle. Is called a platform when defined within a `parent_station`.<br>• `1`: **Station**. A physical structure or area that contains one or more platform.<br>• `2`: **Entrance/Exit**. A location where passengers can enter or exit a station from the street. If an entrance/exit belongs to multiple stations, it can be linked by pathways to both, but the data provider must pick one of them as parent.<br>• `3`: **Generic Node**. A location within a station, not matching any other `location_type`, which can be used to link together pathways define in pathways.txt.<br>• `4`: **Boarding Area**. A specific location on a platform, where passengers can board and/or alight vehicles.|
+|  `parent_station` | ID referencing `stops.stop_id` | **Conditionally Required** | Defines hierarchy between the different locations defined in `stops.txt`. It contains the ID of the parent location, as followed:<br>• **Stop/platform** (`location_type=0`): the `parent_station` field contains the ID of a station.<br>• **Station** (`location_type=1`): this field must be empty.<br>• **Entrance/exit** (`location_type=2`) or **generic node** (`location_type=3`): the `parent_station` field contains the ID of a station (`location_type=1`)<br>• **Boarding Area** (`location_type=4`): the `parent_station` field contains ID of a platform.<br><br>Conditionally Required:<br>• **Required** for locations which are entrances (`location_type=2`), generic nodes (`location_type=3`) or boarding areas (`location_type=4`).<br>• Optional for stops/platforms (`location_type=0`).<br>• Forbidden for stations (`location_type=1`).|
 |  `stop_timezone` | Timezone | Optional | Timezone of the location. If the location has a parent station, it inherits the parent station’s timezone instead of applying its own. Stations and parentless stops with empty `stop_timezone` inherit the timezone specified by `agency.agency_timezone`. If `stop_timezone` values are provided, the times in [stop_times.txt](#stop_timetxt) should be entered as the time since midnight in the timezone specified by `agency.agency_timezone`. This ensures that the time values in a trip always increase over the course of a trip, regardless of which timezones the trip crosses. |
 |  `wheelchair_boarding` | Enum | Optional | Indicates whether wheelchair boardings are possible from the location. Valid options are: <br><br>For parentless stops:<br>`0` or empty - No accessibility information for the stop.<br>`1` - Some vehicles at this stop can be boarded by a rider in a wheelchair.<br>`2` - Wheelchair boarding is not possible at this stop. <br><br>For child stops: <br>`0` or empty - Stop will inherit its `wheelchair_boarding` behavior from the parent station, if specified in the parent.<br>`1` - There exists some accessible path from outside the station to the specific stop/platform.<br>`2` - There exists no accessible path from outside the station to the specific stop/platform.<br><br> For station entrances/exits: <br>`0` or empty - Station entrance will inherit its `wheelchair_boarding` behavior from the parent station, if specified for the parent.<br>`1` - Station entrance is wheelchair accessible.<br>`2` - No accessible path from station entrance to stops/platforms. |
+|  `level_id` | ID referencing `levels.level_id` | Optional | Level of the location. The same level can be used by multiple unlinked stations.|
 
 ### routes.txt
 
@@ -312,6 +317,47 @@ When calculating an itinerary, GTFS-consuming applications interpolate transfers
 |  `transfer_type` | Enum | **Required** | Indicates the type of connection for the specified (`from_stop_id`, `to_stop_id`) pair. Valid options are:<br><br> `0` or empty - Recommended transfer point between routes.<br>`1` - Timed transfer point between two routes. The departing vehicle is expected to wait for the arriving one and leave sufficient time for a rider to transfer between routes.<br>`2` - Transfer requires a minimum amount of time between arrival and departure to ensure a connection. The time required to transfer is specified by `min_transfer_time`.<br>`3` - Transfers are not possible between routes at the location. |
 |  `min_transfer_time` | Non-negative integer | Optional | Amount of time, in seconds, that must be available to permit a transfer between routes at the specified stops. The `min_transfer_time` should be sufficient to permit a typical rider to move between the two stops, including buffer time to allow for schedule variance on each route. |
 
+### pathways.txt
+
+File: **Optional**
+
+The GTFS-Pathways extension uses a graph representation to describe subway or train, with nodes (the locations) and edges (the pathways).
+
+To go from the entrance (which is a node represented as a location with location_type=2) to a platform (which is a node represented as a location with location_type=0), the rider will go through walkway, fare gates, stairs, etc (which are edges represented as pathways). The proposal also adds another type of location, a generic one called "generic node", to represent for example a walkway crossing from which different walkways can be taken.
+
+**Warning: Pathways must be exhaustive in a station.** As consequence, as soon as one platform (as stop), entrance or node belonging to a station has a pathway linked to it, the station is assumed to have exhaustive description of its pathways. Therefore, the following common sense rules apply:
+- No dangling location: If any location within a station has a pathway, then all locations should have pathways (except for those platforms that have boarding areas).
+- No locked platforms: Each platform must be connected to at least one entrance via some chain of pathways. There are very rare stations in the real life where you cannot go outside.
+- No pathways for a platform with boarding areas: A platform that has boarding areas is treated as a parent object, not a point. It may not have pathways assigned. All pathways should be for boarding areas.
+
+|  Field Name | Type | Required | Description |
+|  ------ | ------ | ------ | ------ |
+|  `pathway_id` | ID | **Required** | The `pathway_id` field contains an ID that uniquely identifies the pathway. The `pathway_id` is used by systems as an internal identifier of this record (e.g., primary key in database), and therefore the `pathway_id` must be dataset unique. <br> Different pathways can go from the same `from_stop_id` to the same `to_stop_id`. For example, this happens when two escalators are side by side in opposite direction, or when a stair is nearby and elevator and both go from the same place to the same place.|
+|  `from_stop_id` | ID referencing `stops.stop_id` | **Required** | Location at which the pathway begins. It contains a `stop_id` that identifies a platform, entrance/exit, generic node or boarding area from the `stops.txt` file.|
+|  `to_stop_id` | ID referencing `stops.stop_id` | **Required** | Location at which the pathway ends. It contains a `stop_id` that identifies a platform, entrance/exit, generic node or boarding area from the `stops.txt` file.|
+|  `pathway_mode` | Enum | **Required** | Type of pathway between the specified (`from_stop_id`, `to_stop_id`) pair. Valid values for this field are: <br> • 1: walkway <br> • 2: stairs <br> • 3: moving sidewalk/travelator <br> • 4: escalator <br> • 5: elevator <br> • 6: fare gate (or payment gate): A pathway that crosses into an area of the station where a proof of payment is required (usually via a physical payment gate).<br>Fare gates may either separate paid areas of the station from unpaid ones, or separate different payment areas within the same station from each other. This information can be used to avoid routing passengers through stations using shortcuts that would require passengers to make unnecessary payments, like directing a passenger to walk through a subway platform to reach a busway. <br> • 7: exit gate: Indicates a pathway exiting an area where proof-of-payment is required into an area where proof-of-payment is no longer required.|
+|  `is_bidirectional` | Enum | **Required** | Indicates in which direction the pathway can be used:<br>• 0: Unidirectional pathway, it can only be used from `from_stop_id` to `to_stop_id`.<br>• 1: Bidirectional pathway, it can be used in the two directions.<br><br>Fare gates (`pathway_mode=6`) and exit gates (`pathway_mode=7`) cannot be bidirectional.|
+| `length` | Non-negative Float | Optional | Horizontal length in meters of the pathway from the origin location (defined in `from_stop_id`) to the destination location (defined in `to_stop_id`).<br><br>This field is recommended for walkways (`pathway_mode=1`), fare gates (`pathway_mode=6`) and exit gates (`pathway_mode=7`).|
+| `traversal_time` | Positive Integer | Optional | Average time in seconds needed to walk through the pathway from the origin location (defined in `from_stop_id`) to the destination location (defined in `to_stop_id`).<br><br>This field is recommended for moving sidewalks (`pathway_mode=3`), escalators (`pathway_mode=4`) and elevator (`pathway_mode=5`).|
+| `stair_count` | Non-null Integer | Optional | Number of stairs of the pathway.<br><br>Best Practices: one could use the approximation of 1 floor = 15 stairs to generate approximative values.<br><br>A positive `stair_count` implies that the rider walk up from `from_stop_id` to `to_stop_id`. And a negative `stair_count` implies that the rider walk down from `from_stop_id` to `to_stop_id`.<br><br>This field is recommended for stairs (`pathway_mode=2`).|
+| `max_slope` | Float | Optional | Maximum slope ratio of the pathway. Valid values for this field are:<br>• 0 or (empty): no slope.<br>• A float: slope ratio of the pathway, positive for upwards, negative for downwards.<br><br>This field should be used only with walkways (`pathway_type=1`) and moving sidewalks (`pathway_type=3`).<br><br>Example: In the US, 0.083 (also written 8.3%) is the maximum slope ratio for hand-propelled wheelchair, which mean an increase of 0.083m (so 8.3cm) for each 1m.|
+| `min_width` | Positive Float | Optional | Minimum width of the pathway in meters.<br><br>This field is highly recommended if the minimum width is less than 1 meter.|
+| `signposted_as` | Text | Optional | String of text from physical signage visible to transit riders. The string can be used to provide text directions to users, such as 'follow signs to '. The language text should appear in this field exactly how it is printed on the signs - it should not be translated.|
+| `reversed_signposted_as` | Text | Optional | Same than the `signposted_as` field, but when the pathways is used backward, i.e. from the `to_stop_id` to the `from_stop_id`.|
+
+### levels.txt
+
+File: **Optional**
+
+Describe the different levels of a station. Is mostly useful when used in conjunction with `pathways.txt`, and is required for elevator (`pathway_mode=5`) to ask the user to take the elevator to the “Mezzanine” or the “Platform” level.
+
+|  Field Name | Type | Required | Description |
+|  ------ | ------ | ------ | ------ |
+|  `level_id` | ID | **Required** | Id of the level that can be referenced from `stops.txt`.|
+|  `level_index` | Float | **Required** | Numeric index of the level that indicates relative position of this level in relation to other levels (levels with higher indices are assumed to be located above levels with lower indices).<br><br>Ground level should have index 0, with levels above ground indicated by positive indices and levels below ground by negative indices.|
+|  `level_name` | Text | Optional | Optional name of the level (that matches level lettering/numbering used inside the building or the station). Is useful for elevator routing (e.g. “take the elevator to level “Mezzanine” or “Platforms” or “-1”).|
+
+
 ### feed_info.txt
 
 File: **Optional**