---
title: "Get started with rcites"
author: "rcites team"
date: 10-08-2018
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with rcites}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---





# 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](http://api.speciesplus.net/users/sign_up).

## 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`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html)
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);


```r
library(rcites)
set_token("8QW6Qgh57sBG2k0gtt")
```

3. 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](https://api.speciesplus.net/documentation/v1/taxon_concepts/index.html).
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*.


```r
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:


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

### Object `spp_taxonconcept`

`res1` is an S3 object of class `spp_taxon`:


```r
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):



```r
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`:


```r
res3 <- spp_taxonconcept(query = "Amazilia versicolor")
```

```
#>  ℹ Retrieving info from page 1 ........................ ✔
```

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

```r
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.


```r
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):


```r
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):


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

```r
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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2))
and the last update of the entries, respectively:


```r
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.


```r
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:


```r
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:


```r
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.


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