Add function to retrieve taxonomy version and tests to verify version

.github/workflows/R-CMD-check.yaml

@@ -5,6 +5,9 @@ on:
     branches: [main, master]
   pull_request:
     branches: [main, master]
+  schedule:
+    - cron:
+        '0 8 1,15 * *' # At 08:00AM on 1st and 15th of month
 
 name: R-CMD-check
 
@@ -29,7 +32,7 @@ jobs:
       R_KEEP_PKG_SOURCE: yes
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: r-lib/actions/setup-pandoc@v2
 

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: rebird
-Version: 1.3.9005
+Version: 1.3.9006
 Title: R Client for the eBird Database of Bird Observations
 Description: A programmatic client for the eBird database 
     (<https://ebird.org/home>), including functions for searching for bird 
@@ -36,7 +36,7 @@ Suggests:
     covr,
     vcr (>= 0.6.0),
     withr
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 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

@@ -15,6 +15,7 @@ export(ebirdregioninfo)
 export(ebirdregionspecies)
 export(ebirdsubregionlist)
 export(ebirdtaxonomy)
+export(ebirdtaxonomyversion)
 export(getlatlng)
 export(nearestobs)
 export(species_code)

NEWS.md

@@ -1,5 +1,7 @@
-# rebird 1.3.9005
+# rebird 1.3.9006
 
+- Added `ebirdtaxonomyversion()` which retrieves data on available taxonomy versions.
+The version is added as an attribute to `rebird::tax` (#131).
 - Added `ebirdchecklist()`, which lets you view individual checklists (thanks @RichardLitt and @Rafnuss, #108).
 - Made `ebirdregioncheck()`, `ebirdhotspot()`, `ebirdloc()` defunct. 
 - API tests now use `vcr`, which saves "cassettes" of the tests which can be played

R/ebirdtaxonomy.R

@@ -61,11 +61,13 @@ ebirdtaxonomy <- function(cat=NULL, locale=NULL, species = NULL, key = NULL, ...
   species <- if(!is.null(species)) species <- paste0(species, collapse = ",")
   args <- list(fmt='json', cat=cat, locale=locale, species=species)
 
-  # Allow not using a key for just this function, it's the only endpoint 
-  # that allows it
+  # Allow not using a key for this function
   if (is.null(key) && !nzchar(Sys.getenv("EBIRD_KEY"))) {
     key <- ""
   }
-
-  ebird_GET(paste0(ebase(), 'ref/taxonomy/ebird'), args, key = key, ...)
+
+  tax <- ebird_GET(paste0(ebase(), 'ref/taxonomy/ebird'), args, key = key, ...)
+  latest <-  subset(ebirdtaxonomyversion(), latest == TRUE)$authorityVer
+  attr(tax, "version") <- latest
+  tax
 }

R/ebirdtaxonomyversion.R

@@ -0,0 +1,31 @@
+#' eBird Taxonomy Version
+#'
+#' Returns a data.frame of available version numbers of the eBird taxonomy
+#'
+#' @param key optional 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} to avoid having to constantly
+#'    supply the key, and to avoid accidentally sharing it publicly.
+#' @param ... Curl options passed on to \code{\link[httr]{GET}}
+#'
+#' @return data.frame containing the collected information:
+#' @return "authorityVer": Character of version.
+#' @return "latest": Boolean indicating whether `authorityVer` is the latest taxonomy version
+#'
+#' @export
+#'
+#' @examples \dontrun{
+#' ebirdtaxonomyversion()
+#' }
+#' @author Jordan Bradford \email{[email protected]}
+#' @references \url{http://ebird.org/}
+ebirdtaxonomyversion <- function(key = NULL, ...) {
+  args <- list(fmt = 'json')
+
+  # Allow not using a key for this function
+  if (is.null(key) && !nzchar(Sys.getenv("EBIRD_KEY"))) {
+    key <- ""
+  }
+
+  ebird_GET(paste0(ebase(), 'ref/taxonomy/versions'), args, key = key, ...)
+}

R/zzz.R

@@ -87,4 +87,3 @@ ebird_GET <- function(url, args, key = NULL, ...){
     }
   }
 }
-

README.Rmd

@@ -270,12 +270,12 @@ The 2.0 APIs have considerably been expanded from the previous version, and `reb
 ### ref/taxonomy
  - [x]     eBird Taxonomy: `ebirdtaxonomy()`
  - [ ]     Taxonomic Forms
- - [ ]     Taxonomy Versions
+ - [x]     Taxonomy Versions: `ebirdtaxonomyversion()`
  - [ ]     Taxonomic Groups
 
 ### ref/region
  - [x]     Region Info: `ebirdregioninfo()`
- - [x]     Sub Region List `ebirdsubregionlist()`
+ - [x]     Sub Region List: `ebirdsubregionlist()`
 
 
 ## Meta

README.md

@@ -558,13 +558,13 @@ covered by this package, feel free to submit a pull request!
 
 -   [x] eBird Taxonomy: `ebirdtaxonomy()`
 -   [ ] Taxonomic Forms
--   [ ] Taxonomy Versions
+-   [x] Taxonomy Versions: `ebirdtaxonomyversion()`
 -   [ ] Taxonomic Groups
 
 ### ref/region
 
 -   [x] Region Info: `ebirdregioninfo()`
--   [x] Sub Region List `ebirdsubregionlist()`
+-   [x] Sub Region List: `ebirdsubregionlist()`
 
 ## Meta
 

data-raw/tax.R

@@ -1,7 +1,7 @@
 # eBird taxonomy to look up species codes
 # 
-# This creates the internal taxonomy data frame used by rebird, which
-# is stored ind 'R/sysdata.rda'. We update the package in CRAN when
+# This creates the taxonomy data frame used by rebird, which
+# is stored in 'data/tax.rda'. We update the package in CRAN when
 # the eBird taxonomy update is completed, but in the event you need
 # to update the taxonomy yourself you can do so by running the code below.