Package 'rcites' reference manual

Title:	R Interface to the Species+ Database
Description:	A programmatic interface to the Species+ <https://speciesplus.net/> database via the Species+/CITES Checklist API <https://api.speciesplus.net/>.
Authors:	Kevin Cazelles [aut, cre] , Jonas Geschke [aut] , Ignasi Bartomeus [aut] , Jonathan Goldenberg [ctb], Marie-Bé Leduc [ctb], Yasmine Verzelen [ctb], Noam Ross [rev], Margaret Siple [rev]
Maintainer:	Kevin Cazelles <[email protected]>
License:	MIT + file LICENSE
Version:	1.3.0.9000
Built:	2024-10-28 06:06:52 UTC
Source:	https://github.com/ropensci/rcites

Print methods for objects of class `⁠spp_raw*⁠`.

Description

Print the outputs of a Species+ API call.

Usage

## S3 method for class 'spp_raw'
print(x, ...)

## S3 method for class 'spp_raw_multi'
print(x, ...)

## S3 method for class 'spp_cites_leg'
print(x, ...)

## S3 method for class 'spp_cites_leg_multi'
print(x, ...)

## S3 method for class 'spp_distr'
print(x, ...)

## S3 method for class 'spp_distr_multi'
print(x, ...)

## S3 method for class 'spp_eu_leg'
print(x, ...)

## S3 method for class 'spp_eu_leg_multi'
print(x, ...)

## S3 method for class 'spp_refs'
print(x, ...)

## S3 method for class 'spp_refs_multi'
print(x, ...)

## S3 method for class 'spp_taxon'
print(x, ...)
## S3 method for class 'spp_raw'
print(x, ...)

## S3 method for class 'spp_raw_multi'
print(x, ...)

## S3 method for class 'spp_cites_leg'
print(x, ...)

## S3 method for class 'spp_cites_leg_multi'
print(x, ...)

## S3 method for class 'spp_distr'
print(x, ...)

## S3 method for class 'spp_distr_multi'
print(x, ...)

## S3 method for class 'spp_eu_leg'
print(x, ...)

## S3 method for class 'spp_eu_leg_multi'
print(x, ...)

## S3 method for class 'spp_refs'
print(x, ...)

## S3 method for class 'spp_refs_multi'
print(x, ...)

## S3 method for class 'spp_taxon'
print(x, ...)

Arguments

`x`	an object of class `⁠spp_raw*⁠`.
`...`	ignored.

Value

The JSON result.

Login helper function

Description

Set and forget the authentification token for the current session.

Usage

set_token(token = NULL)

forget_token()
set_token(token = NULL)

forget_token()

Arguments

token

a character string (with quotes) containing your token. If NULL, then the token can be passed without quotes (not as a character string) after a prompt.

Functions

set_token(): set the environment variable SPECIESPLUS_TOKEN.
forget_token(): forget the environment variable SPECIESPLUS_TOKEN.

References

https://api.speciesplus.net/documentation

Examples

## Not run: 
# NB: the token below is not working and should not be used
set_token("8QW6Qgh57sBG2k0gtt")

## End(Not run)
## Not run: 
# NB: the token below is not working and should not be used
set_token("8QW6Qgh57sBG2k0gtt")

## End(Not run)

Get current CITES appendix listings and reservations

Description

Retrieve current CITES appendix listings and reservations, CITES quotas, and CITES suspensions for a given taxon concept.

Usage

spp_cites_legislation(
  taxon_id,
  scope = "current",
  language = "en",
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)
spp_cites_legislation(
  taxon_id,
  scope = "current",
  language = "en",
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)

Arguments

`taxon_id`	a vector of character strings containing species' taxon concept identifiers (see `spp_taxonconcept()`).
`scope`	vector of character strings indicating the time scope of legislation, values are taken among `current`, `historic` and `all`. Default is `current`.
`language`	vector of character strings indicating the language for the text of legislation notes, values are taken among `en` (English), `fr` (French) and `es` (Spanish). Default is `en`.
`raw`	a logical. Should raw data be returned?
`token`	a character string containing the authentification token, see https://api.speciesplus.net/documentation. Default is set to `NULL` and requires the environment variable `SPECIESPLUS_TOKEN` to be set directly in `Renviron`. Alternatively, `set_token()` can be used to set `SPECIESPLUS_TOKEN` for the current session.
`verbose`	a logical. Should extra information be reported on progress?
`pause`	a duration (in second) to suspend execution for (see `Sys.sleep()`). This was added cause the web API returns a 404 error too many requests in a short time interval.
`...`	Further named parameters, see `httr::GET()`.

