Merge pull request #74 from gbabineau/ebirdhistorical

Add new function ebirdhistorical

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: rebird
-Version: 1.0.2
+Version: 1.0.3
 Title: R Client for the eBird Database of Bird Observations
 Description: A programmatic client for the eBird database, including functions
     for searching for bird observations by geographic location (latitude,
@@ -29,7 +29,7 @@ Suggests:
     knitr,
     testthat,
     covr
-RoxygenNote: 6.1.0
+RoxygenNote: 6.1.1
 X-schema.org-applicationCategory: Data Access
 X-schema.org-keywords: birds, birding, ebird, database, data, biology, observations, sightings, ornithology
 X-schema.org-isPartOf: https://ropensci.org

NAMESPACE

@@ -2,6 +2,7 @@
 
 export(ebirdfreq)
 export(ebirdgeo)
+export(ebirdhistorical)
 export(ebirdhotspot)
 export(ebirdloc)
 export(ebirdnotable)

NEWS.md

@@ -2,6 +2,7 @@ rebird 1.1.0
 ===================
 
 * Updated `ebirdregioninfo()` to also provide information of hotspots (thanks @gbabineau, #72).
+* Added `ebirdhistorical()` which provides historic observations on a date at a region or hotspot (thanks @gbabineau, #74).
 
 rebird 1.0.0
 ===================

R/ebirdhistorical.R

@@ -0,0 +1,93 @@
+#' Historic observations on a date at a region or hotspot
+#' 
+#' Returns sighting information reported in a given region or hotspot
+#' 
+#' @param loc (required) Region code or locID (if a hotspot). Region code can
+#'    be country code (e.g. "US"), subnational1 code (states/provinces, e.g. "US-NV"), or
+#'    subnational2 code (counties, e.g. "US-VA-003").
+#' @param date (required) Date of historic observation date formatted according 
+#'    to ISO 8601 (e.g. 'YYYY-MM-DD', or 'YYYY-MM-DD hh:mm'). Hours and minutes 
+#'    are excluded.
+#' @param sortKey [mrec|create] Whether to order results by latest 
+#'    observation date or by latest creation date. The default is by observation date.
+#' @param categories [domestic|form|hybrid|intergrade|issf|slash|species|spuh] 
+#'    This is useful for limiting results to certain taxonomic categories. The 
+#'    default is all. Multiple categories may be comma-separated.
+#' @param max Maximum number of result rows to return in this request.
+#'    (A number between 1 and 10000. The default is 10000)
+#' @param  fieldSet [simple|full] This is set to restrict results to either all 
+#'     or a subset of sighting fields. The default is simple.
+#' @param provisional Should flagged records that have not been reviewed
+#'    be included? 
+#' @param limitToHotspots Should results be limited to sightings at birding hotspots?
+#'    The default is FALSE.
+#' @param sleep Time (in seconds) before function sends API call. The defaults is
+#'    zero. Set this to a higher number if you are using this function in a loop with
+#'    many API calls.
+#' @param key eBird API key. You can obtain one from https://ebird.org/api/keygen.
+#'    We strongly recommend storing it in your \code{.Renviron} file as an 
+#'    environment variable called \code{EBIRD_KEY}.
+#' @param ... Curl options passed on to \code{\link[httr]{GET}}.
+#' @return A data.frame containing the collected information:
+#' @return "speciesCode": species codes
+#' @return "comName": species common names
+#' @return "sciName" species' scientific names
+#' @return "locID": unique identifier for the locations
+#' @return "locName": location name
+#' @return "obsDt": observation date formatted according to ISO 8601 
+#'    (e.g. 'YYYY-MM-DD', or 'YYYY-MM-DD hh:mm'). Hours and minutes are excluded 
+#'    if the observer did not report an observation time
+#' @return "obsValid": TRUE if observation has been deemed valid by either the 
+#'    automatic filters or a regional viewer, FALSE otherwise
+#' @return "obsReviewed": TRUE if observation has been reviewed, FALSE otherwise
+#' @return "locationPrivate": TRUE if location is not a birding hotspot
+#' @return "subnational2Code": county code (returned if simple=FALSE)
+#' @return "subnational2Name": county name (returned if simple=FALSE)
+#' @return "subnational1Code": state/province ISO code (returned if simple=FALSE)
+#' @return "subnational1Name": state/province name (returned if simple=FALSE)
+#' @return "countryCode": country ISO code (returned if simple=FALSE)
+#' @return "countryName": country name (returned if simple=FALSE)
+#' @return "userDisplayName": first and last name of the observer (returned if simple=FALSE) 
+#' @return "subID": submission ID (returned if simple=FALSE)
+#' @return "obsID": observation ID (returned if simple=FALSE)
+#' @return "checklistID": checklist ID (returned if simple=FALSE)
+#' @return "presenceNoted": 'true' if user marked presence but did not count the
+#'   number of birds. 'false' otherwise (returned if simple=FALSE)
+#' @return "hasComments": 'true' if comments are included  (returned if simple=FALSE)
+#' @return "hasRichMedia": 'true' if rich media (e.g. photos/sounds) are included (returned if simple=FALSE)
+#' @return "firstName": observer's first name (returned if simple=FALSE)
+#' @return "lastName": observer's last name (returned if simple=FALSE)
+#' @export
+#' @examples \dontrun{
+#' ebirdhistorical(loc = 'US-VA-003', date='2019-02-14',max=10)
+#' ebirdhistorical(loc = 'L196159', date='2019-02-14', fieldSet='full')
+#' }
+#' @author Guy Babineau \email{guy.babineau@@gmail.com}
+#' @references \url{http://ebird.org/}
+ebirdhistorical <-  function(loc, date, sortKey = 'mrec', categories = 'all', 
+  max = 10000, fieldSet='simple', provisional = FALSE, limitToHotspots = FALSE, sleep=0, 
+  key=NULL, ...)
+{
+
+
+  historicDate=as.Date(date)
+  if (Sys.Date()<historicDate) {
+    stop(paste0("date must be in the past"))
+  }
+  if (historicDate<'1800-01-01'){
+    stop(paste0("date must be on or after 1800-01-01"))
+  }
+  Sys.sleep(sleep)
+
+  url <- paste0(ebase(), 'data/obs/', loc, '/historic/',format(historicDate, "%Y"),'/',
+                format(historicDate, "%m"),'/',format(historicDate, "%d") )
+
+  args <- list(rank=sortKey,maxResults=max,detail=fieldSet,
+               includeProvisional=provisional)
+  if(categories != 'all') {
+    args$cat=categories
+  }
+  if (limitToHotspots) args$hotspot <- 'true'
+
+  ebird_GET(url, args, key = key, ...)
+}

README.Rmd

@@ -134,6 +134,22 @@ or a region
 ebirdnotable(locID = 'US-NY-109')
 ```
 
+## Historic Observations
+
+Search for historic observations on a date at a region 
+
+```{r ebirdhistorical1}
+ebirdhistorical(loc = 'US-VA-003', date = '2019-02-14',max = 10)
+
+```
+
+or a hotspot
+
+```{r ebirdhistorical2}
+ebirdhistorical(loc = 'L196159', date = '2019-02-14', fieldSet = 'full')
+
+```
+
 ## Information on a given region or hotspot
 
 Obtain detailed information on any valid eBird region
@@ -170,7 +186,7 @@ The 2.0 APIs have considerably been expanded from the previous version, and `reb
 - [x] Recent nearby observations of a species: `ebirdgeo()`
 - [x] Nearest observations of a species: `nearestobs()`
 - [x] Recent nearby notable observations: `ebirdnotable()`
-- [ ] Historic observations on a date
+- [x] Historic observations on a date: `ebirdhistorical()`
 
 ### product
 - [ ]   Top 100