Skip to contents

Download GTFS Schedule feeds

Source: R/integration-tidytransit.R
download_feed.Rd

A convenience function for downloading GTFS Schedule feeds from the Mobility Database. This is a "one-stop-shop" that can search for feeds by provider/location and download them in a single call, or download a specific feed by ID.

Note: This function is specifically designed for GTFS Schedule feeds only. GTFS Realtime and GBFS feeds use a different data model and are not supported by this function.

This function was formerly called mobdb_download_feed().

Usage

download_feed(
  feed_id = NULL,
  provider = NULL,
  country_code = NULL,
  subdivision_name = NULL,
  municipality = NULL,
  exclude_flex = TRUE,
  feed_name = NULL,
  use_source_url = FALSE,
  dataset_id = NULL,
  latest = TRUE,
  status = "active",
  official = NULL,
  auth_args = NULL,
  ...
)

Arguments

feed_id

A string or data frame. The unique identifier for the feed (e.g., "mdb-2862"), or a single-row data frame from feeds() or mobdb_search(). If a data frame is provided, the feed ID will be extracted automatically. If provided, all other search parameters are ignored.

provider

A string. Filter by provider/agency name (partial match). Use this to search for feeds without knowing the feed_id.

country_code

A string. Two-letter ISO country code (e.g., "US", "CA").

subdivision_name

A string. State, province, or region name.

municipality

A string. City or municipality name.

exclude_flex

A logical. If TRUE (default), automatically exclude feeds with "flex" in the feed name (case-insensitive). GTFS-Flex feeds are an extension of the GTFS Schedule specification and may contain files that have unique schemas that may not work with standard GTFS tools.

feed_name

A string. Optional filter for feed name. If provided, only feeds whose feed_name contains this string (case-insensitive) will be considered. Use NULL (default) to skip this filter.

use_source_url

A logical. If FALSE (default), uses MobilityData's hosted/archived URL which ensures you get the exact version in their database. If TRUE, uses the provider's direct source URL which may be more current but could differ from MobilityData's version.

dataset_id

A string. Optional specific dataset ID for historical versions (e.g., "mdb-53-202510250025"). If provided, downloads that specific dataset version instead of the latest. Cannot be used with use_source_url = TRUE. If dataset_id is provided without feed_id, the feed ID will be automatically extracted from the dataset ID format.

latest

A logical. If TRUE (default), download the most recent dataset. If FALSE, returns information about all available datasets for the feed without downloading. Only works when feed_id is provided directly; cannot be used with search parameters like provider or country_code.

status

A string. Feed status filter: "active" (default), "deprecated", "inactive", "development", or "future". Only used when searching by provider/location.

official

A logical. If TRUE (default), return official feeds and feeds with unknown official status (NA) when searching by provider/location. If FALSE, only return feeds explicitly marked as unofficial. If NULL, return all feeds regardless of official status.

auth_args

A string. Some agencies require authentication to download feeds directly from their source URLs. Provide your API key/token in one of two formats:

  • Just the value: "your_api_key_here"

  • Parameter and value: "apikey=your_api_key_here"

Also accepts a value stored in .Renviron (.e.g Sys.getenv("AGENCY_API_KEY") stored in the same formats) Only valid when use_source_url = TRUE. If a feed requires authentication, you'll receive an error message with a link to obtain credentials. The authentication method (URL parameter or HTTP header) is determined automatically from the feed's metadata.

...

Additional arguments passed to tidytransit::read_gtfs().

Value

If latest = TRUE, a gtfs object as returned by tidytransit::read_gtfs(). If latest = FALSE, a tibble of all available datasets with their metadata.

See also

mobdb_datasets() to list all available historical versions, get_validation_report() to check feed quality before downloading, feeds() to search for feeds, mobdb_read_gtfs() for more flexible GTFS reading

Examples

if (FALSE) { # \dontrun{
# Download by feed ID
gtfs <- download_feed("mdb-2862")

# Download from search results
feeds <- feeds(provider = "TransLink")
gtfs <- download_feed(feeds[36, ])

# Search and download by provider name
gtfs <- download_feed(provider = "Arlington")

# Download using agency's source URL instead of MobilityData
gtfs <- download_feed(provider = "TriMet", use_source_url = TRUE)

# Download from agency requiring API authentication
gtfs <- download_feed(
  provider = "WMATA",
  feed_name = "Rail",
  use_source_url = TRUE,
  auth_args = "your_wmata_api_key"
)

# Filter by location
gtfs <- download_feed(
  country_code = "US",
  subdivision_name = "California",
  municipality = "San Francisco"
)

# Search and download all feeds, including unofficial ones
gtfs <- download_feed(provider = "TTC", official = NULL)

# See all available versions for a feed
versions <- download_feed("mdb-2862", latest = FALSE)

# Download a specific historical version (feed_id auto-extracted from dataset_id)
historical <- download_feed(dataset_id = "mdb-53-202507240047")

} # }