Source Feeds

Transitland regularly fetches and ingests data from thousands of source feeds. Source feeds are provided by operators of transit service around the world, including public transit agencies and also companies that operate regularly scheduled transit service within or between cities.

Typically, Transitland catalogs and ingests feeds that describe transit service open to the general public. However, sometimes Transitland also includes feeds for private employer shuttles or other transit service with limited access. Interline provides customized versions of the Transitland platform for organizations that require Transitland APIs for private feeds.

Feed specifications

Transitland ingests data in the following feed specifications (also known as "specs"):

  • GTFS for fixed-route transit such as buses, trains, subways, and ferries. GTFS is also known as "static GTFS" or "GTFS Schedule."
  • GTFS Realtime for service alerts, trip updates, and vehicle positions for fixed-route transit. GTFS Realtime is also referred to as GTFS-RT or GTFS-R.
  • GBFS for bike-share and micro-mobility rental system.

Onestop IDs for feeds

Every feed within Transitland is identified by a globally unique Onestop ID that begins with f-.

Onestop IDs for feeds are defined within the Transitland Atlas repository on GitHub. A continuing integration job running on GitHub Actions ensures that Onestop IDs are not duplicated.

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

Transitland Atlas has functionality to track old Onestop IDs that have been deprecated. These are listed on some feed (and also operator records) as supersedes_ids: [] Note that Transitland APIs and the Transitland website do not yet have functionality to query against superseded Onestop IDs.

Adding a feed to Transitland

For more information on how to add a GTFS or GTFS Realtime feed to Transitland, see the Transitland Atlas documentation.

To add a GBFS feed to Transitland, open a pull request against the the GBFS repository on GitHub. The systems.csv file in that repository will be automatically synchronized into the Transitland Atlas repository.

Transit operators are welcome to email Interline for assistance in adding their feeds to Transitland.

Feed license information

Interline and other contributors to Transitland Atlas make a good-faith effort to check for licenses attached to each source feed in Transitland. When a license can be found, we briefly review it and summarize it in the DMFR listing in Transitland Atlas. These feeds listings are imported into Transitland and available throughout Transitland APIs.

Each feed listing may include the following information about the license attached to a source feed:

  • url: a URL for a custom license or a URL for a webpage that identifies a standard open license attached to the feed
  • spdx_identifier: SPDX identifiers provide a common scheme for naming standard open licenses. For example, CC-BY-4.0 is the SPDX identifier for the Creative Commons Attribution 4.0 International license. For a full list of SPDX identifiers, see https://spdx.org/licenses/

Many feed producers care about data consumers providing attribution to the source. That is, a consumer of transit data who uses the data to create a web app, a map, a report, or another type of visual or textual product to credit the source of their data. While not all source feeds in Transitland require attribution, enough do so that we make sure to meet this requirement by requiring that users of the Transitland API Free and Professional plans provide a link to https://www.transit.land/terms This webpage is dynamically generated to provide full attribution to all of Transitland's source feeds. More information about attribution requirements is contained in each feed record with the following parameters:

  • use_without_attribution (allowed values: yes, no, unknown): Are feed consumers allowed to use the feed contents without including attribution text in their app or map? Note that users of the Transitland Free and Professional plans are always required to attribute Transitland by linking to https://www.transit.land/terms This ensures that we meet all attribution requirements on source feeds.
  • attribution_text: Feed consumers must include this particular text when using this feed. This text is automatically included on the webpage at https://www.transit.land/terms
  • attribution_instructions: Feed consumers must follow these instructions for how to provide attribution.

Each feed listing may also summarize additional license terms with the following parameters:

  • create_derived_products (allowed values: yes, no, unknown): Are feed consumers allowed to create and share derived products from the feed?
  • redistribution_allowed (allowed values: yes, no, unknown): Are feed consumers allowed to redistribute the feed in its entirety? If this parameters is set to no, Transitland will not allow downloading of feed versions.
  • commercial_use_allowed (allowed values: yes, no, unknown): Are feed consumers allowed to use the feed for commercial purposes?
  • share_alike_optional (allowed values: yes, no, unknown): Are feed consumers allowed to keep their modifications of this feed private? This parameter is most relevant to feeds licensed under the Open Data Commons Open Database License (ODbL). For a summary of the ODbL and its requirements for "share-alike" and "keep open" see this summary from Open Data Commons.

The v2 REST and GraphQL APIs allow users to filter results based on the license parameters for each source feed. For example, this allows users to search for transit stops within an area excluding stops that are sourced from feeds that require share-alike.

Transitland Atlas may provide incomplete or incorrect information about source feed licenses. We do not guarantee completeness or accuracy. We welcome corrections and additions to the Transitland Atlas repository on GitHub. Feed producers whose feeds are not correctly listed in Transitland Atlas are welcome to email us at mailto:info@interline.io and we will fix any issues as promptly as possible.

GTFS static feed fetching and import

Transitland fetches and imports static GTFS feeds in a two-step process:

  • Feed fetch: Transitland runs feed fetching jobs throughout the day. URLs for each static feed are typically checked every hour. The contents of the feed are compared to feed versions already fetched from that URL (using a SHA1 hash). If the contents have changed, a new feed version is created and stored. This feed version is now available in Transitland's archive for downloading. However, the feed version's contents have not been fully imported, so many querying capabilities are not yet available. See feed import levels.
  • Feed import: A few times per day, Transitland runs a workflow to decide which feed versions are ready to be imported and marked as the active feed version.

GTFS Realtime feed fetching and caching

GTFS Realtime feeds are fetched by Transitland once per minute. The latest feed is cached for use by Transitland APIs, including the stop departures REST endpoint and many REST endpoints that can optionally include alerts.

Transitland does not currently allow API users to download entire protocol buffer (PB) messages from its cache of GTFS Realtime source feeds. API users can access subsets of information extracted GTFS Realtime source feeds and made available in JSON format.

GBFS feed fetching and caching

GBFS feeds are fetched by Transitland once every five minutes.

Select information extracted from GBFS feeds is made available for querying through the GraphQL API.

Browsing source feeds

To explore source feeds within the Transitland platform, use one or more of the following approaches: