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.

shape_idRequiredAn ID to uniquely identify a shape. Every point for a shape contains the same value.
shape_pt_latRequiredThe latitude for a given point in the range of -90 to 90.
shape_pt_lonRequiredThe longitude for a given point in the range of -180 to 180.
shape_pt_sequenceRequiredA non-negative number that defines the ordering for points in a shape. A value must not be repeated within a single shape.
shape_dist_traveledOptionalThis 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.


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.