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_taxonconceptres1 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_listingsFor 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 IIres3$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 FALSEAlso, 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, ...)
#> NULLMost 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.#> NULLspp_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, $synonymslanguage 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_listingsIn 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.urlSimilarly, 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-------