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);
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.
#> → Retrieving info from page 1 ........................✔Note that if you have decide to set your token using the third option, then the code should look like the one below:
spp_taxonconceptres1 is an S3 object of class spp_taxon:
#> $names
#> [1] "all_id" "general" "higher_taxa" "accepted_names"
#> [5] "common_names" "synonyms" "cites_listings"
#>
#> $class
#> [1] "spp_taxon"
#>
#> $taxonomy
#> [1] "CITES"that contains information sorted into several data frames (see ?spp_taxonconcept for further details):
#>
#> ── General info - CITES ($general): ───────────────────────────────────────
#> id full_name author_year rank name_status
#> 1 4521 Loxodonta africana (Blumenbach, 1797) SPECIES A
#> updated_at active cites_listing
#> 1 2019-05-09 11:12:49 TRUE I/II
#>
#> ── Classification ($higher_taxa): ─────────────────────────────────────────
#> id kingdom phylum class order family
#> 1 4521 Animalia Chordata Mammalia Proboscidea Elephantidae
#>
#> ── Synonyms ($synonyms): ──────────────────────────────────────────────────
#> id apply.do.call.rbind..tmp.wch....2..unlist.
#> 1 4521 37069
#> 2 4521 Loxodonta cyclotis
#> 3 4521 (Matschie, 1900)
#> 4 4521 SPECIES
#>
#> ── Common names ($common_names): ──────────────────────────────────────────
#> id name language
#> 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:
#> → Retrieving info from page 1 ........................✔#> id full_name author_year rank name_status
#> 1 3210 Amazilia versicolor (Vieillot, 1818) SPECIES A
#> updated_at active cites_listing
#> 1 2015-05-07 15:10:59 TRUE II#> id full_name author_year rank name_status
#> 1 3210 Amazilia versicolor (Vieillot, 1818) SPECIES A
#> 2 65789 Amazilia versicolor (Vieillot, 1818) SPECIES S
#> updated_at active
#> 1 2015-05-07 15:10:59 TRUE
#> 2 2016-09-23 15:30:46 FALSEAlso, if the taxon is not listed, a warning message should come up.
#> → 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):
#> function (query_taxon, taxonomy = "CITES", with_descendants = FALSE,
#> language = NULL, updated_since = NULL, per_page = 500, pages = NULL,
#> raw = FALSE, token = NULL, verbose = TRUE, ...)
#> NULLMost importantly, the argument taxonomy allows a selection between the two databases (CITES or CMS):
#> → Retrieving info from page 1 ........................✔#> Warning in spp_taxonconcept(query = "Amazilia versicolor", taxonomy =
#> "CMS"): Taxon not listed.#> NULL#> → Retrieving info from page 1 ........................✔#>
#> ── General info - CMS ($general): ─────────────────────────────────────────
#> id full_name author_year rank name_status
#> 1 11691 Loxodonta africana (Blumenbach, 1797) SPECIES A
#> updated_at active
#> 1 2018-06-05 09:19:14 TRUE
#>
#> ── Classification ($higher_taxa): ─────────────────────────────────────────
#> id kingdom phylum class order family
#> 1 11691 Animalia Chordata Mammalia Proboscidea Elephantidae
#>
#> ── Synonyms ($synonyms): ──────────────────────────────────────────────────
#> data frame with 0 columns and 0 rows
#>
#> ── Common names ($common_names): ──────────────────────────────────────────
#> id name language
#> 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:
#> → Retrieving info from page 1 ........................✔#>
#> ── General info - CITES ($general): ───────────────────────────────────────
#> id full_name author_year rank name_status
#> 1 4521 Loxodonta africana (Blumenbach, 1797) SPECIES A
#> updated_at active cites_listing
#> 1 2019-05-09 11:12:49 TRUE I/II
#>
#> ── Classification ($higher_taxa): ─────────────────────────────────────────
#> id kingdom phylum class order family
#> 1 4521 Animalia Chordata Mammalia Proboscidea Elephantidae
#>
#> ── Synonyms ($synonyms): ──────────────────────────────────────────────────
#> id apply.do.call.rbind..tmp.wch....2..unlist.
#> 1 4521 37069
#> 2 4521 Loxodonta cyclotis
#> 3 4521 (Matschie, 1900)
#> 4 4521 SPECIES
#>
#> ── Common names ($common_names): ──────────────────────────────────────────
#> id name language
#> 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.
#>
#> ── Cites listings ($cites_listings): ──────────────────────────────────────
#> id taxon_concept_id is_current appendix change_type effective_at
#> 1 3666 4521 TRUE II + 2007-09-13
#> 2 3665 4521 TRUE I + 2007-09-13
#> 3 3645 4521 TRUE I R+ 1990-01-18
#>
#> ── Cites quotas ($cites_quotas): ──────────────────────────────────────────
#> id taxon_concept_id quota publication_date public_display is_current
#> 1 20604 4521 0 2017-03-06 TRUE TRUE
#> 2 20586 4521 0 2017-03-06 TRUE TRUE
#> 3 20695 4521 0 2017-03-06 TRUE TRUE
#> 4 20696 4521 0 2017-03-06 TRUE TRUE
#> 5 20697 4521 0 2017-03-06 TRUE TRUE
#> 6 20698 4521 0 2017-03-06 TRUE TRUE
#> 7 20699 4521 0 2017-03-06 TRUE TRUE
#> 8 20700 4521 0 2017-03-06 TRUE TRUE
#> 9 20701 4521 0 2017-03-06 TRUE TRUE
#> 10 20703 4521 0 2017-03-06 TRUE TRUE
#> unit geo_entity.iso_code2 geo_entity.name geo_entity.type
#> 1 <NA> CG Congo COUNTRY
#> 2 <NA> AO Angola COUNTRY
#> 3 <NA> BW Botswana COUNTRY
#> 4 <NA> BF Burkina Faso COUNTRY
#> 5 <NA> CF Central African Republic COUNTRY
#> 6 <NA> CI Côte d'Ivoire COUNTRY
#> 7 <NA> GW Guinea Bissau COUNTRY
#> 8 <NA> LR Liberia COUNTRY
#> 9 <NA> SL Sierra Leone COUNTRY
#> 10 <NA> GA Gabon COUNTRY
#> -------truncated-------
#> Field(s) not printed: notes, url
#>
#> ── Cites suspensions ($cites_suspensions): ────────────────────────────────
#> id taxon_concept_id start_date is_current applies_to_import
#> 1 15986 <NA> 2013-05-16 TRUE FALSE
#> 2 17621 4521 2014-08-11 TRUE TRUE
#> 3 17620 4521 2014-08-11 TRUE TRUE
#> 4 17686 4521 2014-10-10 TRUE TRUE
#> 5 18709 4521 2010-08-16 TRUE TRUE
#> 6 15983 <NA> 2011-01-19 TRUE FALSE
#> 7 15971 <NA> 2004-07-30 TRUE FALSE
#> 8 18955 4521 2016-04-01 TRUE TRUE
#> 9 22079 <NA> 2018-01-30 TRUE FALSE
#> 10 22076 <NA> 2018-01-22 TRUE FALSE
#> geo_entity.iso_code2 geo_entity.name geo_entity.type
#> 1 GN Guinea COUNTRY
#> 2 ZW Zimbabwe COUNTRY
#> 3 TZ United Republic of Tanzania COUNTRY
#> 4 US United States of America COUNTRY
#> 5 ZW Zimbabwe COUNTRY
#> 6 DJ Djibouti COUNTRY
#> 7 SO Somalia COUNTRY
#> 8 CN China COUNTRY
#> 9 DJ Djibouti COUNTRY
#> 10 LR Liberia 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:
#>
#> ── EU listings ($eu_listings): ────────────────────────────────────────────
#> id taxon_concept_id is_current annex change_type effective_at
#> 1 17604 3210 FALSE B + 2012-02-14
#> 2 17603 3210 FALSE B + 2012-12-15
#> 3 17606 3210 FALSE B + 2009-05-22
#> 4 17607 3210 FALSE B + 2008-04-11
#> 5 17609 3210 FALSE B + 2003-08-30
#> 6 17610 3210 FALSE B + 2000-12-18
#> 7 17611 3210 FALSE B + 1997-06-01
#> 8 17605 3210 FALSE B + 2010-08-15
#> 9 17608 3210 FALSE B + 2005-08-22
#> 10 17602 3210 FALSE B + 2013-08-10
#> -------truncated-------
#>
#> ── EU decisions ($eu_decisions): ──────────────────────────────────────────
#> data frame with 0 columns and 0 rowsDistribution data at the country level is also available for a given taxon concept:
#>
#> ── Distributions ($distributions): ────────────────────────────────────────
#> id iso_code2 name type tags
#> 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): ──────────────────────────────────────────────
#> id reference
#> 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.
#>
#> ── References ($references): ──────────────────────────────────────────────
#> id citation is_standard
#> 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-------