diff options
Diffstat (limited to '.idea/gtfs-book/ch-09-shapes.md')
| -rw-r--r-- | .idea/gtfs-book/ch-09-shapes.md | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/.idea/gtfs-book/ch-09-shapes.md b/.idea/gtfs-book/ch-09-shapes.md new file mode 100644 index 0000000..bc05636 --- /dev/null +++ b/.idea/gtfs-book/ch-09-shapes.md @@ -0,0 +1,76 @@ +## 9. Trip Shapes (shapes.txt) + +*This file is ***optional*** in a GTFS feed.* + +Each trip in `trips.txt` can have a shape associated with it. The +shapes.txt file defines the points that make up an individual shape in +order to plot a trip on a map. Two or more records in `shapes.txt` +with the same `shape_id` value define a shape. + +The amount of data stored in this file can be quite large. In +*Optimizing Shapes* there are some strategies to efficiently +reduce the amount of shape data. + +| Field | Required? | Description | +| :----- | :-------- | :---------- | +| `shape_id` | Required | An ID to uniquely identify a shape. Every point for a shape contains the same value. | +| `shape_pt_lat` | Required | The latitude for a given point in the range of `-90` to `90`. | +| `shape_pt_lon` | Required | The longitude for a given point in the range of `-180` to `180`. | +| `shape_pt_sequence` | Required | A non-negative number that defines the ordering for points in a shape. A value must not be repeated within a single shape. | +| `shape_dist_traveled` | Optional | This value represents how far along a shape a particular point exists. This is a distance in a unit such as feet or kilometers. This unit must be the same as that used in `stop_times.txt`. | + +### Sample Data + +The following table shows a portion of a shape from the TriMet GTFS +feed. It is a portion of the shape that corresponds to the sample data +in the `stop_times.txt` section. + +| `shape_id` | `shape_pt_lat` | `shape_pt_lon` | `shape_pt_sequence` | `shape_dist_traveled` | +| :--------- | :------------- | :------------- | :------------------ | :-------------------- | +| 185328 | 45.52291 | -122.677372 | 1 | 0.0 | +| 185328 | 45.522921 | -122.67737 | 2 | 3.7 | +| 185328 | 45.522991 | -122.677432 | 3 | 34.0 | +| 185328 | 45.522992 | -122.677246 | 4 | 81.5 | +| 185328 | 45.523002 | -122.676567 | 5 | 255.7 | +| 185328 | 45.523004 | -122.676486 | 6 | 276.4 | +| 185328 | 45.523007 | -122.676386 | 7 | 302.0 | +| 185328 | 45.523024 | -122.675386 | 8 | 558.4 | +| 185328 | 45.522962 | -122.67538 | 9 | 581.0 | + +In this sample data, the `shape_dist_traveled` is listed in feet. +There is no way to specify in a GTFS feed which units are used for this +column -- it could be feet, miles, meters, kilometers. In actual fact, +it does not really matter, just as long as the units are the same as in +`stop_times.txt`. + +If you need to present a distance to your users (such as how far you +need to travel on a bus), you can calculate it instead by adding up the +distance between each point and formatting it based on the user's +locale settings. + +### Point Sequences + +In most GTFS feeds the `shape_pt_sequence` value starts at 1 and +increments by 1 for every subsequent point. Additionally, points are +typically listed in order of their sequence. + +You should not rely on these two statements though, as this is not a +requirement of GTFS. Many transit agencies have automated systems that +export their GTFS from a separate system, which can sometimes result in +an unpredictable output format. + +For instance, a trip that has stop times listed with the sequences `1`, `2`, +`9`, `18`, `7`, `3` is perfectly valid. + +### Distance Travelled + +The `shape_dist_traveled` column is used so you can programmatically +determine how much of a shape to draw when showing a map to users of +your web site or app. If you use techniques in *Optimizing Shapes* +to reduce the file size of shape data, then it becomes difficult to +use this value. + +Alternatively, you can calculate portions of shapes by determining which +point in a shape travels closest to the start and finish points of a +trip. + |