Package '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, ...)

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()

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)

---

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,
  ...
)

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:

1. cites_listings: lists CITES annex listings EU suspensions,

2. cites_quotas: lists CITES quotas,

3. 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)

---

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,
  ...
)

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:

1. distributions: lists distributions for a given taxon concept,

2. 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)

---

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,
  ...
)

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:

1. eu_listings: lists EU annex listings EU suspensions,

2. 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)

---

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,
  ...
)

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)

---

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,
  ...
)

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:

1. all_id: general information for all entries, including non-active taxon concepts,

2. general: includes general information for active taxon concepts,

3. higher_taxa: includes taxonomy information,

4. accepted_names: list of accepted names (only for synonyms),

5. common_names: list of common names (only for accepted names),

6. synonyms: list of synonyms (only for accepted names),

7. 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)

---