Value

If raw is set to TRUE then an object of class spp_raw (or spp_raw_multi if length(taxon_id) > 1) is returned which is essentially a list of lists (see option as = 'parsed' in httr::content()). Otherwise, an object of class spp_cites_leg (or spp_cites_leg_multi if length(taxon_id)>1) is returned which is a list of three data frames:

cites_listings: lists CITES annex listings EU suspensions,
cites_quotas: lists CITES quotas,
cites_suspensions: lists CITES suspensions.

References

https://api.speciesplus.net/documentation/v1/cites_legislation/index.html

Examples

## Not run: 
# this calls will only work if a token is set and valid
res1 <- spp_cites_legislation(taxon_id = 4521)
res2 <- spp_cites_legislation(taxon_id = c('4521', '3210', '10255'))
res3 <- spp_cites_legislation(taxon_id = 4521, scope = 'all',
verbose = FALSE, config=httr::verbose())
res4 <- spp_cites_legislation(taxon_id = 4521, language = 'fr')

## End(Not run)
## Not run: 
# this calls will only work if a token is set and valid
res1 <- spp_cites_legislation(taxon_id = 4521)
res2 <- spp_cites_legislation(taxon_id = c('4521', '3210', '10255'))
res3 <- spp_cites_legislation(taxon_id = 4521, scope = 'all',
verbose = FALSE, config=httr::verbose())
res4 <- spp_cites_legislation(taxon_id = 4521, language = 'fr')

## End(Not run)

Get distributions data available for a given taxon concept

Description

Retrieve distributions data available for a given taxon concept for which the the taxon identifier is known.

Usage

spp_distributions(
  taxon_id,
  language = "en",
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)
spp_distributions(
  taxon_id,
  language = "en",
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)

Arguments

`taxon_id`	a vector of character strings containing species' taxon concept identifiers (see `spp_taxonconcept()`).
`language`	vector of character strings indicating the language for the names of distributions, values are taken among `en` (English), `fr` (French) and `es` (Spanish). Default is `en`.
`raw`	a logical. Should raw data be returned?
`token`	a character string containing the authentification token, see https://api.speciesplus.net/documentation. Default is set to `NULL` and requires the environment variable `SPECIESPLUS_TOKEN` to be set directly in `Renviron`. Alternatively, `set_token()` can be used to set `SPECIESPLUS_TOKEN` for the current session.
`verbose`	a logical. Should extra information be reported on progress?
`pause`	a duration (in second) to suspend execution for (see `Sys.sleep()`). This was added cause the web API returns a 404 error too many requests in a short time interval.
`...`	Further named parameters, see `httr::GET()`.

Value

If raw is set to TRUE then an object of class spp_raw (or spp_raw_multi if length(taxon_id)>1) is returned which is essentially a list of lists (see option as = 'parsed' in httr::content()). Otherwise, an object of class spp_distr (or spp_distr_multi if length(taxon_id) > 1) is returned which is a list of two data frames:

distributions: lists distributions for a given taxon concept,
references: lists the corresponding references. In case taxon_id includes several elements

References

https://api.speciesplus.net/documentation/v1/distributions/index.html

Examples

## Not run: 
 # this calls will only work if a token is set and valid
 res1 <- spp_distributions(taxon_id = '4521')
 res2 <- spp_distributions(taxon_id = c('4521', '3210', '10255'))
 res3 <- spp_distributions(taxon_id = '4521', raw = TRUE)
 res4 <- spp_distributions(taxon_id = '4521', language = 'fr',
 verbose = FALSE, config = httr::progress())

## End(Not run)
## Not run: 
 # this calls will only work if a token is set and valid
 res1 <- spp_distributions(taxon_id = '4521')
 res2 <- spp_distributions(taxon_id = c('4521', '3210', '10255'))
 res3 <- spp_distributions(taxon_id = '4521', raw = TRUE)
 res4 <- spp_distributions(taxon_id = '4521', language = 'fr',
 verbose = FALSE, config = httr::progress())

## End(Not run)

Get current EU annex listings, SRG opinions, and EU suspensions

Description

Retrieve current EU annex listings, SRG opinions, and EU suspensions for a given taxon concept (identifier must be known).

Usage

spp_eu_legislation(
  taxon_id,
  scope = "current",
  language = "en",
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)
spp_eu_legislation(
  taxon_id,
  scope = "current",
  language = "en",
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)

