zentraR

zentraR is an R client for the ZENTRA Cloud v5 API. It gets you from “I have an API key” to “I have a tidy, up-to-date data frame of my sensor readings” in a few lines — handling authentication, pagination, rate limits, and reshaping so you can get straight to analysis.

Features

Device discovery — zc_list_devices() lists every device your key can access.
Tidy readings — zc_get_readings() returns one row per measurement, ready for dplyr / ggplot2, with a zc_pivot_wider() helper for a spreadsheet layout.
Automatic pagination & rate-limit handling — large pulls just work; the client paces itself and retries on throttling.
Incremental sync with pluggable storage — zc_sync() fetches only what’s new and appends it to your store of choice: native R files (zc_store_rds()), plain CSV (zc_store_csv()), or nothing at all (return-only, for loading into your own database).
Schedule-friendly — run zc_sync() on file open, daily, or weekly. See the Scheduling automatic syncs vignette.

Installation

Install from the METER Group public packages group on GitLab:

# install.packages("remotes")
remotes::install_gitlab("meter-group-inc/pubpackages/zentraR")

Alternatively, download the package file (zentraR_0.1.0.tar.gz) from the Installation section of the Getting Started with zentraR guide and install it locally:

install.packages(c("httr2", "cli", "rlang", "tibble", "tidyr", "vctrs"))
install.packages("zentraR_0.1.0.tar.gz", repos = NULL, type = "source")

Authentication

Get your API key from ZENTRA Cloud: User Account → Integrations → Show Token (https://app.zentracloud.io/profile/integrations). Then either set it for the session, or save it to your .Renviron so it’s always available:

library(zentraR)

zc_set_key("your-api-key")                 # this session only
zc_set_key("your-api-key", install = TRUE) # persist across sessions

Quick start

library(zentraR)

# 1. What devices can I see?
devices <- zc_list_devices(expand = "max_min_timestamp")
devices

# 2. Pull the last week of readings for one device (tidy long format).
readings <- zc_get_readings("z6-00930", start = Sys.Date() - 7)
readings

# 3. Reshape to one column per measurement.
zc_pivot_wider(readings)

# 4. Add human-readable quality flags.
zc_label_errors(readings)

Keeping a local record up to date

zc_sync() remembers what you already have and fetches only newer readings, so you can run it on a routine. Pick where the data lives:

# Persist as CSV (accessible to non-R tools):
store <- zc_store_csv("data/zentra")

# First run backfills history; later runs fetch only what's new:
zc_sync("z6-00930", store = store, start = Sys.Date() - 30)
zc_sync("z6-00930", store = store)   # incremental

# Sync every device your key can access:
zc_sync(store = store)

# Read your accumulated data back:
zc_store_read(store)

Prefer native R objects for an RStudio project? Use zc_store_rds("data/zentra"). Piping into your own database? Pass store = NULL and zc_sync() simply returns the new readings.

Rate limits

The v5 API is limited per key: roughly a 5-request burst, then about one request per minute. zentraR respects this automatically (pacing and retrying), but very large historical backfills will take time. Because zc_sync() is incremental and resumable, routine top-ups stay well within the limit.

Learn more

Built-in vignettes:

vignette("getting-started", package = "zentraR")
vignette("working-with-data", package = "zentraR")
vignette("scheduling", package = "zentraR")

Online (kept current with the API) on ZENTRA Cloud: