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.