A few years ago, Washington DC’s transit authority, WMATA, released a programming interface for its bus and rail system. The API provides real-time position information for all active buses and trains and is used by a number of apps.

The API returns the train positions as reported by sensors placed at known locations on the tracks, every few hundred feet or so. Since portions of the train lines are below ground, GPS cannot locate train positions, so these sensors are the best they can do. Each sensor has a number to identify it called a track circuit identifier which is reported by the API for each active train.

No publicly released map of the circuit numbers is available. The API does provide the identifiers of neighboring track segments connected to each track segment. From this information it is possible to construct a system-wide map of the circuit identifiers (see below, SVG version).

On first inspection, assembling such a map might seem trivial, but as it turns out, there are over 5000 circuit identifiers system-wide that span four possible track types and five train lines, making the problem similar to solving a large jigsaw puzzle.

I gave a short presentation at a meetup on this project in 2016 that has more information. I used Python to interact with the API and graphviz to draw the diagram below. Interestingly, I discovered a few connector tracks that permit trains to traverse independent lines, such as the single track line from the red to green line.

track map