To set up a connection to the Species+/CITES Checklist API, an authentication token is required. Each user should obtain his or her own personal token to run the code below (see https://api.speciesplus.net/documentation for more details). To obtain a token, sign up on the Species+ API website.
Now, we assume that you already have a token. For illustrative purposes, we will use the generic token value
8QW6Qgh57sBG2k0gtt from the API documentation.
A token is mandatory and needs to be passed to the header of all URL requests. They are three different ways to set the token in
set an environment variable
SPECIESPLUS_TOKEN in your
.Renviron file (preferred for frequent users);
set_token() to set up the token as a character string (with quotes). If not entered in the function, the token can be passed without quotes (not as a character string) after the prompt. This way, the token
SPECIESPLUS_TOKEN is interactively set up only for the current R session, meaning a login will be required for the future R sessions (preferred);
tokenargument inside the functions, i.e. the token is passed manually to each function call.
Note that if you set a wrong token and you wish to set it again interactively, you must first forget the previous token with
In order to efficiently query information from the CITES database, you first need to retrieve the unique taxon identifier
taxon_id from the Species+ taxon concept. To do so, you should first call
spp_taxonconcept() and provide the scientific name of the taxon you are looking for. Let us start by requesting the identifier of the African bush elephant, i.e. Loxodonta africana.
Note that if you have decide to set your token using the third option, then the code should look like the one below:
res1 is an S3 object of class
that contains information sorted into several data frames (see
?spp_taxonconcept for further details):
For some taxa, there are more than one taxon identifier available. In
general only active identifiers are listed, but the full list of identifiers are available in
Also, if the taxon is not listed, a warning message should come up.
spp_taxonconcept() includes several arguments to retrieve a specific subset of information (see
?spp_taxonconcept for more details):
Most importantly, the argument
taxonomy allows a selection between the two databases (CITES or CMS):
updated_since are convenient filters for the written language of common names (must be a two-letters code, see ISO 3166-1 alpha-2) and the last update of the entries, respectively:
In order to use the four
spp_* functions, one needs to use the active taxon identifier of a given species. For instance, for the two species we used as examples above we use the value indicated in the table below:
First, we can retrieve current CITES appendix listings and reservations, CITES quotas, and CITES suspensions for a given taxon concept.
Similarly, we can also retrieve current EU annex listings, SRG opinions, and EU suspensions with
spp_eu_legislation. Both legislation functions have a
scope argument that sets the time scope of legislation and take one value among
all (default is set to
current). For instance, one can get all information pertaining to EU annex listing for Amazilia versicolor with the following command line:
Distribution data at the country level is also available for a given taxon concept: