Rebuilding Broken GTFS Shapes: How We Redraw the World's Transit Maps

If you have ever tried to build a map from a raw GTFS feed, you have probably discovered an uncomfortable truth: a lot of them are broken. Not in the catastrophic, feed-won't-parse sense. In the quieter, more infuriating sense. The trips are there. The stops are there. The schedule is there. But the shape of the route — the actual line you want to draw on a map — is missing, sparse, or plainly wrong.

At trains.fyi we track more than 130 rail networks worldwide, and we would estimate that somewhere around a third of the feeds we ingest have shape data that is not really fit to render. This post is about how we solve that, without calling out any agency by name, because honestly, we feel for them.

The problem, briefly

The GTFS spec includes an optional file called shapes.txt. It is a sequence of latitude-longitude points that describe the physical path a vehicle takes between stops. When it is present and accurate, everything is easy: you draw the line, the train icon slides along it, and the map looks like a map.

When it is missing, your options are grim. The classic fallback is to just draw straight lines between consecutive stops. This works for a handful of tiny metros where stations are already in a straight line. For almost every other rail system on earth, it looks like a toddler got a ruler. Long-distance intercity routes become chords across mountain ranges. Curved suburban branches become zigzags. Tunnels and bridges disappear entirely.

And "missing" is only the obvious failure mode. We see feeds where:

Only a subset of routes has shapes, and the rest inherit the straight-line treatment.
The shapes exist but follow obsolete alignments the railway stopped using years ago.
Every trip on a route points at a single shape that has the stops in the wrong order.
The shape snake-dances between the stops because somebody interpolated from a low-resolution source.

Each of these makes for a bad map. A bad map makes for a bad product.

The insight

Here is the thing. Even when a feed's geometry is a disaster, two pieces of information are almost always reliable:

The stop locations. Agencies care a lot about where their stations are. Stop coordinates are usually accurate to within a few meters.
The order of stops on a trip. Even the roughest feeds get the sequence right. They have to — passengers need it.

That gives us a skeleton: a sequence of points in the right order, on or very near the actual railway. The thing we are missing is the curve of the track between them.

Fortunately, that curve is not a secret. The world's railways have been mapped, in exhaustive detail, by an enormous community of volunteers and open data projects. Railway alignments are one of the most thoroughly catalogued things on Earth. You just have to know how to ask.

Our approach

We will keep the specifics vague on purpose, because this is one of the pieces of work we consider a genuine moat. But at a high level, our pipeline does something like this:

Take the feed's stops and the trip's stop sequence as ground truth.
Consult an open corpus of rail infrastructure geometry covering the region the route runs through.
Reconstruct a plausible path that respects the real rail network — its curves, its junctions, its tunnels, its bridges — while hitting every stop in the correct order.
Store the result as a first-class shape that behaves exactly like a good GTFS shapes.txt row would.

The result is geometry that looks and behaves like the agency published it themselves, even in cases where they did not publish anything at all. Train icons follow real track. Routes curve through mountains. Underground stretches trace the actual tunnel, not the street above it.

We do not hand-draw any of this. The whole thing is automated end to end, runs on every sync, and quietly corrects itself as upstream data improves.

Why we bother

You might reasonably ask whether this level of effort matters. The honest answer is that it matters more than almost anything else in the product.

A map is the first thing a user sees. If the lines are wrong, they stop trusting everything else on the screen — the schedules, the real-time positions, the ETAs. If the lines are right, the user assumes the whole thing is right, even when, underneath, we are juggling dozens of flaky feeds held together by pipelines and careful engineering.

There is also a second-order effect that turns out to be meaningful. Once you have a faithful shape, a lot of downstream work gets easier. Interpolating a vehicle's position between two GPS pings. Detecting whether a reported position is plausible. Computing corridor-based search radii. Snapping noisy realtime data to a track. All of it becomes tractable the moment your geometry is honest.

A note to agencies

If you are a transit agency reading this: please ship shapes.txt, and please make sure it tracks the actual alignment your trains use. We will happily continue rebuilding it when you do not, but the best-case map we can produce is always the one where we do not have to.

And if you run a feed and you are not sure whether yours is in good shape — pun intended — we are genuinely happy to take a look. Reach out. We have opinions.

The takeaway

GTFS is a quietly extraordinary piece of infrastructure. It powers every serious transit map, tracker, and journey planner in the world. But the spec is permissive by design, which means the quality of any given feed is entirely up to the agency that publishes it. Some are excellent. Some are works in progress. A few are, politely, in a state of disrepair.

Shipping a product that works across 130-plus networks means accepting this and engineering around it. Rebuilding missing shapes from stop sequences and open rail data is one of the more satisfying pieces of that work — a problem the spec quietly hands back to you, and one with a surprisingly elegant solution if you are willing to go looking for it.

If you want to see the results, open any network page on trains.fyi and look at the route lines. Some of them are the agency's own shapes, faithfully rendered. Some of them are ours, reconstructed from scratch. We would be flattered if you could not tell which is which.