Search
Clear search
Close search
Google apps
Main menu

Stop to shape matching

A common task for GTFS consumers is matching stops to shape data for routes and trips. Recall that the shapes.txt file can be used to define the path of travel for a particular trip by linking the trip to a shape with the shape_id field in trips.txt. A trip also defines a sequence of stops in the stop_times.txt file for the stops visited during the course of the trip. When defining a shape for a trip, you often want to match the sequence of stops to their closest location along the trip shape to show the path of travel between two stops in routing results.

Matching stops to a trip shape may seem like a straightforward task, but it can be tricky in cases where a trip has a complex geometry such as loops or overlapping sections. Our software does its best to match a stop to its best location along a shape. When that process fails, it may indicate a problem with your shape data, stop locations, or the stop sequence of a trip.

Specifically, our GTFS validation tool often reports two common warnings for stop-to-shape matching. Follow the links for specific guidance on diagnosing those issues.

For complex shape and stop sequences, the GTFS specification provides a mechanism for explicitly defining how stops are matched to the trip shape. The shapes.txt file defines a shape_dist_traveled field, which can be used to specify the distance along the shape for each point of the shape. The stop_times.txt file also defines a shape_dist_traveled field, which can be used to specify distance along the shape for each stop along a trip. When both fields are defined for the shape and each stop belonging to a trip, the distance values can be used to explicitly determine where each stop matches to a shape.

Consider the following example:

trips.txt

trip_id,route_id,service_id,shape_id
t0,r0,weekly,shape0

shapes.txt

shape_id,shape_pt_sequence,shape_pt_lat,shape_pt_lon,shape_dist_traveled
shape0,0,47.0,-122.0,0
shape0,1,47.1,-122.0,100
shape0,2,47.1,-122.1,200
stop_times.txt
trip_id,stop_sequence,stop_id,arrival_time,departure_time,shape_dist_traveled
t0,0,stop0,09:00:00,09:00:00,50
t0,1,stop1,09:30:00,09:30:00,175

In our example, we defined a simple trip with a simple shape, two stops, and shape_dist_traveled values for both the shape and each stop. Consider stop0 first. It has a shape_dist_traveled value of 50. Looking at our shape points, we see that 50 falls between the first two shape points, which have shape_dist_traveled values of 0 and 100, respectively. That would put the stop-to-shape match roughly halfway between the two shape points: approximately 47.05, -122.0. We also see that stop1 has a shape_dist_traveled value of 175, putting it between the last two shape points. Since the stop is about 3/4 of the way between the two points according to the shape distance, the stop-to-shape match would be approximately 47.1, -122.75.

Use whatever units you prefer for shape_dist_traveled values (meters, feet, etc): feed consumers should not assume particular units. Instead, the values can only be used relative to each other to determine how a stop matches positions along a shape.

Was this article helpful?
How can we improve it?