diff --git a/gtfs/spec/en/inlining.svg b/gtfs/spec/en/inlining.svg new file mode 100644 index 00000000..616575da --- /dev/null +++ b/gtfs/spec/en/inlining.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index efec8df6..1783a372 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -61,6 +61,7 @@ Presence conditions applicable to fields and files: * **Optional** - The field or file may be omitted from the dataset. * **Conditionally Required** - The field or file must be included under conditions outlined in the field or file description. * **Conditionally Forbidden** - The field or file must not be included under conditions outlined in the field or file description. +* **Recommended** - The field or file may be omitted from the dataset, but it is a best practice to include it. Before omitting this field or file, the best practice should be carefully evaluated and the full implications of omission should be understood. ### Field Types @@ -155,7 +156,7 @@ Primary key (`agency_id`) | Field Name | Type | Presence | Description | | ------ | ------ | ------ | ------ | -| `agency_id` | Unique ID | **Conditionally Required** | Identifies a transit brand which is often synonymous with a transit agency. Note that in some cases, such as when a single agency operates multiple separate services, agencies and brands are distinct. This document uses the term "agency" in place of "brand". A dataset may contain data from multiple agencies.

Conditionally Required:
- **Required** when the dataset contains data for multiple transit agencies.
- Optional otherwise. | +| `agency_id` | Unique ID | **Conditionally Required** | Identifies a transit brand which is often synonymous with a transit agency. Note that in some cases, such as when a single agency operates multiple separate services, agencies and brands are distinct. This document uses the term "agency" in place of "brand". A dataset may contain data from multiple agencies.

Conditionally Required:
- **Required** when the dataset contains data for multiple transit agencies.
- Recommended otherwise. | | `agency_name` | Text | **Required** | Full name of the transit agency. | | `agency_url` | URL | **Required** | URL of the transit agency. | | `agency_timezone` | Timezone | **Required** | Timezone where the transit agency is located. If multiple agencies are specified in the dataset, each must have the same `agency_timezone`. | @@ -198,8 +199,8 @@ Primary key (`route_id`) | Field Name | Type | Presence | Description | | ------ | ------ | ------ | ------ | | `route_id` | Unique ID | **Required** | Identifies a route. | -| `agency_id` | Foreign ID referencing `agency.agency_id` | **Conditionally Required** | Agency for the specified route.

