https://github.com/quant-aq/r-quantaq
The official R wrapper for the QuantAQ API
https://github.com/quant-aq/r-quantaq
Last synced: 6 months ago
JSON representation
The official R wrapper for the QuantAQ API
- Host: GitHub
- URL: https://github.com/quant-aq/r-quantaq
- Owner: quant-aq
- License: apache-2.0
- Created: 2019-05-22T02:06:09.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2023-12-13T18:41:59.000Z (over 2 years ago)
- Last Synced: 2024-12-17T02:03:43.375Z (over 1 year ago)
- Language: R
- Size: 74.2 KB
- Stars: 3
- Watchers: 5
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-air-quality - r-quantaq - The official R wrapper for the QuantAQ API (Software Libraries)
README
# r-quantaq
[](https://github.com/christopherDT/r-quantaq/actions/workflows/R-CMD-check.yaml)
An R wrapper for the QuantAQ RESTful API.
**NOTE**:
As of Aug 30th, 2023, this package is in **active development** and will be updated in potentially breaking ways until the first release.
# Installation
Currently, you must install directly from GitHub:
```R
# If you don't have devtools installed:
install.packages("devtools")
# Install the library from GitHub
devtools::install_github(repo="quant-aq/r-quantaq")
```
# Docs
Complete documentation is available [here](). A quick-start guide follows:
# Getting Started
To use `r-quantaq`, import it:
```R
library("QuantAQAPIClient")
```
## Authentication
To use the QuantAQ API, you must have an API key. To obtain an API key, please follow the instructions [here](https://docs.quant-aq.com/api#541cc94f0c3a41abbb0200b69bb8d9e2).
To begin, call `setup_client()` to set your API Key. By passing `verbose = TRUE`, you will receive a message on successful connection to the API. It's possible, but not recommended, to include your API Key in the function as an argument, (i.e., `setup_client(api_key = )`). We recommend that RStudio users call `setup_client()` without arguments, and RStudio will use its automatic secret key manager. You can then follow the prompt to install the keyring package, which saves the key so you don't have to enter it every time.
## Utility Functions
To receive data as a dataframe (rather than json), you can use the `as.data.frame` function:
```R
# Return data as a dataframe
as.data.frame(get_data(""))
# Pipe it through
get_data("") %>% as.data.frame()
```
## Basic Functions
### `whoami()`
`whoami()` returns your basic account information.
```R
# Get your account information
account <- whoami()
```
### `get_data(sn, limit=100, start=NULL, stop=NULL, filter=NULL, sort=NULL, raw=FALSE)`
Return all data for a device by its serial number.
```R
# Get the data for a device with all defaults
x <- as.data.frame(get_data(""))
# Get the first 10 records for a device
x <- as.data.frame(get_data("", limit=10))
# Get the raw data
x <- as.data.frame(get_data("", raw=TRUE))
```
### `get_organizations(organization_id=NULL)`
Return a list of all organizations you can view,
or the particular organization with id=organization_id.
```R
# Get the list of organizations
x <- get_organizations()
```
### `get_networks(organization_id, network_id=NULL)`
Return a list of all networks you can can view in
the context of the particular organization with id=organization_id,
or the particular network with id=network_id within that organization.
```R
# Get the list of networks in organization 1
x <- get_networks(organization_id = 1)
```
### `get_devices(sn=NULL, limit=NULL, sort=NULL)`
Get a list of all devices you have access to.
```R
# Get a list of the first 25 devices as a dataframe
x <- as.data.frame(get_devices(limit=25))
```
### `get_data_by_date(sn, date, raw=FALSE)`
Return the data for a device by the date. This is the most efficient way to grab a lot of data as it is cached and ready to download.
```R
# Get the data for date as a dataframe
x <- as.data.frame(get_data_by_date("", "2023-08-30"))
# Get the raw data for date as a dataframe
x <- as.data.frame(get_data_by_date("", "2023-08-30", raw=TRUE))
```
## Advanced Queries
Advanced requests are available by named keywords, examples below. See the [API docs](https://docs.quant-aq.com/api#1bcd5e949cb74e63ab25d214d600e1af) for more information.
## Filter
Format as `filter = ',,;,,;'`. Append as many filters as desired.
```R
# returns data where pm25 >= 25 and <= 50
get_data("", filter = 'pm25,ge,25;pm25,le,50')
# returns only data where device is on, i.e. device_state == ACTIVE
get_data("", filter = "device_state,eq,ACTIVE")
```
## Limit
Format as `limit = `.
```R
# returns 25 devices
get_devices(limit = 25)
# returns first 10 timestamps of data
get_data(""), limit = 10)
```
## Sort
Include `sort = ''`, where 'order' is one of "asc" or "desc".
```R
# returns data in descending order by timestamp
get_data(""), sort = 'timestamp,desc')
```
, and each `get_` function GETs the data from its similarly-named API endpoint. Each of these can be piped or passed to `as.data.frame` for nicer formatting, e.g. to get data from device serial number `MOD-PM-00233`:
# Development
Tests are run automatically when pull requests are made against the `main` branch via a github action. To run locally:
```R
devtools::test()
```
To build a new version of the docs pdf:
```R
devtools::document() # in case any changes were made to the documentation in the code
devtools::build_manual() # to build the pdf
```
To contribute to this library, please submit a pull request with documentation and notes about what changed and why. Please be as descriptive as possible, add tests where necessary, and add an appropriate label. A QuantAQ maintainer will review and merge PRs as they are received.
If you notice any bugs or have questions about this library, please create an Issue using the GitHub Issues feature.