Download the "best" GTFS Schedule feed with smart selection

A wrapper around download_feed() that automagically selects the best GTFS Schedule feed when multiple options exist. This function:

• Searches for feeds using provider name or location

• Ranks feeds by status, official designation, and validation quality

• Prompts for user selection when multiple equally-ranked feeds exist (in interactive mode)

• Falls back to historical datasets when current feed is marked "future" or "inactive"

• Only works with GTFS Schedule feeds (not GTFS-RT or GBFS)

This is designed for use cases where you just want the best, most recent feed without needing to specify exact feed IDs or handle multiple results manually.

Usage

download_best_feed(
  provider = NULL,
  country_code = NULL,
  subdivision_name = NULL,
  municipality = NULL,
  feed_name = NULL,
  prefer_official = TRUE,
  prefer_active = TRUE,
  max_validation_errors = NULL,
  interactive = NULL,
  exclude_flex = TRUE,
  use_source_url = FALSE,
  auth_args = NULL,
  export_path = NULL,
  raw = NULL,
  ...
)

Arguments

provider

Provider/agency name (partial match).

country_code

ISO 2-letter country code (requires subdivision_name).

subdivision_name

State/province/region name (requires country_code).

municipality

City name.

feed_name

Feed name filter (case-insensitive substring match).

prefer_official

Logical. If TRUE (default), prefer feeds marked as official.

prefer_active

Logical. If TRUE (default), prefer feeds with status "active" over "future", "development", "deprecated", or "inactive".

max_validation_errors

Integer. Maximum number of validation errors allowed. Feeds exceeding this threshold are filtered out. If NULL (default), no filtering.

interactive

Logical. If TRUE, prompt user to select when multiple equally-ranked feeds exist. If FALSE, automatically select the first highest-ranked feed with a warning. If NULL (default), uses getOption("mobdb.interactive") or falls back to interactive() to detect if running in an interactive R session.

exclude_flex

Logical. If TRUE (default), exclude GTFS-Flex feeds.

use_source_url

Logical. Download from agency's source URL (TRUE) or Mobility Database's hosted URL (FALSE, default).

auth_args

Authentication arguments if required (see download_feed()).

export_path

A string. Optional path to save the GTFS feed as a ZIP file (e.g., "data/gtfs/feed.zip"). See download_feed() for details.

raw

A logical. Controls whether the file saved to export_path is the raw download (TRUE) or a parsed-and-re-exported version (FALSE). Defaults to TRUE when export_path is provided, FALSE otherwise.

...

Additional arguments passed to tidytransit::read_gtfs().

Value

If export_path is provided with raw = TRUE (the default when exporting), the file path (invisibly). Otherwise, a gtfs object from tidytransit, or NULL if user cancels selection.

Selection algorithm

When multiple feeds match the search criteria, feeds are ranked by:

1. Status (if prefer_active = TRUE): active > future > development > inactive > deprecated

2. Official designation (if prefer_official = TRUE): official > unclassified > unofficial

3. Validation quality: Feeds with fewer errors score higher

4. Service date coverage: Feeds covering today's date score higher

5. Recency: More recently added feeds get a tiebreaker boost

If multiple feeds have the same score and interactive = TRUE, you'll be prompted to choose.

Status handling

The function handles different feed statuses as follows:

• "active": Preferred. Feed should be used in public trip planners.

• "future" or "inactive": Automatically searches for historical datasets with service dates covering today. "future" feeds are not yet active; "inactive" feeds haven't been recently updated and may provide outdated information.

• "deprecated": Explicitly deprecated and shouldn't be used. Warns user to search for a replacement feed.

• "development": For development purposes only, shouldn't be used in production.

GTFS Schedule Only

Like download_feed(), this function only works with GTFS Schedule feeds. For GTFS-RT or GBFS feeds, use mobdb_read_gtfs() or fetch URLs with mobdb_get_feed().

See also

download_feed() for precise control, feeds() to explore available feeds before downloading, mobdb_search() for full-text search with validation data

Examples

if (FALSE) { # mobdb_can_run_examples() && mobdb_has_tidytransit()
# Simple one-shot download by provider name
bart_feed <- download_best_feed(provider = "Bay Area Rapid Transit")

# Download with quality filtering
clean_feed <- download_best_feed(
  provider = "Capital Metro",
  max_validation_errors = 0
)

# Download by location
ontario_feed <- download_best_feed(
  country_code = "CA",
  subdivision_name = "Ontario"
)

# Non-interactive mode (for scripts)
options(mobdb.interactive = FALSE)
feed <- download_best_feed(provider = "WMATA")
}