Downloads environmental sensor data from the ZENTRA Cloud V5 API (< https://api.zentracloud.io>) into tidy data frames. Provides device discovery, reading retrieval with automatic pagination and rate-limit handling, tidy long output with a wide-format helper, and an incremental 'sync' engine with pluggable local storage (RDS files, CSV files, or return-only) so that new readings can be fetched on a schedule and appended to a growing local record.
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.
zc_list_devices() lists every device your key can access.zc_get_readings() returns one row per measurement, ready
for dplyr / ggplot2, with a zc_pivot_wider() helper for a spreadsheet layout.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).zc_sync() on file open, daily, or weekly. See the
Scheduling automatic syncs vignette.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")
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
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)
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.
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.
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:
MIT © METER Group, Inc.