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 rcites
:
set an environment variable SPECIESPLUS_TOKEN
in your .Renviron
file (preferred for frequent users);
use 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);
library(rcites) set_token("8QW6Qgh57sBG2k0gtt")
token
argument 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 forget_token()
.
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.
res1 <- spp_taxonconcept(query_taxon = "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 <- spp_taxonconcept(query_taxon = "Loxodonta africana", token = "8QW6Qgh57sBG2k0gtt")
spp_taxonconcept
res1
is an S3 object of class spp_taxon
:
attributes(res1)
#> $names #> [1] "all_id" "general" "higher_taxa" "accepted_names" "common_names" "synonyms" #> [7] "cites_listings" #> #> $class #> [1] "spp_taxon" #> #> $taxonomy #> [1] "CITES"
that contains information sorted into several data frames (see ?spp_taxonconcept
for further details):
res1
#> #> ── General info - CITES ($general): ────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 8 #> id full_name author_year rank name_status updated_at active cites_listing #> <chr> <chr> <chr> <chr> <chr> <dttm> <lgl> <chr> #> 1 4521 Loxodonta africana (Blumenbach, 1797) SPECIES A 2021-10-13 13:12:58 TRUE I/II #> #> ── Classification ($higher_taxa): ──────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 6 #> id kingdom phylum class order family #> <chr> <chr> <chr> <chr> <chr> <chr> #> 1 4521 Animalia Chordata Mammalia Proboscidea Elephantidae #> #> ── Synonyms ($synonyms): ───────────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 4 #> id full_name author_year rank #> <int> <chr> <chr> <chr> #> 1 37069 Loxodonta cyclotis (Matschie, 1900) SPECIES #> #> ── Common names ($common_names): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 3 #> id name language #> <int> <chr> <chr> #> 1 4521 Ndovo SW #> 2 4521 Tembo SW #> 3 4521 Haathi UR #> 4 4521 Elefante PT #> 5 4521 Slon RU #> 6 4521 Elefant NO #> 7 4521 Olifant NL #> 8 4521 Afrikaanse olifant NL #> 9 4521 Elefante africano ES #> 10 4521 afrikansk elefant SV #> -------truncated------- #> #> Information available: $all_id, $general, $higher_taxa, $accepted_names, $common_names, $synonyms, $cites_listings
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 all_id
:
res3 <- spp_taxonconcept(query = "Amazilia versicolor")
#> ℹ Retrieving info from page 1 ........................ ✔
res3$general
#> # A tibble: 1 × 8 #> id full_name author_year rank name_status updated_at active cites_listing #> * <chr> <chr> <chr> <chr> <chr> <dttm> <lgl> <chr> #> 1 3210 Amazilia versicolor (Vieillot, 1818) SPECIES A 2015-05-07 15:10:59 TRUE II
res3$all_id
#> # A tibble: 2 × 7 #> id full_name author_year rank name_status updated_at active #> <chr> <chr> <chr> <chr> <chr> <dttm> <lgl> #> 1 3210 Amazilia versicolor (Vieillot, 1818) SPECIES A 2015-05-07 15:10:59 TRUE #> 2 65789 Amazilia versicolor (Vieillot, 1818) SPECIES S 2016-09-23 15:30:46 FALSE
Also, if the taxon is not listed, a warning message should come up.
res4 <- spp_taxonconcept(query = "Homo Sapiens")
#> ℹ Retrieving info from page 1 ........................ ✔
#> Warning in spp_taxonconcept(query = "Homo Sapiens"): Taxon not listed.
spp_taxonconcept()
includes several arguments to retrieve a specific subset
of information (see ?spp_taxonconcept
for more details):
args('spp_taxonconcept')
#> function (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, ...) #> NULL
Most importantly, the argument taxonomy
allows a selection between the two
databases (CITES or CMS):
spp_taxonconcept(query = "Amazilia versicolor", taxonomy = "CMS")
#> ℹ Retrieving info from page 1 ........................ ✔
#> Warning in spp_taxonconcept(query = "Amazilia versicolor", taxonomy = "CMS"): Taxon not listed.
#> NULL
spp_taxonconcept(query = "Loxodonta africana", taxonomy = "CMS")
#> ℹ Retrieving info from page 1 ........................ ✔
#> #> ── General info - CMS ($general): ──────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 7 #> id full_name author_year rank name_status updated_at active #> <chr> <chr> <chr> <chr> <chr> <dttm> <lgl> #> 1 11691 Loxodonta africana (Blumenbach, 1797) SPECIES A 2021-05-06 12:44:13 TRUE #> #> ── Classification ($higher_taxa): ──────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 6 #> id kingdom phylum class order family #> <chr> <chr> <chr> <chr> <chr> <chr> #> 1 11691 Animalia Chordata Mammalia Proboscidea Elephantidae #> #> ── Synonyms ($synonyms): ───────────────────────────────────────────────────────────────────────────────────────────── #> No records available. #> #> ── Common names ($common_names): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 3 #> id name language #> <int> <chr> <chr> #> 1 11691 Tembo SW #> 2 11691 Ndovo SW #> 3 11691 Haathi UR #> 4 11691 Elefante PT #> 5 11691 Slon RU #> 6 11691 Elefant NO #> 7 11691 Olifant NL #> 8 11691 Afrikaanse olifant NL #> 9 11691 Elefante africano ES #> 10 11691 afrikansk elefant SV #> -------truncated------- #> #> Information available: $all_id, $general, $higher_taxa, $accepted_names, $common_names, $synonyms
language
and 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:
spp_taxonconcept(query_taxon = "Loxodonta africana", language = 'EN', updated_since = "2016-01-01")
#> ℹ Retrieving info from page 1 ........................ ✔
#> #> ── General info - CITES ($general): ────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 8 #> id full_name author_year rank name_status updated_at active cites_listing #> <chr> <chr> <chr> <chr> <chr> <dttm> <lgl> <chr> #> 1 4521 Loxodonta africana (Blumenbach, 1797) SPECIES A 2021-10-13 13:12:58 TRUE I/II #> #> ── Classification ($higher_taxa): ──────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 6 #> id kingdom phylum class order family #> <chr> <chr> <chr> <chr> <chr> <chr> #> 1 4521 Animalia Chordata Mammalia Proboscidea Elephantidae #> #> ── Synonyms ($synonyms): ───────────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 4 #> id full_name author_year rank #> <int> <chr> <chr> <chr> #> 1 37069 Loxodonta cyclotis (Matschie, 1900) SPECIES #> #> ── Common names ($common_names): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 2 × 3 #> id name language #> <int> <chr> <chr> #> 1 4521 African Elephant EN #> 2 4521 African Savannah Elephant EN #> #> Information available: $all_id, $general, $higher_taxa, $accepted_names, $common_names, $synonyms, $cites_listings
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:
|name | taxon identifier| |:-------------------|:----------------| |Loxodonta africana | 4521 | |Amazilia versicolor | 3210 |
First, we can retrieve current CITES appendix listings and reservations, CITES quotas, and CITES suspensions for a given taxon concept.
spp_cites_legislation(taxon_id = "4521", verbose = FALSE)
#> #> ── Cites listings ($cites_listings): ───────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 6 #> id taxon_concept_id is_current appendix change_type effective_at #> <chr> <chr> <lgl> <chr> <chr> <chr> #> 1 30344 4521 TRUE I + 2017-01-02 #> 2 30115 4521 TRUE II + 2019-11-26 #> 3 32160 4521 TRUE II R+ 2019-11-26 #> 4 32161 4521 TRUE II R+ 2019-11-26 #> 5 32156 4521 TRUE II R+ 2019-11-26 #> 6 32158 4521 TRUE II R+ 2019-11-26 #> 7 32154 4521 TRUE II R+ 2019-11-26 #> 8 32159 4521 TRUE II R+ 2019-11-26 #> 9 32157 4521 TRUE II R+ 2019-11-26 #> 10 32155 4521 TRUE II R+ 2019-11-26 #> #> ── Cites quotas ($cites_quotas): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 10 #> id taxon_concept_id quota publication_date public_display is_current unit geo_entity.iso_code2 geo_entity.name #> <chr> <chr> <chr> <chr> <lgl> <lgl> <chr> <chr> <chr> #> 1 25337 4521 0 2021-02-03 TRUE TRUE <NA> KE Kenya #> 2 25348 4521 0 2021-02-03 TRUE TRUE <NA> LR Liberia #> 3 25355 4521 0 2021-02-03 TRUE TRUE <NA> MW Malawi #> 4 25358 4521 0 2021-02-03 TRUE TRUE <NA> ML Mali #> 5 25375 4521 0 2021-02-03 TRUE TRUE <NA> MZ Mozambique #> 6 25390 4521 0 2021-02-03 TRUE TRUE <NA> AO Angola #> 7 25414 4521 0 2021-02-03 TRUE TRUE <NA> NE Niger #> 8 25431 4521 0 2021-02-03 TRUE TRUE <NA> NG Nigeria #> 9 25554 4521 100 2021-02-03 TRUE TRUE <NA> TZ United Republic… #> 10 25555 4521 300 2021-02-03 TRUE TRUE <NA> ZA South Africa #> # … with 1 more variable: geo_entity.type <chr> #> -------truncated------- #> Field(s) not printed: notes, url #> #> ── Cites suspensions ($cites_suspensions): ─────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 8 #> id taxon_concept_id start_date is_current applies_to_import geo_entity.iso_code2 geo_entity.name geo_entity.type #> <chr> <chr> <chr> <lgl> <lgl> <chr> <chr> <chr> #> 1 17621 4521 2014-08-11 TRUE TRUE US United States … COUNTRY #> 2 17620 4521 2014-08-11 TRUE TRUE US United States … COUNTRY #> 3 17686 4521 2014-10-10 TRUE TRUE US United States … COUNTRY #> 4 18709 4521 2010-08-16 TRUE TRUE ZW Zimbabwe COUNTRY #> 5 15983 <NA> 2011-01-19 TRUE FALSE DJ Djibouti COUNTRY #> 6 22079 <NA> 2018-01-30 TRUE FALSE DJ Djibouti COUNTRY #> 7 22076 <NA> 2018-01-22 TRUE FALSE LR Liberia COUNTRY #> 8 22132 4521 2018-03-19 TRUE FALSE AU Australia COUNTRY #> 9 23168 <NA> 2019-07-04 TRUE FALSE SO Somalia COUNTRY #> 10 24947 4521 2020-05-26 TRUE TRUE CN China COUNTRY #> -------truncated------- #> Field(s) not printed: notes, start_notification.name, start_notification.date, start_notification.url
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
current
, historic
and 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:
spp_eu_legislation(taxon_id = "3210", scope = "all", verbose = FALSE)
#> #> ── EU listings ($eu_listings): ─────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 6 #> id taxon_concept_id is_current annex change_type effective_at #> <chr> <chr> <lgl> <chr> <chr> <chr> #> 1 17611 3210 FALSE B + 1997-06-01 #> 2 17610 3210 FALSE B + 2000-12-18 #> 3 17609 3210 FALSE B + 2003-08-30 #> 4 17608 3210 FALSE B + 2005-08-22 #> 5 17607 3210 FALSE B + 2008-04-11 #> 6 17606 3210 FALSE B + 2009-05-22 #> 7 17605 3210 FALSE B + 2010-08-15 #> 8 17604 3210 FALSE B + 2012-02-14 #> 9 17603 3210 FALSE B + 2012-12-15 #> 10 17602 3210 FALSE B + 2013-08-10 #> -------truncated------- #> #> ── EU decisions ($eu_decisions): ───────────────────────────────────────────────────────────────────────────────────── #> No records available.
Distribution data at the country level is also available for a given taxon concept:
spp_distributions("4521", verbose = FALSE)
#> #> ── Distributions ($distributions): ─────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 5 #> id iso_code2 name type tags #> <int> <chr> <chr> <chr> <chr> #> 1 1778 ML Mali COUNTRY "" #> 2 1923 GQ Equatorial Guinea COUNTRY "" #> 3 4429 RW Rwanda COUNTRY "" #> 4 4491 GH Ghana COUNTRY "" #> 5 5628 SD Sudan COUNTRY "" #> 6 6724 ET Ethiopia COUNTRY "" #> 7 8995 GA Gabon COUNTRY "" #> 8 12983 AO Angola COUNTRY "" #> 9 15554 CM Cameroon COUNTRY "" #> 10 17060 BJ Benin COUNTRY "" #> -------truncated------- #> #> ── References ($references): ───────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 2 #> id reference #> <int> <chr> #> 1 1778 Kingdon, J., Happold [truncated] #> 2 1923 Basilio, A. 1962. La [truncated] #> 3 4429 Jackson, P. 1982. El [truncated] #> 4 4429 Monfort, A. 1992. Pr [truncated] #> 5 4491 Grubb, P., Jones, T. [truncated] #> 6 4491 Jackson, P. 1982. El [truncated] #> 7 5628 Hameed, S.M.A. and E [truncated] #> 8 6724 Bolton, M. 1973. Not [truncated] #> 9 6724 Largen, M. J. and Ya [truncated] #> 10 6724 Meester, J. and Setz [truncated] #> -------truncated-------
Finally, we can retrieve all available references for a given taxa.
spp_references("4521", verbose = FALSE)
#> #> ── References ($references): ───────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 3 #> id citation is_standard #> <chr> <chr> <chr> #> 1 10265 Anon. 1978. Red data book: Mammalia. IUC [truncated] FALSE #> 2 6344 Barnes, R. F., Agnagna, M., Alers, M. P. [truncated] FALSE #> 3 17013 Blanc, J.J., Thouless, C.R., Hart, J.A., [truncated] FALSE #> 4 6371 Burton, M. P. 1994. Alternative projecti [truncated] FALSE #> 5 6532 Douglas-Hamilton, I. 1987. African Eleph [truncated] FALSE #> 6 6534 Douglas-Hamilton, I. 1987. African Eleph [truncated] FALSE #> 7 6825 Jackson, P. 1982. Elephants and rhinos i [truncated] FALSE #> 8 7224 Meester, J. and Setzer, H. W (eds.) 1974 [truncated] FALSE #> 9 7609 Parker, I. and Amin, M. 1983. Ivory cris [truncated] FALSE #> 10 19397 Parker, I.S.C. and Martin, E.B. 1982. Ho [truncated] FALSE #> -------truncated-------
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.