Arguments

`taxon_id`	a vector of character strings containing species' taxon concept identifiers (see `spp_taxonconcept()`).
`scope`	vector of character strings indicating the time scope of legislation, values are taken among `current`, `historic` and `all`. Default is set to `current`.
`language`	vector of character strings indicating the language for the text of legislation notes, values are taken among `en` (English), `fr` (French) and `es` (Spanish). Default is `en`.
`raw`	a logical. Should raw data be returned?
`token`	a character string containing the authentification token, see https://api.speciesplus.net/documentation. Default is set to `NULL` and requires the environment variable `SPECIESPLUS_TOKEN` to be set directly in `Renviron`. Alternatively, `set_token()` can be used to set `SPECIESPLUS_TOKEN` for the current session.
`verbose`	a logical. Should extra information be reported on progress?
`pause`	a duration (in second) to suspend execution for (see `Sys.sleep()`). This was added cause the web API returns a 404 error too many requests in a short time interval.
`...`	Further named parameters, see `httr::GET()`.

Value

If raw is set to TRUE then an object of class spp_raw (or spp_raw_multi if length(taxon_id)>1) is returned which is essentially a list of lists (see option as = 'parsed' in httr::content()). Otherwise, an object of class spp_eu_leg (or spp_eu_leg_multi if length(taxon_id)>1) is returned which is a list of two data frames:

eu_listings: lists EU annex listings EU suspensions,
eu_decisions: lists EU decisions

References

https://api.speciesplus.net/documentation/v1/eu_legislation/index.html

Examples

## Not run: 
# this calls will only work if a token is set and valid
res1 <- spp_eu_legislation(taxon_id = '4521')
res2 <- spp_eu_legislation(taxon_id = c('4521', '3210', '10255'))
res3 <- spp_eu_legislation(taxon_id = '4521', scope = 'historic')
res4 <- spp_eu_legislation(taxon_id = '4521', scope = 'all', language='fr',
 verbose = FALSE, config=httr::verbose())

## End(Not run)
## Not run: 
# this calls will only work if a token is set and valid
res1 <- spp_eu_legislation(taxon_id = '4521')
res2 <- spp_eu_legislation(taxon_id = c('4521', '3210', '10255'))
res3 <- spp_eu_legislation(taxon_id = '4521', scope = 'historic')
res4 <- spp_eu_legislation(taxon_id = '4521', scope = 'all', language='fr',
 verbose = FALSE, config=httr::verbose())

## End(Not run)

Get references for a given taxon concept

Description

Retrieve available references for a given taxon concept.

Usage

spp_references(
  taxon_id,
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)
spp_references(
  taxon_id,
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)

Arguments

`taxon_id`	a vector of character strings containing species' taxon concept identifiers (see `spp_taxonconcept()`).
`raw`	a logical. Should raw data be returned?
`token`	a character string containing the authentification token, see https://api.speciesplus.net/documentation. Default is set to `NULL` and requires the environment variable `SPECIESPLUS_TOKEN` to be set directly in `Renviron`. Alternatively, `set_token()` can be used to set `SPECIESPLUS_TOKEN` for the current session.
`verbose`	a logical. Should extra information be reported on progress?
`pause`	a duration (in second) to suspend execution for (see `Sys.sleep()`). This was added cause the web API returns a 404 error too many requests in a short time interval.
`...`	Further named parameters, see `httr::GET()`.

Value

If raw is set to TRUE then an object of class spp_raw (or spp_raw_multi if length(taxon_id) > 1) is returned which is essentially a list of lists (see option as = 'parsed' in httr::content()). Otherwise, an object of class spp_refs (or spp_refs_multi if length(taxon_id) > 1) is returned which is a list of one data frame:

references that includes the identifier of the reference and the corresponding citation.

References

https://api.speciesplus.net/documentation/v1/references/index.html

Examples

## Not run: 
# this calls will only work if a token is set and valid
res1 <- spp_references(taxon_id = '4521')
res2 <- spp_references(c('4521', '3210', '10255'))
res3 <- spp_references(taxon_id = '4521', raw = TRUE, verbose = FALSE,
 config = httr::progress())

## End(Not run)
## Not run: 
# this calls will only work if a token is set and valid
res1 <- spp_references(taxon_id = '4521')
res2 <- spp_references(c('4521', '3210', '10255'))
res3 <- spp_references(taxon_id = '4521', raw = TRUE, verbose = FALSE,
 config = httr::progress())

## End(Not run)

