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:

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 ZYP.
  • It's known in Amtrak's GTFS feed as NYP.
  • It's known in the Long Island Railroad's GTFS feed as Stop #8.
  • It's known in New Jersey Transit's GTFS feed as Stop #105.

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:

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 two or three components, separated by hyphens. For example:

an example of a Onestop ID: 0-9q9-BART

Entity types

The first component of a Onestop ID is its entity type:

  • f for feeds
  • o for operators/agencies
  • s for stops/stations
  • r for routes

Geohash

The second component of a Onestop ID is an optional geohash.

In Transitland v1, the geohash component was required in a Onestop ID. In Transitland v2, the geohash component is now optional in Onestop IDs for feeds and operators. This makes it easier to add feed and operator records in Transitland Atlas.

For example, this is a valid "two component" Onestop ID: f-galesburg~il~us

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:

map showing an example geohash 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.

map showing a geohash bounding box surrounded by its eight neighbors

Name

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:

  • o-ezjm-informaciónoficial~consorcioregionaldetransportesdemadrid
  • o-xn39-瑞浪市
  • r-xn39k-瑞浪市コミュニティバス釜戸大湫線

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.

Where is the authority for a Onestop ID

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.

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:

https://www.transit.land/onestop-id/f-9q9-bart

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:

https://www.transit.land/onestop_id/f-9q9-bart

For more examples, see the Find an entity by Onestop ID page.