add more examples, fix missing parameter check

R/box.R

@@ -40,8 +40,31 @@
 #'   # get all boxes with grouptag 'ifgi' that are placed outdoors
 #'   b = osem_boxes(grouptag = 'ifgi', exposure = 'outdoor')
 #'
+#'   # get all boxes with model 'luftdaten_sds011_dht22'
+#'   b = osem_boxes(grouptag = 'ifgi')
+#'
 #'   # get all boxes that have measured PM2.5 in the last 4 hours
 #'   b = osem_boxes(date = Sys.time(), phenomenon = 'PM2.5')
+#'
+#'   # get all boxes that have measured PM2.5 between Jan & Feb 2018
+#'   library(lubridate)
+#'   b = osem_boxes(
+#'     from = date('2018-01-01'),
+#'     to = date('2018-02-01'),
+#'     phenomenon = 'PM2.5'
+#'   )
+#'
+#'   # get all boxes from a custom (selfhosted) openSenseMap API
+#'   b = osem_box(endpoint = 'http://api.my-custom-osem.com')
+#'
+#'   # get all boxes and cache the response, in order to provide
+#'   # reproducible results in the future. Also useful for development
+#'   # to avoid repeated loading times!
+#'   b = osem_boxes(cache = getwd())
+#'   b = osem_boxes(cache = getwd())
+#'
+#'   # get *all* boxes available on the API, without showing download progress
+#'   b = osem_boxes(progress = FALSE)
 #' }
 osem_boxes = function (exposure = NA, model = NA, grouptag = NA,
                       date = NA, from = NA, to = NA, phenomenon = NA,
@@ -95,9 +118,17 @@ osem_boxes = function (exposure = NA, model = NA, grouptag = NA,
 #' @seealso \code{\link{osem_clear_cache}}
 #' @export
 #' @examples
+#' \donttest{
 #'   # get a specific box by ID
 #'   b = osem_box('57000b8745fd40c8196ad04c')
 #'
+#'   # get a specific box by ID from a custom (selfhosted) openSenseMap API
+#'   b = osem_box('51030b8725fd30c2196277da', 'http://api.my-custom-osem.com')
+#'
+#'   # get a specific box by ID and cache the response, in order to provide
+#'   # reproducible results in the future.
+#'   b = osem_box('51030b8725fd30c2196277da', cache = tempdir())
+#' }
 osem_box = function (boxId, endpoint = osem_endpoint(), cache = NA) {
   get_box_(boxId, endpoint = endpoint, cache = cache)
 }

R/measurement.R

@@ -40,8 +40,27 @@ osem_measurements = function (x, ...) UseMethod('osem_measurements')
 #' @export
 #' @examples
 #' \donttest{
-#'   # get measurements from all boxes
-#'   m1 = osem_measurements('Windrichtung')
+#'   # get measurements from all boxes on the phenomenon 'PM10' from the last 48h
+#'   m = osem_measurements('PM10')
+#'
+#'   # get measurements from all mobile boxes on the phenomenon 'PM10' from the last 48h
+#'   m = osem_measurements('PM10', exposure = 'mobile')
+#'
+#'   # get measurements and cache them locally in the working directory.
+#'   # subsequent identical requests will load from the cache instead, ensuring
+#'   # reproducibility and saving time and bandwidth!
+#'   m = osem_measurements('PM10', exposure = 'mobile', cache = getwd())
+#'   m = osem_measurements('PM10', exposure = 'mobile', cache = getwd())
+#'
+#'   # get measurements returning a custom selection of columns
+#'   m = osem_measurements('PM10', exposure = 'mobile', columns = c(
+#'     'value',
+#'     'boxId',
+#'     'sensorType',
+#'     'lat',
+#'     'lon',
+#'     'height'
+#'   ))
 #' }
 osem_measurements.default = function (x, ...) {
   bbox = structure(c(-180, -90, 180, 90), class = 'bbox')
@@ -54,13 +73,26 @@ osem_measurements.default = function (x, ...) {
 #' @export
 #' @examples
 #' \donttest{
-#'   # get measurements from sensors within a bounding box
+#'   # get measurements from sensors within a custom WGS84 bounding box
 #'   bbox = structure(c(7, 51, 8, 52), class = 'bbox')
-#'   m2 = osem_measurements(bbox, 'Temperatur')
+#'   m = osem_measurements(bbox, 'Temperatur')
 #'
-#'   points = sf::st_multipoint(matrix(c(7.5, 7.8, 51.7, 52), 2, 2))
-#'   bbox2 = sf::st_bbox(points)
-#'   m3 = osem_measurements(bbox2, 'Temperatur', exposure = 'outdoor')
+#'   # construct a bounding box 12km around berlin using the sf package,
+#'   # and get measurements from stations within that box
+#'   library(sf)
+#'   bbox2 = st_point(c(13.4034, 52.5120)) %>%
+#'     st_sfc(crs = 4326) %>%
+#'     st_transform(3857) %>% # allow setting a buffer in meters
+#'     st_buffer(set_units(12, km)) %>%
+#'     st_transform(4326) %>% # the opensensemap expects WGS 84
+#'     st_bbox()
+#'   m = osem_measurements(bbox2, 'Temperatur', exposure = 'outdoor')
+#'
+#'   # construct a bounding box from two points,
+#'   # and get measurements from stations within that box
+#'   points = st_multipoint(matrix(c(7.5, 7.8, 51.7, 52), 2, 2))
+#'   bbox3 = st_bbox(points)
+#'   m = osem_measurements(bbox2, 'Temperatur', exposure = 'outdoor')
 #' }
 osem_measurements.bbox = function (x, phenomenon, exposure = NA,
                                    from = NA, to = NA, columns = NA,
@@ -88,6 +120,17 @@ osem_measurements.bbox = function (x, phenomenon, exposure = NA,
 #'   # ...or a single box
 #'   b = osem_box('57000b8745fd40c8196ad04c')
 #'   m5 = osem_measurements(b, phenomenon = 'Temperatur')
+#'
+#'   # get measurements from a single box on the from the last 40 days.
+#'   # requests are paged for long time frames, so the APIs limitation
+#'   # does not apply!
+#'   library(lubridate)
+#'   m1 = osem_measurements(
+#'     b,
+#'     'Temperatur',
+#'     to = now(),
+#'     from = now() - days(40)
+#'   )
 #' }
 osem_measurements.sensebox = function (x, phenomenon, exposure = NA,
                                        from = NA, to = NA, columns = NA,
@@ -112,7 +155,7 @@ osem_measurements.sensebox = function (x, phenomenon, exposure = NA,
 #' @return A named \code{list} of parsed parameters.
 #' @noRd
 parse_get_measurements_params = function (params) {
-  if (is.null(params$phenomenon) | is.na(params$phenomenon))
+  if (is.symbol(params$phenomenon) || is.null(params$phenomenon) || is.na(params$phenomenon))
     stop('Parameter "phenomenon" is required')
 
   if (