Get started with rcites

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:

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")

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")

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:

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.

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, 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

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

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

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-------

References

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-------

rcites team

10-08-2018

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

Get your personal token

Set the token

Use of key features

Retrieve a taxon identifiers with spp_taxonconcept()

Basic calls to spp_taxonconcept()

Object `spp_taxonconcept`

Custom calls to spp_taxonconcept()

Retrieve a taxon identifiers available data

CITES legislation data

EU legislation data

Distribution data

References

About

Community

Resources

Get started with rcites

rcites team

10-08-2018

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

Get your personal token

Set the token

Use of key features

Retrieve a taxon identifiers with spp_taxonconcept()

Basic calls to spp_taxonconcept()

Object spp_taxonconcept

Custom calls to spp_taxonconcept()

Retrieve a taxon identifiers available data

CITES legislation data

EU legislation data

Distribution data

References

Object `spp_taxonconcept`