Contents
REST API - Feeds
Feeds
Transitland is built on publicly available GTFS data contributed by our user community to the Transitland Atlas.
Feeds contain details on how to access transit information, including URLs to data sources in various formats (GTFS, GTFS-RT, GBFS, etc), license information, related feeds, details on how to make authorized requests, and feed version archives. Feed versions are archived (as .zip
files) and imported into the Transitland database for querying agencies, stops, routes, trips, etc.
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 feedspdx_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/termsattribution_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 tono
, 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 info@interline.io and we will fix any issues as promptly as possible.
Request overview
The feeds API provides a number of searching and filtering parameters; results are based on this GraphQL query.
Request parameters
GET/api/v2/rest/feeds Feeds — Search for feeds
GET/api/v2/rest/feeds.{format} — Request feeds in specified format
GET/api/v2/rest/feeds/{feed_key} — Request a feed by ID or Onestop ID
GET/api/v2/rest/feeds/{feed_key}.{format} — Request a feed by ID or Onestop ID in specified format
Parameter | Type | Description | Example |
---|---|---|---|
id | integer 0 ... unlimited | Search for a specific internal ID | |
feed_key | string | Feed lookup key; can be an integer ID or a Onestop ID | |
after | integer | Return records past this record ID | |
limit | integer 0 ... 100 | Maximum number of records to return | limit=1 |
format | enum | Response format | format=geojson |
search | string | Full text search | search=caltrain |
onestop_id | string | Search for a specific Onestop ID | onestop_id=f-9q9-caltrain |
spec | string enum | Type of data contained in this feed | spec=gtfs |
fetch_error | string enum | Search for feeds with or without a fetch error | fetch_error=true |
tag_key | string | Search for feeds with a tag. Combine with tag_value also query for the value of the tag. | tag_key=gtfs_data_exchange |
tag_value | string | Search for feeds tagged with a given value. Must be combined with tag_key. | tag_key=unstable_url&tag_value=true |
license_commercial_use_allowed | enum | Filter entities by feed license 'commercial_use_allowed' value. Please see feed documentation for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'. | |
license_share_alike_optional | enum | Filter entities by feed license 'share_alike_optional' value. Please see feed documentation for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'. | |
license_create_derived_product | enum | Filter entities by feed license 'create_derived_product' value. Please see feed documentation for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'. | |
license_redistribution_allowed | enum | Filter entities by feed license 'redistribution_allowed' value. Please see feed documentation for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'. | |
license_use_without_attribution | enum | Filter entities by feed license 'use_without_attribution' value. Please see feed documentation for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'. |
Response format
Array of objects
Description Distributed mobility data registry (DMFR) feed
Reference DMFR Schema
id
(integer)
(integer)
Unique integer ID
onestop_id
(string)
(string)
Onestop ID for this feed
Examplef-9q9-bart
name
(string)
(string)
A common name for this feed
ExampleBay Area Rapid Transit
spec
(string)
(string)
Type of data contained in this feed: GTFS, GTFS-RT, GBFS, or MDS
languages
(string array)
(string array)
Language(s) included in this feed
Example{ "0": "en-US" }
feed_versions
(object array)
(object array)
A subset of fields for the feed versions associated with this feed
urls
(object)
(object)
URLs that provide data associated with this feed
static_current
(string)
(string)
URL for the static feed that represents today's service
Examplehttps://www.bart.gov/dev/schedules/google_transit.zip
static_historic
(string array)
(string array)
URLs for static feeds that represent past service that is no longer in effect
static_planned
(string)
(string)
URLs for static feeds that represent service planned for upcoming dates. Typically used to represent calendar/service changes that will take effect few weeks or months in the future
realtime_vehicle_positions
(string)
(string)
URL for GTFS Realtime VehiclePosition messages
realtime_trip_updates
(string)
(string)
URL for GTFS Realtime TripUpdate messages
realtime_alerts
(string)
(string)
URL for GTFS Realtime Alert messages
gbfs_auto_discovery
(string)
(string)
URL for GBFS auto discovery
mds_provider
(string)
(string)
URL for MDS endpoint
license
(object)
(object)
License information for this feed, if present
spdx_identifier
(string)
(string)
SPDX identifier for a common license. See https://spdx.org/licenses/
ExampleCC-BY-4.0
url
(string)
(string)
URL for a custom license
Examplehttp://www.actransit.org/data-terms-and-conditions/
use_without_attribution
(string)
(string)
Are feed consumers allowed to use the feed contents without including attribution text in their app or map?
create_derived_product
(string)
(string)
Are feed consumers allowed to create and share derived products from the feed?
redistribution_allowed
(string)
(string)
Are feed consumers allowed to redistribute the feed in its entirety?
commercial_use_allowed
(string)
(string)
Are feed consumers allowed to use the feed for commercial purposes?
share_alike_optional
(string)
(string)
Are feed consumers allowed to keep their modifications of this feed private?
attribution_text
(string)
(string)
Feed consumers must include this particular text when using this feed
Exampledata provided by 511.org
attribution_instructions
(string)
(string)
Feed consumers must follow these instructions for how to provide attribution
ExampleYou must acknowledge the source of the provided data...
auth
(object)
(object)
Details on how to construct an HTTP request to access a protected resource
type
(string)
(string)
Method for inserting authorization secret into request
param_name
(string)
(string)
When type=query_param, this specifies the name of the query parameter. When type=header, this specifies the name of the header.
info_url
(string)
(string)
Website to visit to sign up for an account
feed_state
(object)
(object)
Details on the current state of this feed, such as active version, last fetch time, etc.
last_fetch_error
(string)
(string)
Error produced during the last fetch attempt. Empty string if no error.
Example404 error
last_fetched_at
(datetime)
(datetime)
Time of last attempted fetch
Example2019-11-15T00:45:55.409906
last_successful_fetch_at
(datetime)
(datetime)
Time of last successful fetch that returned valid data
Example2019-11-15T00:45:55.409906
feed_version
(object)
(object)
The subset of fields of the active feed version. See feed version documentation for full details.
geometry
(object)
(object)
Geometry in GeoJSON format
type
(string)
(string)
GeoJSON geometry type
ExampleLineString
coordinates
(number array)
(number array)
An array of coordinates; may be nested arrays if geometry is Polygon or MultiLineString
Example[ [ -122.496, 37.778 ], [ -122.425, 37.786 ] ]
Downloading source GTFS
GET/api/v2/rest/feeds/{feed_key}/download_latest_feed_version — Download latest feed version for this feed
Description Download the latest feed version GTFS zip for this feed, if redistribution is allowd by the source feed's license