Skip to contents

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.