Update to match latest OpenAPI Spec

Author: ankoure

R/aggregate.R

@@ -2,7 +2,10 @@
 #'
 #' Retrieves aggregated travel time data over a date range and stop pair.
 #' Common query parameters include `from_stop`, `to_stop`, `start_date`, and
-#' `end_date`.
+#' `end_date`. `from_stop` and `to_stop` take **stop IDs** (as returned by
+#' [tm_stop_id()], [tm_bus_stop_id()], or [tm_cr_stop_id()]), not place IDs.
+#' Multiple stop IDs for the same station can be passed by repeating the
+#' argument (e.g. `from_stop = c("70076", "70077")`).
 #'
 #' @param ... Named query parameters passed to the API (e.g., `from_stop`,
 #'   `to_stop`, `start_date`, `end_date`).
@@ -13,8 +16,8 @@
 #' @examples
 #' \dontrun{
 #' tm_aggregate_travel_times(
-#'   from_stop  = "place-pktrm",
-#'   to_stop    = "place-davis",
+#'   from_stop  = "70076",
+#'   to_stop    = "70061",
 #'   start_date = "2024-01-01",
 #'   end_date   = "2024-01-31"
 #' )
@@ -34,8 +37,8 @@ tm_aggregate_travel_times <- function(..., base_url = tm_base_url()) {
 #' @examples
 #' \dontrun{
 #' tm_aggregate_travel_times2(
-#'   from_stop  = "place-pktrm",
-#'   to_stop    = "place-davis",
+#'   from_stop  = "70076",
+#'   to_stop    = "70061",
 #'   start_date = "2024-01-01",
 #'   end_date   = "2024-01-31"
 #' )

R/dated.R

@@ -59,25 +59,32 @@ tm_travel_times <- function(user_date, from_stop, to_stop,
 #' Get MBTA service alerts
 #'
 #' When `user_date` is `NULL` the undated `/api/alerts` endpoint is called,
-#' returning current alerts. Pass a date to retrieve alerts for a specific day.
+#' returning current live alerts (no parameters accepted). Pass a date to
+#' retrieve historical alerts for a specific day, optionally filtered by route.
 #'
 #' @param user_date A `Date` object, a `"YYYY-MM-DD"` string, or `NULL`
 #'   (default) for current alerts.
-#' @param route One or more MBTA route IDs (e.g. `"Red"`, `"Orange"`). Required.
-#'   Use [tm_routes()] to list valid IDs.
+#' @param route One or more MBTA route IDs (e.g. `"Red"`, `"Orange"`). Only
+#'   used when `user_date` is provided. Use [tm_routes()] to list valid IDs.
 #' @param base_url Base URL of the TransitMatters API. Defaults to
 #'   `getOption("tm_dashboard_base_url")` or the production host.
 #' @return A list with an `alerts` element.
 #' @export
 #' @examples
 #' \dontrun{
-#' tm_alerts(route = "Red")
+#' tm_alerts()
 #' tm_alerts("2024-01-15", route = "Red")
 #' }
-tm_alerts <- function(user_date = NULL, route, base_url = tm_base_url()) {
-  path <- if (is.null(user_date)) "api/alerts"
-          else c("api", "alerts", .tm_date(user_date))
-  tm_request(path, query = list(route = route), base_url = base_url)
+tm_alerts <- function(user_date = NULL, route = NULL, base_url = tm_base_url()) {
+  if (is.null(user_date)) {
+    tm_request("api/alerts", base_url = base_url)
+  } else {
+    tm_request(
+      c("api", "alerts", .tm_date(user_date)),
+      query = list(route = route),
+      base_url = base_url
+    )
+  }
 }
 
 #' Get stops for a route

R/parameterized.R

@@ -139,10 +139,11 @@ tm_ridership <- function(start_date, end_date, line_id = NULL,
 #' Get slow zone / speed restriction data
 #'
 #' Returns current or historical speed restrictions for an MBTA line on a given
-#' date.
+#' date. Only rapid transit lines are supported.
 #'
-#' @param line_id MBTA line identifier. Accepts any of `"Red"`, `"red"`,
-#'   `"line-red"`, or `"line-Red"` — all are equivalent.
+#' @param line_id Rapid transit line identifier. Valid lines: `"Red"`,
+#'   `"Orange"`, `"Blue"`, `"Green"`. Also accepts `"red"`, `"line-red"`,
+#'   `"line-Red"`, etc. — all are normalized internally.
 #' @param on_date The date to query. A `Date` object or `"YYYY-MM-DD"` string.
 #' @param base_url Base URL of the TransitMatters API. Defaults to
 #'   `getOption("tm_dashboard_base_url")` or the production host.

R/stops.R

@@ -78,8 +78,10 @@ tm_stop_id <- function(line, stop_name, direction) {
 
 #' Look up the GTFS place ID for a rapid transit station
 #'
-#' Returns the GTFS place identifier used by the aggregate travel-time
-#' endpoints (e.g. `"place-alfcl"`, `"place-davis"`).
+#' Returns the GTFS parent-station identifier (e.g. `"place-alfcl"`,
+#' `"place-davis"`). These are provided for cross-referencing with the MBTA v3
+#' API. The TransitMatters aggregate endpoints expect stop IDs from
+#' [tm_stop_id()], not place IDs.
 #'
 #' @inheritParams tm_stop_id
 #' @return A single GTFS place ID string.
@@ -187,7 +189,7 @@ tm_line_directions <- function(line) {
 #' @export
 #' @examples
 #' tm_bus_stop_id("1", "Harvard", "inbound")
-#' tm_bus_stop_id("66", "Harvard Square", "outbound")
+#' tm_bus_stop_id("66", "Harvard", "outbound")
 tm_bus_stop_id <- function(route, stop_name, direction) {
   key       <- .tm_normalize_route(route, .tm_bus_stations, "bus", "tm_bus_routes")
   rd        <- .tm_bus_stations[[key]]
@@ -246,6 +248,10 @@ tm_cr_stop_id <- function(route, stop_name, direction) {
 
 #' Look up the GTFS place ID for a commuter rail station
 #'
+#' Returns the GTFS parent-station identifier (e.g. `"place-sstat"`). These
+#' are provided for cross-referencing with the MBTA v3 API. The TransitMatters
+#' aggregate endpoints expect stop IDs from [tm_cr_stop_id()], not place IDs.
+#'
 #' @param route CR route ID. Use [tm_cr_routes()] to see all valid IDs.
 #' @param stop_name Station name (case-insensitive).
 #' @return A single GTFS place ID string (e.g. `"place-sstat"`).