Get taxon concepts for a search term

Description

Retrieve the taxon concept of a specific taxon (scientific name).

Usage

spp_taxonconcept(
  query_taxon,
  taxonomy = "CITES",
  with_descendants = FALSE,
  language = NULL,
  updated_since = NULL,
  per_page = 500,
  pages = NULL,
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)
spp_taxonconcept(
  query_taxon,
  taxonomy = "CITES",
  with_descendants = FALSE,
  language = NULL,
  updated_since = NULL,
  per_page = 500,
  pages = NULL,
  raw = FALSE,
  token = NULL,
  verbose = TRUE,
  pause = 1,
  ...
)

Arguments

`query_taxon`	a character string containing the query (e.g. species). Scientific taxa only (max 255 characters).
`taxonomy`	filter taxon concepts by taxonomy, accepts either 'CITES' or 'CMS' as its value. Default sets to 'CITES'.
`with_descendants`	a logical. Should the search by name be broadened to include higher taxa?
`language`	filter languages returned for common names. Value should be a vector of character strings including one or more country codes (two-letters country code ISO 3166-1 alpha-2). Default is set to `NULL`, showing all available languages.
`updated_since`	a timestamp. Only entries updated after (and including) this timestamp will be pulled.
`per_page`	an integer that indicates how many objects are returned per page for paginated responses. Default set to 500 which is the maximum.
`pages`	a vector of integer that contains page numbers. Default is set to `NULL`, i.e. all pages are accessed.
`raw`	a logical. Should raw data be returned?
`token`	a character string containing the authentification token, see https://api.speciesplus.net/documentation. Default is set to `NULL` and requires the environment variable `SPECIESPLUS_TOKEN` to be set directly in `Renviron`. Alternatively, `set_token()` can be used to set `SPECIESPLUS_TOKEN` for the current session.
`verbose`	a logical. Should extra information be reported on progress?
`pause`	a duration (in second) to suspend execution for (see `Sys.sleep()`). This was added cause the web API returns a 404 error too many requests in a short time interval.
`...`	Further named parameters, see `httr::GET()`.

Value

If raw = TRUE, then a object of class spp_raw is returned, which is a list of lists. If raw = FALSE, then an object of class spp_taxon is returned, it is a collection of seven data frames:

all_id: general information for all entries, including non-active taxon concepts,
general: includes general information for active taxon concepts,
higher_taxa: includes taxonomy information,
accepted_names: list of accepted names (only for synonyms),
common_names: list of common names (only for accepted names),
synonyms: list of synonyms (only for accepted names),
cites_listing: list of current CITES listings with annotations (missing if taxonomy == 'CMS').

References

https://api.speciesplus.net/documentation/v1/taxon_concepts/index.html

Examples

## Not run: 
# this calls will only work if a token is set and valid
res1 <- spp_taxonconcept(query_taxon = 'Loxodonta africana')
res2 <- spp_taxonconcept(query_taxon = 'Amazilia versicolor', raw = TRUE)
res3 <- spp_taxonconcept(query_taxon = '', taxonomy = 'CMS', pages = c(1, 3),
 language = 'EN', config = httr::progress())
res4 <- spp_taxonconcept(query_taxon = '', per_page = 20, pages = 44)

## End(Not run)
## Not run: 
# this calls will only work if a token is set and valid
res1 <- spp_taxonconcept(query_taxon = 'Loxodonta africana')
res2 <- spp_taxonconcept(query_taxon = 'Amazilia versicolor', raw = TRUE)
res3 <- spp_taxonconcept(query_taxon = '', taxonomy = 'CMS', pages = c(1, 3),
 language = 'EN', config = httr::progress())
res4 <- spp_taxonconcept(query_taxon = '', per_page = 20, pages = 44)

## End(Not run)

Package 'rcites'

Help Index

Print methods for objects of class ⁠spp_raw*⁠.

Description

Usage

Arguments

Value

Login helper function

Description

Usage

Arguments

Functions

References

Examples

Get current CITES appendix listings and reservations

Description

Usage

Arguments

Value

References

Examples

Get distributions data available for a given taxon concept

Description

Usage

Arguments

Value

References

Examples

Get current EU annex listings, SRG opinions, and EU suspensions

Description

Usage

Arguments

Value

References

Examples

Get references for a given taxon concept

Description

Usage

Arguments

Value

References

Examples

Get taxon concepts for a search term

Description

Usage

Arguments

Value

References

Examples

Print methods for objects of class `⁠spp_raw*⁠`.