Contents
Documentation
Source feeds
Last updated
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 systems.
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 continuous integration job running on GitHub Actions ensures that Onestop IDs are not duplicated.
The geohash component is optional for feed Onestop IDs, so f-galesburg~il~us is valid. See the Onestop ID scheme.
Transitland Atlas tracks deprecated Onestop IDs for some feed and operator records in supersedes_ids. Transitland APIs and the Transitland website do not query feeds or operators by 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:
| Field | Description |
|---|---|
url | A URL for a custom license, or for a webpage that identifies a standard open license attached to the feed |
spdx_identifier | A standard identifier for an open license. For example, CC-BY-4.0 is the SPDX identifier for the Creative Commons Attribution 4.0 International license. See the full list of SPDX identifiers. |
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 Transitland users provide a link to https://www.transit.land/terms, on every plan except Enterprise and commercial Datasets licenses. 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:
| Field | Description |
|---|---|
use_without_attribution | yes, no, or unknown: Are feed consumers allowed to use the feed contents without including attribution text in their app or map? Transitland users outside Enterprise and commercial Datasets licenses are always required to attribute Transitland by linking to https://www.transit.land/terms, which meets all attribution requirements on source feeds. |
attribution_text | Feed consumers must include this text when using this feed. This text is automatically included on 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:
| Field | Description |
|---|---|
create_derived_product | yes, no, or unknown: Are feed consumers allowed to create and share derived products from the feed? |
redistribution_allowed | yes, no, or unknown: Are feed consumers allowed to redistribute the feed in its entirety? When set to no, Transitland does not allow downloading of feed versions or of cached GTFS Realtime data. |
commercial_use_allowed | yes, no, or unknown: Are feed consumers allowed to use the feed for commercial purposes? |
share_alike_optional | yes, no, or unknown: Are feed consumers allowed to keep their modifications of this feed private? This is most relevant to feeds licensed under the Open Data Commons Open Database License (ODbL). See the ODbL summary from Open Data Commons for its "share-alike" and "keep open" requirements. |
The v2 REST and GraphQL APIs allow users to filter results based on the license parameters for each source feed. The REST API takes license_ query parameters, such as license_share_alike_optional, on the feeds, agencies, operators, routes, stops, and trips endpoints. 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 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 (using SHA1 checksums). 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 yet been imported, so many querying capabilities are not yet available. See new feed versions.
- Feed import: Every hour, Transitland runs a workflow that imports newly fetched feed versions and selects each feed's 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.
The cached GTFS Realtime feeds can be downloaded in their original Protocol Buffer (PB) format or as JSON, and vehicle positions also as GeoJSON. Three types of GTFS Realtime feeds are supported:
- Vehicle positions: Real-time location of transit vehicles
- Trip updates: Real-time updates to scheduled trips
- Service alerts: Information about service disruptions and other alerts
See also downloading latest GTFS Realtime.
GBFS feed fetching and caching
GBFS feeds are fetched by Transitland approximately every 10 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:
- Easy: Browse the Source Feeds section on the Transitland website.
- Intermediate: Query the REST API feed endpoint.
- Advanced: Query the GraphQL API.
- Advanced: Parse DMFR files from the Transitland Atlas repository on GitHub.