Set up a connection to the Species+/CITES Checklist API

Get your personal token

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.

Set the token

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:

  1. set an environment variable SPECIESPLUS_TOKEN in your .Renviron file (preferred for frequent users);

  2. 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")
  1. use the 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().

Use of key features

Retrieve a taxon identifiers with spp_taxonconcept()

Basic calls to spp_taxonconcept()

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")
#>  → 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:

res1 <- spp_taxonconcept(query_taxon = "Loxodonta africana", token = "8QW6Qgh57sBG2k0gtt")

Object spp_taxonconcept

res1 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_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 ........................✔
#>      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  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.

Custom calls to spp_taxonconcept()

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, ...) 
#>  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): ─────────────────────────────────────────
#>       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, $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): ───────────────────────────────────────
#>      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_listings

Retrieve a taxon identifiers available data

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

CITES legislation data

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): ──────────────────────────────────────
#>      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.url

EU legislation data

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): ────────────────────────────────────────────
#>        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 rows

Distribution data

Distribution data at the country level is also available for a given taxon concept:

spp_distributions("4521", verbose = FALSE)
#>  
#>  ── 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-------

References

Finally, we can retrieve all available references for a given taxa.

spp_references("4521", verbose = FALSE)
#>  
#>  ── 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-------

Bulk analysis

Please see Bulk analysis with rcites for details.