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.
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 two or three components, separated by hyphens. For example:
The first component of a Onestop ID is its entity type:
The second component of a Onestop ID is an optional geohash.
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
9q8zn2j refers this purple rectangle in San Francisco:
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.
The final component of a Onestop ID is a name. This is the third component when a geohash is the second component; or the name is the second component, when the geohash is skipped.
An abbreviated name that is short but understandable. The only punctuation that is allowed are tildes (
~) to indicate word breaks within the name component.
When using in a "three part" Onestop ID with a geohash, 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.
When using in a "two part" Onestop ID for a feed or an operator (without a geohash), the name does have to be globally uniqe.
The name component may include UTF-8 characters, including accented letters and Japanese letters. For example:
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 for feeds are defined within the Transitland Atlas repository.
Onestop IDs for operators are defined within the Transitland Atlas repository. Alternatively, when static GTFS feeds provide agencies that are not matched to operators defined in the Transitland Atlas, then Transitland APIs will list a "virtual" operator record with an automatically generated Onestop ID.
Onestop IDs for routes and stops are automatically generated by Transitland APIs based on GTFS data.
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.