Skip to content
Documentation

Transitland Atlas feed registry

Transitland Atlas is an open catalog of transit/mobility data feeds and operators.

This catalog is used to power the canonical Transitland platform, is available for distributed used of the transitland-lib tooling, and is open to use as a "crosswalk" within other transportation data systems.

Transitland Atlas is a public GitHub repository filled with JSON files in the Distributed Mobility Feed Registry format.

Feed specifications included in Transitland Atlas

Transitland Atlas catalogs feeds in the following data specifications (specs):

Transitland Atlas previously included support for MDS feeds, but uptake was so limited that we have removed that functionality.

How to Add a New Feed

  1. Check if a ./feeds file exists with the domain name for the feed URL. (ex. http://bart.gov -> bart.gov.dmfr.json)
    • If a file exists, use that file, otherwise create a new empty DMFR file.
    • To create a new file, you can use another dmfr.json file as a starting point.
    • Feeds exist as an array in the feeds property of a DMFR file.
  2. Propose a new Onestop ID for the feed (see the Onestop ID scheme)
    • Feed Onestop ID's begins with f- and continues with a unique string, like the transit operator's name
    • Use lowercase, alphanumeric unicode characters in the name component
    • Use ~ instead of spaces or other punctuation
  3. Add the appropriate URL to static_current
  4. Add license and/or authorization metadata if you are aware of it.
  5. Open a PR. Feel free to add any questions as a comment on the PR if you are uncertain about your DMFR file.
  6. GitHub Actions (continuous integration service) will run a basic validation check on your PR and report any errors.
  7. A moderator will review and comment on your PR. If you don't get a response shortly, feel free to ping us at hello@transit.land

If you are using the GitHub web interface, you can click "Add a file -> Create a new file" in the ./feeds directory, or when viewing an individual existing file, the pencil icon in the upper right of the contents display. Make sure to select "Create a new branch for this commit" and begin creating a pull request to propose changes.

For more information on what can go into a DMFR file, see the DMFR documentation.

How to Update an Existing Feed

  1. Find the DMFR file containing the feed.
  2. Update the URLs and other properties for that feed
    • For static feeds, use static_current for the present URL.
    • Add the previous URL value to the static_historic array.
  3. Edit the file and open the PR as described above.

Onestop ID values for feeds and operators are used to synchronize with existing values in the Transitland database. Editing the Onestop ID value will cause a new feed or operator record to be created; values in the database that are no longer present in the Transitland Atlas will be marked as soft-deleted. Use caution and clear intent when changing a Onestop ID value.

Operators

Operators describe, annotate, and group data from different feed data sources. See agencies and operators for what that distinction means. This section covers how to write one in a DMFR file.

Operators can exist in the top-level operators property if a DMFR file, or nested within a feed. An operator defined in the top-level operators property requires an associated_feeds value to connect the operator with data sources. When an operator is nested within a feed, there is an implicit association that all GTFS agencies contained in that file are associated with that operator, which helps reduces complexity and maintenance.

The key properties for an operator are:

  • onestop_id: A Onestop ID value for this operator, starting with o-
  • name: A formal name for the operator, such as Bay Area Rapid Transit
  • short_name: A simpler, colloqial name for an operator, such as BART
  • tags: A set of key,value string pairs that provide additional metadata and references
  • website: A URL to find more information about this operator
  • associated_feeds: An array of feed association objects; for each entry, feed_onestop_id is required and gtfs_agency_id is optional

Values for onestop_id and name are required; associated_feeds (either explicit or through nesting the operator in a feed) are highly recommended.