Documentation

REST API - Feeds

Feeds

The REST API feeds endpoint provides a fast and flexible way to browse source feeds registered in the Transitland platform.

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 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

ParameterTypeDescriptionExample
feed_keystring

Feed lookup key; can be a Onestop ID or an internal database integer ID
specstring enum
gtfsgtfs-rtgbfsmds
Type of data contained in this feedspec=gtfs
fetch_errorstring enum
truefalse
Search for feeds with or without a fetch errorfetch_error=true
tag_keystring

Search for feeds with a tag. Combine with tag_value also query for the value of the tag.tag_key=gtfs_data_exchange
tag_valuestring

Search for feeds tagged with a given value. Must be combined with tag_key.tag_key=unstable_url&tag_value=true
idinteger

Search for a specific internal ID
afterinteger

Pagination cursor value. This should be treated as an opaque value created by the server and returned as the link to the next result page, which may be empty. For historical reasons, this is based on the integer record ID values, but that should not be assumed to be the case in the future.
limitinteger

Maximum number of records to returnlimit=1
formatstring enum
jsongeojsongeojsonl
Response formatformat=geojson
searchstring

Full text searchsearch=caltrain
onestop_idstring

Search for a specific Onestop IDonestop_id=f-sf~bay~area~rg
lonnumber

Longitude
latnumber

Latitude
radiusnumber

Search radius (meters); requires lat and lonlon=-122.3?lat=37.8&radius=1000
bboxstring

Geographic search using a bounding box, with coordinates in (min_lon, min_lat, max_lon, max_lat) order as a comma separated stringbbox=-122.269,37.807,-122.267,37.808
license_commercial_use_allowedstring enum
yesnounknownexclude_no
Filter entities by feed license 'commercial_use_allowed' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.
license_share_alike_optionalstring enum
yesnounknownexclude_no
Filter entities by feed license 'share_alike_optional' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.
license_create_derived_productstring enum
yesnounknownexclude_no
Filter entities by feed license 'create_derived_product' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.
license_redistribution_allowedstring enum
yesnounknownexclude_no
Filter entities by feed license 'redistribution_allowed' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.
license_use_without_attributionstring enum
yesnounknownexclude_no
Filter entities by feed license 'use_without_attribution' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.

Response format


feeds
array: Feed
List or search for Feeds (metadata about data sources)
id
integer
Internal integer ID
spec
object: FeedSpecTypes
Type of feed: GTFS, GTFS_RT, GBFS, or MDS
EnumGTFSGTFS_RTGBFSMDS
name
string
A common name for this feed; alternatively use associated_operators[].name
onestop_id
string
Onestop ID for this feed. Format: f-geohash-name. Example: f-9q9-bart.
languages
array: String
Language(s) included in this feed (BCP 47 tags)
tags
object
Atlas tags providing additional metadata for this feed
urls
object: FeedUrls
URLs associated with this feed
static_current
string
URL for the static feed that represents today's service
static_historic
array: String
URLs for static feeds that represent past service that is no longer in effect
static_planned
array: String
URLs for static feeds representing planned future service (typically schedule changes due to take effect)
realtime_vehicle_positions
string
URL for GTFS-RT VehiclePosition messages
realtime_trip_updates
string
URL for GTFS-RT TripUpdate messages
realtime_alerts
string
URL for GTFS-RT Alert messages
gbfs_auto_discovery
string
URL for the GBFS auto-discovery file (gbfs.json)
mds_provider
string
URL for the MDS (Mobility Data Specification) provider endpoint
license
object: FeedLicense
Feed license metadata
spdx_identifier
string
SPDX identifier for a common license (see https://spdx.org/licenses/); empty if no SPDX license applies
url
string
URL to a custom license; empty if a SPDX license is used or no license is recorded
use_without_attribution
string
Whether feed consumers may use the feed without attribution
create_derived_product
string
Whether feed consumers may create and share derived products
redistribution_allowed
string
Whether feed consumers may redistribute the feed in its entirety
commercial_use_allowed
string
Whether feed consumers may use the feed for commercial purposes
share_alike_optional
string
Whether feed consumers may keep their modifications of this feed private
attribution_text
string
Attribution text that consumers must include when using this feed
attribution_instructions
string
Instructions for how consumers must provide attribution
authorization
object: FeedAuthorization
Authorization metadata for fetching data from this feed (e.g., API keys, headers)
type
string
Method for inserting the authorization secret into the request: header, basic_auth, query_param, path_segment, or replace_url
param_name
string
Name of the request parameter that carries the secret (query string key, header name, or URL path placeholder, depending on type); unused for basic_auth and replace_url
info_url
string
Website to visit to sign up for an account
feed_state
object: FeedState
Current state of this feed (e.g. the active feed version)
feed_version
object: FeedVersion
The active feed version for this feed. This is the version currently used for queries
feed_versions
array: FeedVersion
Versions of this feed that have been fetched, archived, and imported
id
integer
Internal integer ID
sha1
string
SHA1 hash of the zip file

Exampleab5bdc8b6cedd06792d42186a9b542504c5eef9a

fetched_at
string
Time when the file was fetched from the URL

Example2019-11-15T00:45:55.409906

url
string
URL used to fetch the file
earliest_calendar_date
string
The earliest date with scheduled service

Example2020-01-01

latest_calendar_date
string
The latest date with scheduled service

Example2020-12-31

Downloading latest static GTFS

See also downloading static GTFS feed versions.

GET/api/v2/rest/feeds/{feed_key}/download_latest_feed_version Download latest feed version

ParameterTypeDescriptionExample
feed_keystring

Feed lookup key; can be an integer ID or Onestop ID value
Description Download the latest feed version GTFS zip for this feed, if redistribution is allowed by the source feed's license

Downloading latest GTFS Realtime

For more information about GTFS Realtime message types and fields, see the GTFS Realtime reference documentation.

GET/api/v2/rest/feeds/{feed_key}/download_latest_rt/{rt_type}.{format} Download latest GTFS Realtime feed data

ParameterTypeDescriptionExample
feed_keystring

Feed lookup key; can be an integer ID or Onestop ID value
rt_typestring enum
alertstrip_updatesvehicle_positions
GTFS Realtime message types to download
formatstring enum
jsonpbgeojsongeojsonl
Output format (JSON, Protocol Buffers, or GeoJSON for vehicle positions)
Description Download the latest snapshot of the specified GTFS Realtime feed, if redistribution is allowed by the source feed's license. Returns 404 if feed or message not found, 401 if redistribution not allowed.