Conditionally Required:
- **Required** if multiple agencies are defined in [agency.txt](#agency).
- Optional otherwise. | -| `route_short_name` | Text | **Conditionally Required** | Short name of a route. Often a short, abstract identifier (e.g., "32", "100X", "Green") that riders use to identify a route. Both `route_short_name` and `route_long_name` may be defined.

Conditionally Required:
- **Required** if `routes.route_long_name` is empty.
- Optional otherwise. | +| `agency_id` | Foreign ID referencing `agency.agency_id` | **Conditionally Required** | Agency for the specified route.

Conditionally Required:
- **Required** if multiple agencies are defined in [agency.txt](#agency).
- Recommended otherwise. | +| `route_short_name` | Text | **Conditionally Required** | Short name of a route. Often a short, abstract identifier (e.g., "32", "100X", "Green") that riders use to identify a route. Both `route_short_name` and `route_long_name` may be defined.

Conditionally Required:
- **Required** if `routes.route_long_name` is empty.
- Recommended if there is a brief service designation. This should be the commonly-known passenger name of the service, and should be no longer than 12 characters. | | `route_long_name` | Text | **Conditionally Required** | Full name of a route. This name is generally more descriptive than the `route_short_name` and often includes the route's destination or stop. Both `route_short_name` and `route_long_name` may be defined.

Conditionally Required:
- **Required** if `routes.route_short_name` is empty.
- Optional otherwise. | | `route_desc` | Text | Optional | Description of a route that provides useful, quality information. Should not be a duplicate of `route_short_name` or `route_long_name`.
_Example: "A" trains operate between Inwood-207 St, Manhattan and Far Rockaway-Mott Avenue, Queens at all times. Also from about 6AM until about midnight, additional "A" trains operate between Inwood-207 St and Lefferts Boulevard (trains typically alternate between Lefferts Blvd and Far Rockaway)._ | | `route_type` | Enum | **Required** | Indicates the type of transportation used on a route. Valid options are:

`0` - Tram, Streetcar, Light rail. Any light rail or street level system within a metropolitan area.
`1` - Subway, Metro. Any underground rail system within a metropolitan area.
`2` - Rail. Used for intercity or long-distance travel.
`3` - Bus. Used for short- and long-distance bus routes.
`4` - Ferry. Used for short- and long-distance boat service.
`5` - Cable tram. Used for street-level rail cars where the cable runs beneath the vehicle (e.g., cable car in San Francisco).
`6` - Aerial lift, suspended cable car (e.g., gondola lift, aerial tramway). Cable transport where cabins, cars, gondolas or open chairs are suspended by means of one or more cables.
`7` - Funicular. Any rail system designed for steep inclines.
`11` - Trolleybus. Electric buses that draw power from overhead wires using poles.
`12` - Monorail. Railway in which the track consists of a single rail or a beam. | @@ -265,8 +266,8 @@ Primary key (`trip_id`, `stop_sequence`) | `drop_off_type` | Enum | Optional | Indicates drop off method. Valid options are:

`0` or empty - Regularly scheduled drop off.
`1` - No drop off available.
`2` - Must phone agency to arrange drop off.
`3` - Must coordinate with driver to arrange drop off. | | `continuous_pickup` | Enum | Optional | Indicates that the rider can board the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, from this `stop_time` to the next `stop_time` in the trip’s `stop_sequence`. Valid options are:

`0` - Continuous stopping pickup.
`1` or empty - No continuous stopping pickup.
`2` - Must phone agency to arrange continuous stopping pickup.
`3` - Must coordinate with driver to arrange continuous stopping pickup.

If this field is populated, it overrides any continuous pickup behavior defined in `routes.txt`. If this field is empty, the `stop_time` inherits any continuous pickup behavior defined in `routes.txt`. | | `continuous_drop_off` | Enum | Optional | Indicates that the rider can alight from the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, from this `stop_time` to the next `stop_time` in the trip’s `stop_sequence`. Valid options are:

`0` - Continuous stopping drop off.
`1` or empty - No continuous stopping drop off.
`2` - Must phone agency to arrange continuous stopping drop off.
`3` - Must coordinate with driver to arrange continuous stopping drop off.

If this field is populated, it overrides any continuous drop-off behavior defined in `routes.txt`. If this field is empty, the `stop_time` inherits any continuous drop-off behavior defined in `routes.txt`. | -| `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the associated shape, from the first stop to the stop specified in this record. This field specifies how much of the shape to draw between any two stops during a trip. Must be in the same units used in [shapes.txt](#shapestxt). Values used for `shape_dist_traveled` must increase along with `stop_sequence`; they must not be used to show reverse travel along a route. A stop time's `shape_dist_traveled` must not exceed the maximum `shape_dist_traveled` of the shape for the related trip in [shapes.txt](#shapestxt).
*Example: If a bus travels a distance of 5.25 kilometers from the start of the shape to the stop,`shape_dist_traveled`=`5.25`.* | -| `timepoint` | Enum | Optional | Indicates if arrival and departure times for a stop are strictly adhered to by the vehicle or if they are instead approximate and/or interpolated times. This field allows a GTFS producer to provide interpolated stop-times, while indicating that the times are approximate. Valid options are:

`0` - Times are considered approximate.
`1` or empty - Times are considered exact. | +| `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the associated shape, from the first stop to the stop specified in this record. This field specifies how much of the shape to draw between any two stops during a trip. Must be in the same units used in [shapes.txt](#shapestxt). Values used for `shape_dist_traveled` must increase along with `stop_sequence`; they must not be used to show reverse travel along a route.

Recommended for routes that have looping or inlining (the vehicle crosses or travels over the same portion of alignment in one trip). See [`shapes.shape_dist_traveled`](#shapestxt).
*Example: If a bus travels a distance of 5.25 kilometers from the start of the shape to the stop,`shape_dist_traveled`=`5.25`.*| +| `timepoint` | Enum | Recommended | Indicates if arrival and departure times for a stop are strictly adhered to by the vehicle or if they are instead approximate and/or interpolated times. This field allows a GTFS producer to provide interpolated stop-times, while indicating that the times are approximate. Valid options are:

`0` - Times are considered approximate.
`1` or empty - Times are considered exact. | ### calendar.txt @@ -322,7 +323,7 @@ There are two modelling options for describing fares. GTFS-Fares V1 is the legac | `currency_type` | Currency code | **Required** | Currency used to pay the fare. | | `payment_method` | Enum | **Required** | Indicates when the fare must be paid. Valid options are:

`0` - Fare is paid on board.
`1` - Fare must be paid before boarding. | | `transfers` | Enum | **Required** | Indicates the number of transfers permitted on this fare. Valid options are:

`0` - No transfers permitted on this fare.
`1` - Riders may transfer once.
`2` - Riders may transfer twice.
empty - Unlimited transfers are permitted. | -| `agency_id` | Foreign ID referencing `agency.agency_id` | **Conditionally Required** | Identifies the relevant agency for a fare.

Conditionally Required:
- **Required** if multiple agencies are defined in `agency.txt`.
- Optional otherwise. | +| `agency_id` | Foreign ID referencing `agency.agency_id` | **Conditionally Required** | Identifies the relevant agency for a fare.

Conditionally Required:
- **Required** if multiple agencies are defined in `agency.txt`.
- Recommended otherwise. | | `transfer_duration` | Non-negative integer | Optional | Length of time in seconds before a transfer expires. When `transfers`=`0` this field may be used to indicate how long a ticket is valid for or it may be left empty. | ### fare_rules.txt @@ -518,7 +519,7 @@ Shapes describe the path that a vehicle travels along a route alignment, and are | `shape_pt_lat` | Latitude | **Required** | Latitude of a shape point. Each record in [shapes.txt](#shapestxt) represents a shape point used to define the shape. | | `shape_pt_lon` | Longitude | **Required** | Longitude of a shape point. | | `shape_pt_sequence` | Non-negative integer | **Required** | Sequence in which the shape points connect to form the shape. Values must increase along the trip but do not need to be consecutive.
*Example: If the shape "A_shp" has three points in its definition, the [shapes.txt](#shapestxt) file might contain these records to define the shape:*
`shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence`
`A_shp,37.61956,-122.48161,0`
`A_shp,37.64430,-122.41070,6`
`A_shp,37.65863,-122.30839,11` | -| `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the shape from the first shape point to the point specified in this record. Used by trip planners to show the correct portion of the shape on a map. Values must increase along with `shape_pt_sequence`; they must not be used to show reverse travel along a route. Distance units must be consistent with those used in [stop_times.txt](#stop_timestxt).
*Example: If a bus travels along the three points defined above for A_shp, the additional `shape_dist_traveled` values (shown here in kilometers) would look like this:*
`shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled`
`A_shp,37.61956,-122.48161,0,0`
`A_shp,37.64430,-122.41070,6,6.8310`
`A_shp,37.65863,-122.30839,11,15.8765` | +| `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the shape from the first shape point to the point specified in this record. Used by trip planners to show the correct portion of the shape on a map. Values must increase along with `shape_pt_sequence`; they must not be used to show reverse travel along a route. Distance units must be consistent with those used in [stop_times.txt](#stop_timestxt).

Recommended for routes that have looping or inlining (the vehicle crosses or travels over the same portion of alignment in one trip).

If a vehicle retraces or crosses the route alignment at points in the course of a trip, `shape_dist_traveled` is important to clarify how portions of the points in `shapes.txt` line up correspond with records in `stop_times.txt`.
*Example: If a bus travels along the three points defined above for A_shp, the additional `shape_dist_traveled` values (shown here in kilometers) would look like this:*
`shape_id,shape_pt_lat,shape_pt_lon,shape_pt_sequence,shape_dist_traveled`
`A_shp,37.61956,-122.48161,0,0`
`A_shp,37.64430,-122.41070,6,6.8310`
`A_shp,37.65863,-122.30839,11,15.8765` | ### frequencies.txt @@ -662,7 +663,7 @@ In regions that have multiple official languages, transit agencies/operators typ ### feed_info.txt -File: **Optional** (**Required** if `translations.txt` is provided) +File: **Recommended** (**Required** if `translations.txt` is provided) Primary key (none) @@ -676,11 +677,11 @@ If both referencing methods (`record_id`, `record_sub_id`) and `field_value` are | `feed_publisher_url` | URL | **Required** | URL of the dataset publishing organization's website. This may be the same as one of the `agency.agency_url` values. | | `feed_lang` | Language code | **Required** | Default language used for the text in this dataset. This setting helps GTFS consumers choose capitalization rules and other language-specific settings for the dataset. The file `translations.txt` can be used if the text needs to be translated into languages other than the default one.

The default language may be multilingual for datasets with the original text in multiple languages. In such cases, the `feed_lang` field should contain the language code `mul` defined by the norm ISO 639-2, and a translation for each language used in the dataset should be provided in `translations.txt`. If all the original text in the dataset is in the same language, then `mul` should not be used.
_Example: Consider a dataset from a multilingual country like Switzerland, with the original `stops.stop_name` field populated with stop names in different languages. Each stop name is written according to the dominant language in that stop’s geographic location, e.g. `Genève` for the French-speaking city of Geneva, `Zürich` for the German-speaking city of Zurich, and `Biel/Bienne` for the bilingual city of Biel/Bienne. The dataset `feed_lang` should be `mul` and translations would be provided in `translations.txt`, in German: `Genf`, `Zürich` and `Biel`; in French: `Genève`, `Zurich` and `Bienne`; in Italian: `Ginevra`, `Zurigo` and `Bienna`; and in English: `Geneva`, `Zurich` and `Biel/Bienne`._ | | `default_lang` | Language code | Optional | Defines the language that should be used when the data consumer doesn’t know the language of the rider. It will often be `en` (English). | -| `feed_start_date` | Date | Optional | The dataset provides complete and reliable schedule information for service in the period from the beginning of the `feed_start_date` day to the end of the `feed_end_date` day. Both days may be left empty if unavailable. The `feed_end_date` date must not precede the `feed_start_date` date if both are given. It is recommended that dataset providers give schedule data outside this period to advise of likely future service, but dataset consumers should treat it mindful of its non-authoritative status. If `feed_start_date` or `feed_end_date` extend beyond the active calendar dates defined in [calendar.txt](#calendartxt) and [calendar_dates.txt](#calendar_datestxt), the dataset is making an explicit assertion that there is no service for dates within the `feed_start_date` or `feed_end_date` range but not included in the active calendar dates. | -| `feed_end_date` | Date | Optional | (see above) | -| `feed_version` | Text | Optional | String that indicates the current version of their GTFS dataset. GTFS-consuming applications can display this value to help dataset publishers determine whether the latest dataset has been incorporated. | -| `feed_contact_email` | Email | Optional | Email address for communication regarding the GTFS dataset and data publishing practices. `feed_contact_email` is a technical contact for GTFS-consuming applications. Provide customer service contact information through [agency.txt](#agencytxt). | -| `feed_contact_url` | URL | Optional | URL for contact information, a web-form, support desk, or other tools for communication regarding the GTFS dataset and data publishing practices. `feed_contact_url` is a technical contact for GTFS-consuming applications. Provide customer service contact information through [agency.txt](#agencytxt). | +| `feed_start_date` | Date | Recommended | The dataset provides complete and reliable schedule information for service in the period from the beginning of the `feed_start_date` day to the end of the `feed_end_date` day. Both days may be left empty if unavailable. The `feed_end_date` date must not precede the `feed_start_date` date if both are given. It is recommended that dataset providers give schedule data outside this period to advise of likely future service, but dataset consumers should treat it mindful of its non-authoritative status. If `feed_start_date` or `feed_end_date` extend beyond the active calendar dates defined in [calendar.txt](#calendartxt) and [calendar_dates.txt](#calendar_datestxt), the dataset is making an explicit assertion that there is no service for dates within the `feed_start_date` or `feed_end_date` range but not included in the active calendar dates. | +| `feed_end_date` | Date | Recommended | (see above) | +| `feed_version` | Text | Recommended | String that indicates the current version of their GTFS dataset. GTFS-consuming applications can display this value to help dataset publishers determine whether the latest dataset has been incorporated. | +| `feed_contact_email` | Email | Optional | Email address for communication regarding the GTFS dataset and data publishing practices. `feed_contact_email` is a technical contact for GTFS-consuming applications. Provide customer service contact information through [agency.txt](#agencytxt). It's recommended that at least one of `feed_contact_email` or `feed_contact_url` are provided. | +| `feed_contact_url` | URL | Optional | URL for contact information, a web-form, support desk, or other tools for communication regarding the GTFS dataset and data publishing practices. `feed_contact_url` is a technical contact for GTFS-consuming applications. Provide customer service contact information through [agency.txt](#agencytxt). It's recommended that at least one of `feed_contact_url` or `feed_contact_email` are provided. | ### attributions.txt