Skip to content
This repository has been archived by the owner on May 21, 2024. It is now read-only.

Commit

Permalink
Remove Best Practices merged into spec (#59)
Browse files Browse the repository at this point in the history
* Remove BP merged into spec

Removing content coded into reference.md from BP:

- agency.agency_id
- routes.agency_id
- routes.route_short_name
- stop_times.shape_dist_traveled
- stop_times.timepoint
- fare_attributes.agency_id
- shapes.shape_dist_traveled
- feed_info.txt

* Added field name in shapes.txt table

Added `shape_dist_traveled` field name under shapes.txt table
  • Loading branch information
Sergiodero authored Aug 30, 2023
1 parent 80e2487 commit 09fa31c
Showing 1 changed file with 1 addition and 18 deletions.
19 changes: 1 addition & 18 deletions en/best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,6 @@ This section shows practices organized by file and field, aligning with the [GTF

| Field Name | Recommendation |
| --- | --- |
| `agency_id` | Should be included, even if there is only one agency in the feed. (See also recommendation to include `agency_id` in [`routes.txt`](#routestxt) and [`fare_attributes.txt`](#fare_attributestxt)) |
| `agency_phone` | Should be included unless no such customer service phone exists. |
| `agency_email` | Should be included unless no such customer service email exists. |
| `agency_fare_url` | Should be included unless the agency is fully fare-free. |
Expand All @@ -70,8 +69,6 @@ __Examples:__

| Field Name | Recommendation |
| --- | --- |
| `agency_id` | Should be included, even if there is only one agency in the feed. (See also recommendation to include `agency_id` in [`agency.txt`](#agencytxt) and [`fare_attributes.txt`](#fare_attributestxt)) |
| `route_short_name` | Include `route_short_name` if there is a brief service designation. This should be the commonly-known passenger name of the service, no longer than 12 characters. |
| `route_long_name` | The definition from Specification reference: <q>This name is generally more descriptive than the <code>route_short_name</code> and will often include the route's destination or stop. At least one of <code>route_short_name</code> or <code>route_long_name</code> must be specified, or potentially both if appropriate. If the route does not have a long name, please specify a <code>route_short_name</code> and use an empty string as the value for this field.</q><br>Examples of types of long names are below:<table class='example'><thead><tr><th colspan='3'>Primary Travel Path or Corridor</th></tr><tr><th>Route Name</th><th>Form</th><th>Agency</th></tr></thead><tbody><tr><td><a href='https://www.sfmta.com/getting-around/transit/routes-stops/n-judah'>“N”/“Judah”</a></td><td><code>route_short_name</code>/<br><code>route_long_name</code></td><td><a href='https://www.sfmta.com/'>Muni</a>, in San Francisco</td></tr><tr><td><a href='https://trimet.org/schedules/r006.htm'>“6“/“ML King Jr Blvd“</a></td><td><code>route_short_name</code>/<br><code>route_long_name</code></td><td><a href='https://trimet.org/'>TriMet</a>, in Portland, Or.</td></tr><tr><td><a href='http://www.ratp.fr/informer/pdf/orienter/f_plan.php?nompdf=m6'>“6”/“Nation - Étoile”</a></td><td><code>route_short_name</code>/<br><code>route_long_name</code></td><td><a href='http://www.ratp.fr/'>RATP</a>, in Paris France.</td></tr><tr><td><a href='http://www.bvg.de/images/content/linienverlaeufe/LinienverlaufU2.pdf'>“U2”-“Pankow – Ruhleben”</a></td><td><code>route_short_name</code>-<br><code>route_long_name</code></td><td><a href='http://www.bvg.de/'>BVG</a>, in Berlin, Germany</td></tr></tbody></table><table class='example'><thead><tr><th>Description of the Service</th></tr></thead><tbody><tr><td><a href='https://128bc.org/schedules/rev-bus-hartwell-area/'>“Hartwell Area Shuttle“</a></td></tr></tbody></table>
| | `route_long_name` should not contain the `route_short_name`. |
| | Include the full designation including a service identity when populating `route_long_name`. Examples:<table class='example'><thead><tr><th>Service Identity</th><th>Recommendation</th><th>Examples</th></tr></thead><tbody><tr><td>"MAX Light Rail"<br>TriMet, in Portland, Oregon</td><td>The <code>route_long_name</code> should include the brand (MAX) and the specific route designation</td><td>"MAX Red Line" "MAX Blue Line"</td></tr><tr><td>"Rapid Ride"<br>ABQ Ride, in Albuquerque, New Mexico</td><td>The <code>route_long_name</code> should include the brand (Rapid Ride) and the specific route designation</td><td>"Rapid Ride Red Line"<br>"Rapid Ride Blue Line"</td></tr></tbody></table>
Expand Down Expand Up @@ -101,12 +98,10 @@ Loop routes: Loop routes require special `stop_times` considerations. (See: [Loo
| --- | --- |
| `pickup_type` & `drop_off_type` | Non-revenue (deadhead) trips that do not provide passenger service should be marked with `pickup_type` and `drop_off_type` value of `1` for all `stop_times` rows.
| | On revenue trips, internal “timing points” for monitoring operational performance and other places such as garages that a passenger cannot board should be marked with `pickup_type = 1` (no pickup available) and `drop_off_type = 1` (no drop off available). |
| timepoint | The `timepoint` field should be provided. It specifies which `stop_times` the operator will attempt to strictly adhere to (`timepoint=1`), and that other stop times are estimates (`timepoint=0`). |
| `arrival_time` & `departure_time` | `arrival_time` and `departure_time` fields should specify time values whenever possible, including non-binding estimated or interpolated times between timepoints. |
| `stop_headsign` | In general, headsign values should also correspond to signs in the stations.<br><br>In the cases below, “Southbound” would mislead customers because it is not used in the station signs.
| | <table class="example"><thead><tr><th colspan="2">In NYC, for the 2 going Southbound:</th></tr><tr><th>For <code>stop_times.txt</code> rows:</th><th>Use <code>stop_headsign</code> value:</th></tr></thead><tbody><tr><td>Until Manhattan is Reached</td><td><code>Manhattan & Brooklyn</code></td></tr><tr><td>Until Downtown is Reached</td><td><code>Downtown & Brooklyn</code></td></tr><tr><td>Until Brooklyn is Reached</td><td><code>Brooklyn</code></td></tr><tr><td>Once Brooklyn is Reached</td><td><code>Brooklyn (New Lots Av)</code></td></tr></tbody></table> |
| | <table class="example"><thead><tr><th colspan="2">In Boston, for the Red Line going Southbound, for the Braintree branch:</th></tr><tr><th>For <code>stop_times.txt</code> rows:</th><th>Use <code>stop_headsign</code> value:</th></tr></thead><tbody><tr><td>Until Downtown is Reached</td><td><code>Inbound to Braintree</code></td></tr><tr><td>Once Downtown is Reached</td><td><code>Braintree</code></td></tr><tr><td>After Downtown</td><td><code>Outbound to Braintree</code></td> </tr></tbody></table> |
| `shape_dist_traveled` | `shape_dist_traveled` must be provided for routes that have looping or inlining (the vehicle crosses or travels over the same portion of alignment in one trip). See the [`shapes.shape_dist_traveled`](#shapestxt) recommendation. |

### calendar.txt

Expand All @@ -124,7 +119,6 @@ Loop routes: Loop routes require special `stop_times` considerations. (See: [Loo

| Field Name | Recommendation |
| --- | --- |
| `agency_id` | Should be included, even if there is only one agency in the feed. (See also recommendation to include `agency_id` in [`agency.txt`](#agencytxt) and [`routes.txt`](#routestxt)) |
| | If a fare system cannot be accurately modeled, avoid further confusion and leave it blank. |
| | Include fares (`fare_attributes.txt` and `fare_rules.txt`) and model them as accurately as possible. In edge cases where fares cannot be accurately modeled, the fare should be represented as more expensive rather than less expensive so customers will not attempt to board with insufficient fare. If the vast majority of fares cannot be modeled correctly, do not include fare information in the feed. |

Expand All @@ -141,8 +135,7 @@ Loop routes: Loop routes require special `stop_times` considerations. (See: [Loo
| --- | --- |
| All Fields | Ideally, for alignments that are shared (i.e. in a case where Routes 1 and 2 operate on the same segment of roadway or track) then the shared portion of alignment should match exactly. This helps to facilitate high-quality transit cartography. <!-- (77) -->
| | Alignments should follow the centerline of the right of way on which the vehicle travels. This could be either the centerline of the street if there are no designated lanes, or the centerline of the side of the roadway that travels in the direction the vehicle moves. <br><br>Alignments should not “jag” to a curb stop, platform, or boarding location. |
| `shape_dist_traveled` | Must be provided in both `shapes.txt` and `stop_times.txt` if an alignment includes looping or inlining (the vehicle crosses or travels over the same portion of alignment in one trip). <img src="https://raw.githubusercontent.com/MobilityData/GTFS_Schedule_Best-Practices/master/en/inlining.svg" width=200px style="display: block; margin-left: auto; margin-right: auto;"><br>If a vehicle retraces or crosses the route alignment at points in the course of a trip, <code>shape_dist_traveled</code> is important to clarify how portions of the points in <code>shapes.txt</code> line up correspond with records in <code>stop_times.txt</code>. |
| | The `shape_dist_traveled` field allows the agency to specify exactly how the stops in the `stop_times.txt` file fit into their respective shape. A common value to use for the `shape_dist_traveled` field is the distance from the beginning of the shape as traveled by the vehicle (think something like an odometer reading). <li>Route alignments (in `shapes.txt`) should be within 100 meters of stop locations which a trip serves.</li><li>Simplify alignments so that <code>shapes.txt</code> does not contain extraneous points (i.e. remove extra points on straight-line segments; see discussion of line simplification problem).</li>
| `shape_dist_traveled` | The `shape_dist_traveled` field allows the agency to specify exactly how the stops in the `stop_times.txt` file fit into their respective shape. A common value to use for the `shape_dist_traveled` field is the distance from the beginning of the shape as traveled by the vehicle (think something like an odometer reading). <li>Route alignments (in `shapes.txt`) should be within 100 meters of stop locations which a trip serves.</li><li>Simplify alignments so that <code>shapes.txt</code> does not contain extraneous points (i.e. remove extra points on straight-line segments; see discussion of line simplification problem).</li>

### frequencies.txt

Expand All @@ -164,16 +157,6 @@ Loop routes: Loop routes require special `stop_times` considerations. (See: [Loo
| | If in-seat (block) transfers are allowed between trips, then the last stop of the arriving trip must be the same as the first stop of the departing trip. |


### feed_info.txt

`feed_info.txt` should be included, with all fields below.

| Field Name | Recommendation |
| --- | --- |
| `feed_start_date` & `feed_end_date` | Should be included |
| `feed_version` | Should be included |
| `feed_contact_email` & `feed_contact_url` | Provide at least one |

## Practice Recommendations Organized by Case

This section covers particular cases with implications across files and fields.
Expand Down

0 comments on commit 09fa31c

Please sign in to comment.