-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
108 lines (70 loc) · 3.04 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# rweatherlink
<!-- badges: start -->
[](https://www.tidyverse.org/lifecycle/#maturing)
[](https://CRAN.R-project.org/package=rweatherlink)
[](https://github.com/basf/rweatherlink/actions)
[](https://codecov.io/gh/basf/rweatherlink?branch=master)
<!-- badges: end -->
An R client for [Weatherlink v2 API](https://weatherlink.github.io/v2-api/)
## Usage
```{r load, eval=FALSE}
library("rweatherlink")
```
### Authentication
The api key and api secret are read by default from environmental variables
`WL_API_KEY` and `WL_API_SECRET`, but you can provide them also in every function call
using the `api_key=` and `api_secret=` arguments.
### Basic usage
For each endpoint we provide convenience wrappers, like
```{r basic, eval=FALSE}
wl_stations()
```
The full list of endpoints wrappers is:
* `wl_stations()` for `/stations` & `stations/{station-ids}` endpoints
* `wl_nodes()` for `/nodes` & `nodes/{nodes-ids}` endpoints
* `wl_sensors()` for `/sensors` & `sensors/{sensor-ids}` endpoints
* `wl_sensor_activity()` for `/sensor-activity` & `sensor-activity/{sensor-ids}` endpoints
* `wl_sensor_catalog()` for `/sensor-catalog` endpoint
* `wl_current()` for `/current/{station-id}` endpoint
* `wl_historic()` for `/historic/{station-id}` endpoint
### Parsers
For each of the listed functions (except `wl_sensor_catalog()`) we provide
(opinionated) convenience parsers, that parse the return value into a nice `data.frame`.
Columns with UTC-dates for timestamps are added, as well as elevation in meters.
The generic function for all objects is `wl_parse()`
```{r parser, eval=FALSE}
wl_stations() %>% wl_parse()
wl_sensors() %>% wl_parse()
```
These parsers are in an experimental stage.
### Timestamps
`wl_historic()` needs unix-timestamps as input for start and end.
These can be easily generated from `POSIXct` objects, e.g.
```{r timestamp}
as.integer(Sys.time())
```
gives the timestamp of the current time.
## Under the hood
`wl_request()` is the workhorse of this package.
With it you can query every API endpoint, e.g.
```{r request, eval=FALSE}
wl_request(endpoint = "stations")
```
It takes also care of creating the correct api-signature via HMAC, which us handled by `wl_params()`.
## Unit tests
To run the full test suite set valid environmental variables
`WL_API_KEY` and `WL_API_SECRET` and run `devtools::test()`.
Note, that for some tests more than one stations is needed.
Currently, code coverage is very high. wl_nodes is not well covered by the unit tests.