Onestop ID scheme
The Onestop ID is an attempt to link transit data across disparate sources. At present, each transit operator, each government department, and each software developer has their own scheme for identifying and labeling their data. Take, for example, the San Francisco Municipal Transportation Agency:
- It's known colloquially as:
- It's known in its GTFS feed as
- It's known in the US National Transit Database as
- It's known on the GTFS Data Exchange as
When considering just this one operator of transit service, the differences are minor. But the US National Transit Database includes 769 different operators. Building software to handle data from that many different operators, each with a few different IDs, is more of a challenge. And we're still only talking about the U.S.
Just as each transit operator has multiple IDs, each bus stop and train station has at least one ID for each of the operators that serves it. Take, for example, New York's Penn Station:
- It's known to the International Air Transport Association as
- It's known in Amtrak's GTFS feed as
- It's known in the Long Island Railroad's GTFS feed as
- It's known in New Jersey Transit's GTFS feed as
In the Transitland Atlas, we've created listings for the San Francisco Municipal Transportation Agency. For the SFMTA, we've assigned the transit agency a Onestop ID of
o-9q8y-sfmta and its feed a Onestop ID of
f-9q8y-sfmta. We also use these Onestop IDs in various Transitland APIs and data products. You can query it for:
- the SFMTA feed on the website:
- the SFMTA feed through the v2 REST API:
- the SFMTA operator record:
- the SFMTA operator through the v2 REST API:
- browse routes operated by the SFMTA:
Notice how stops and routes are assigned their own Onestop IDs as well.
What is in a Onestop ID?
A Onestop ID is an alphanumeric, global, immutable identifer for transit feeds, operators/agencies, stops/stations, and routes provided by authoritative sources that contain timetable and geographic information for transit networks. Every Onestop ID includes three components, separated by hyphens. For example:
An entity type
A geohash, a set of characters that can be translated into a geographic bounding box around the service area of the operator/agency, the location of the stop/station, or the coverage of a route. The more characters, the more precise and smaller the bounding box. For example, the geohash
9q8zn2jrefers this purple rectangle in San Francisco:
- An abbreviated name that is short but understandable. The only punctuation that is allowed are tildes (
~) to indicate word breaks. The name doesn't have to be unique across the whole world, but it must be unique within the bounding box of the particular geohash.
Want to browse geohashes for your location? Here's a map of geohashes over the entire globe: missinglink/leaflet-spatial-prefix-tree
Sometimes, an operator's service area won't fit exactly inside a geohash's bounding box. The most extreme example is London, where the tube network crosses the prime meridian. No one geohash can be used to effectively identify the extent of Transport for London's service area.
Therefore, the geohash in a Onestop ID is used to refer to a focal point. In the case of feeds and operators, their coverage/service area can extend out to any of the eight neighboring geohash bounding boxes. In the case of routes, they can extend into any of the eight neighbors. The centroid of the feed, operator, or route will always be located in the geohash that's included in the Onestop ID—the focal point, that is—but the lines or polygons could extend out into neighbors.
For example, here is the geohash
9q9 and its eight neighbors. This geohash can refer to Bay Area Rapid Transit (BART), including all its service area.
Onestop IDs are case insensitive. It is recommended to use lower case internally in your systems. When displaying IDs for users, you can capitalize for readability.
Onestop IDs should be no longer than 64 characters.
Where is the authority for a Onestop ID
OnestopIDs are generated or updated whenever data is imported into the Transitland database.
To browse Onestop IDs for feeds and operators, try the Transitland Operators index.
To browse Onestop IDs for operators, stops, and routes, try the global transit map.
Onestop IDs are also included on all Transitland APIs.
For the future, Transitland may consider distributed mechanisms for registering, updating, and removing Onestop IDs, and welcomes suggestions on how to best share this responsibility among systems and users.
Look up any entity by Onestop ID
To link to the Transitland website page for any entity with a Onestop ID, you can form a URL like the following:
This endpoint can take any Onestop ID for a feed, operator, stop, or route and it will redirect the user to the appropriate webpage.
In case users accidentally type an underscore instead of a dash character, we also handle URLs like the following:
For more examples, see the Find an entity by Onestop ID page.