RZonar is an R package for retrieving data from the Zonar API
Capabilities and limitations
RZonar is not a comprehensive Zonar client, nor does it aspire to be. It currently focuses on just a few API endpoints, including schedule, path, zones, idle events, and assets.
The RZonar package does not provide anything close to a 1:1 mapping to the Zonar API; if that’s what you want just use the Zonar API directly, e.g., via the httr2 package in R. Rather, RZonar offers high-level data retrieval and formatting using the Zonar API. It aspires to be more like an R-based version of the Zonar website, providing relatively easy access to Zonar data.
Function naming convention
Most functions in RZonar are prefixed with
zonar_get
. This makes for somewhat verbose function names,
but makes auto-completion easy in most modern editors and IDEs. Assuming
you use Rstudio
or similarly capable development environment you can generall just type
zonar_
and browse the completion suggesions to find the
function you are looking for.
Time-varying and time-invariant data
Many functions provided by RZonar require start
and end
arguments. This is your clue that the function
returns time-varying data. All such arguments may be specified as
character strings formatted as YYY-MM-DD HH:MM:SS
. For
example we can retrieve path data from 8-9 AM on December 14th 2022 like
this:
library(RZonar)
paths_12.12.22 <- zonar_get_paths(
start = "2022-12-14 08:00:00", end = "2022-12-14 09:00:00"
)
Other functions that require start
and end
arguments (and therefore return time-varying data) include
zonar_get_idle_events
and
zonar_get_schedules
.
Functions without start
or end
arguments
often return time-inverient data. For example, we can retrieve a list of
Assets (buses) like this:
assets <- zonar_get_assets()
Not that time-invariant data can and does change, e.g., when a new asset is added to the system. However the Zonar API does not allow you to retrieve time-stamped versions, i.e. we cannot easily get the asset list as it appeared on some arbitrary historical date.
RZonar does not currently provide much in the way of analysis or visualization, so it is often convenient to use other popular R packages for that purpose.
library(dplyr)
#>
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#>
#> filter, lag
#> The following objects are masked from 'package:base':
#>
#> intersect, setdiff, setequal, union
library(ggplot2)
library(sf)
#> Linking to GEOS 3.9.3, GDAL 3.5.2, PROJ 8.2.1; sf_use_s2() is TRUE
These packages make examining, manipulating, and plotting the data returned by RZonar easier:
glimpse(assets)
#> Rows: 1,500
#> Columns: 20
#> $ assetID <chr> "829", "190", "687", "688", "690", "693", "885", "868…
#> $ Asset <chr> "", "", "", "", "", "", "", "", "", "", "B445", "MS15…
#> $ tag <chr> "0", "25783", "25587", "25588", "21971", "26655", "0"…
#> $ fleet <chr> "0", "009898", "081", "082", "084", "087", "1", "1002…
#> $ type <chr> "Standard", "Standard", "Standard", "Standard", "Stan…
#> $ subtype <chr> "Auto-Created Sub-Type", NA, "MS", NA, NA, NA, "MS", …
#> $ mileage <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0"…
#> $ location <chr> "UNKNOWN", "Readville Yard", "Washington Yard", "Wash…
#> $ mileoffset <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0"…
#> $ enginehouroffset <chr> "0", "0", "0", "0", "0", "0", "0", "0", "1", "0", "1"…
#> $ inservice <chr> "02 Sep 2010", "09 Jul 2008", "09 Jul 2008", "09 Jul …
#> $ yardstat.stat <chr> "unknown", "unknown", "unknown", "unknown", "unknown"…
#> $ status <chr> "2", "2", "2", "2", "2", "2", "2", "2", "2", "2", "2"…
#> $ opstatus <chr> "unknown", "unknown", "unknown", "unknown", "unknown"…
#> $ name <chr> NA, "25783", "25587", "25588", "SB21971", "26655", NA…
#> $ vin <chr> NA, "4UZ3CJFA0YCG03369", "1GBHG31F611192561", "1GBHG3…
#> $ mfg <chr> NA, "FREIGHTLNR", "CHEVY", "CHEVY", "CHEVY", "CHEVY",…
#> $ gps <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ yardstat.yard <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ exsid <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
Using geographical information
RZonar typically returns geometry as Lat/Lon points or well-known text for simplicity and to avoid additional R package dependencies.