| Type: | Package |
| Title: | 'IUCN' Red List Client |
| Description: | 'IUCN' Red List (https://api.iucnredlist.org/) client. The 'IUCN' Red List is a global list of threatened and endangered species. Functions cover all of the Red List 'API' routes. An 'API' key is required. |
| Version: | 1.0.0 |
| License: | MIT + file LICENSE |
| URL: | https://docs.ropensci.org/rredlist/, https://github.com/ropensci/rredlist |
| BugReports: | https://github.com/ropensci/rredlist/issues |
| Encoding: | UTF-8 |
| Language: | en-US |
| Imports: | crul (≥ 0.3.8), jsonlite (≥ 1.1), lifecycle, cli, curl, rlang |
| Suggests: | spelling, testthat, vcr (≥ 0.6.0), knitr, rmarkdown, webmockr, microbenchmark, ggplot2, dplyr, patchwork, vdiffr |
| RoxygenNote: | 7.3.2 |
| VignetteBuilder: | knitr |
| X-schema.org-applicationCategory: | Biodiversity |
| X-schema.org-keywords: | IUCN, biodiversity, API, web-services, traits, habitat, species, conservation |
| X-schema.org-isPartOf: | https://ropensci.org |
| NeedsCompilation: | no |
| Packaged: | 2025-01-31 17:41:43 UTC; willg |
| Author: | William Gearty [aut, cre],
Scott Chamberlain [aut],
rOpenSci [fnd] (https://ropensci.org/),
Maëlle Salmon [ctb],
Kevin Cazelles 
[rev],
Stephanie Hazlitt [rev] |
| Maintainer: | William Gearty <willgearty@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2025-01-31 18:30:02 UTC |
rredlist: 'IUCN' Red List Client
Description
'IUCN' Red List (https://api.iucnredlist.org/) client. The 'IUCN' Red List is a global list of threatened and endangered species. Functions cover all of the Red List 'API' routes. An 'API' key is required.
Authentication
IUCN requires you to get your own API key, an alphanumeric string that you
need to send in every request. See rl_use_iucn() for help getting and
storing it. Get it at https://api.iucnredlist.org/users/sign_up. Keep this
key private. You can pass the key in to each function via the key
parameter, but it's better to store the key either as an environment variable
(IUCN_REDLIST_KEY) or an R option (iucn_redlist_key) - we recommend using
the former option.
High vs. Low level package APIs
High level API
High level functions do the HTTP request and parse data to a data.frame for
ease of downstream use. The high level functions have no underscore on
the end of the function name, e.g., rl_species().
Low level API
The parsing to data.frame in the high level API does take extra time.
The low level API only does the HTTP request, and gives back JSON without
doing any more parsing. The low level functions DO have an underscore on
the end of the function name, e.g., rl_species_().
No Spatial
This package does not include support for the spatial API, described at https://apiv3.iucnredlist.org/spatial.
Citing the IUCN Red List API
Get the proper citation for the version of the Red List you are using
by programatically running rl_citation(). Also see
https://api.iucnredlist.org/.
Red List API Terms of Use
See https://www.iucnredlist.org/terms/terms-of-use.
Rate limiting
From the IUCN folks: Too many frequent calls, or too many calls per day might get your access blocked temporarily. If you're a heavy API user, the Red List Unit asked that you contact them, as there might be better options. They suggest a 2-second delay between your calls if you plan to make a lot of calls.
Author(s)
Maintainer: William Gearty willgearty@gmail.com
Authors:
Scott Chamberlain myrmecocystus@gmail.com
Other contributors:
rOpenSci (https://ropensci.org/) [funder]
Maëlle Salmon maelle.salmon@yahoo.se [contributor]
Kevin Cazelles kevin.cazelles@insileco.io (ORCID) [reviewer]
Stephanie Hazlitt stephhazlitt@gmail.com [reviewer]
See Also
Useful links:
Report bugs at https://github.com/ropensci/rredlist/issues
Conservation actions needed assessment summary
Description
Return the latest assessments with a given conservation action needed (e.g., Land/water management or Species recovery). These conservation action codes correspond to the IUCN Red List Conservation Actions Classification Scheme (v2.0).
Usage
rl_actions(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_actions_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the conservation action to look up. If not supplied, a list of all conservation actions will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by conservation actions or research needed:
rl_research()
Examples
## Not run:
# Get list of all conservation actions
rl_actions()
# Get assessments with Species recovery conservation action needed
rl_actions("3_2")
## End(Not run)
Get the Red List API version
Description
Returns the current version number of the IUCN Red List of Threatened Species API.
Usage
rl_api_version(key = NULL, ...)
Arguments
key |
(character) An IUCN API token. See |
... |
Curl options passed to HttpClient. |
Value
API version as character string.
See Also
Red List information and statistics:
rl_citation(),
rl_sp_count(),
rl_version()
Examples
## Not run:
rl_api_version()
## End(Not run)
Retrieve an assessment
Description
Get the full details for a single IUCN Red List assessment.
Usage
rl_assessment(id, key = NULL, parse = TRUE, ...)
rl_assessment_(id, key = NULL, ...)
Arguments
id |
(integer) The unique identifier of the assessment. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
... |
Includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
Examples
## Not run:
# Get assessment details for Fratercula arctica
ex1 <- rl_assessment(id = 166290968)
ex1$red_list_category$code
ex1$systems
## End(Not run)
Red List category assessment summary
Description
Return a list of the latest assessments for a given category (e.g., Not Evaluated, Data Deficient, Least Concern, Near Threatened, Vulnerable, Endangered, Critically Endangered, Extinct in the Wild and Extinct). This endpoint returns categories for the current IUCN Red List Categories and Criteria (v3.1) as well as older versions (i.e., v2.3). Note that a code may not be unique across Categories and Criteria versions. Therefore, codes like "EX" will return assessments for EX v3.1 and EX v2.3.
Usage
rl_categories(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_categories_(
code = NULL,
key = NULL,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
Arguments
code |
(character) The code of the Red List category to look up. If not supplied, a list of all categories will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by threat details:
rl_pop_trends(),
rl_stresses(),
rl_threats(),
rl_use_and_trade()
Examples
## Not run:
# Get all Red List categories
rl_categories()
# Get assessments for the Vulnerable category
rl_categories("VU")
## End(Not run)
Get the citation for the Red List API
Description
Full acknowledgement and citation needs to be given for using the API. Use this function to get the full citation for the current version of the Red List API. More details are available here: https://api.iucnredlist.org/.
Usage
rl_citation(key = NULL, ...)
Arguments
key |
(character) An IUCN API token. See |
... |
Curl options passed to HttpClient. |
Value
Red List citation as a bibentry object.
See Also
Red List information and statistics:
rl_api_version(),
rl_sp_count(),
rl_version()
Examples
## Not run:
rl_citation()
## End(Not run)
Class assessment summary
Description
Get an assessment summary for a particular class
Usage
rl_class(
class = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_class_(class = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
class |
(character) The name of the class to look up. If not supplied, a list of all class names will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_family(),
rl_kingdom(),
rl_order(),
rl_phylum(),
rl_sis(),
rl_sis_latest(),
rl_species(),
rl_species_latest()
Examples
## Not run:
# Get assessment summary for class
ex1 <- rl_class(class = "Mammalia")
nrow(ex1$assessments)
## End(Not run)
Get common names for a given taxonomic name
Description
![[Deprecated]](../help/figures/lifecycle-deprecated.svg)
This function is fully deprecated in favor of
rl_species_latest()$taxon$common_names as of rredlist version
1.0.0.
Comprehensive group assessment summary
Description
Returns a list of the latest assessments for a comprehensive group name.
Usage
rl_comp_groups(
name = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_comp_groups_(
name = NULL,
key = NULL,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
Arguments
name |
(character) The code of the comprehensive group to look up. If not supplied, a list of all comprehensive groups will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments for specific sets of taxa
rl_extinct(),
rl_extinct_wild(),
rl_green(),
rl_growth_forms()
Examples
## Not run:
# Get list of all comprehensive groups
rl_comp_groups()
# Get assessment summary for sea snakes
rl_comp_groups('seasnakes')
## End(Not run)
Country assessment summary
Description
Returns a collection of assessments for a given country code.
Usage
rl_countries(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_countries_(
code = NULL,
key = NULL,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
Arguments
code |
(character) The ISO alpha-2 code of the country to look up. If not supplied, a list of all countries will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by geographic regions:
rl_faos(),
rl_realms(),
rl_scopes()
Examples
## Not run:
# Get list of all countries
rl_countries()
# Get assessments for Madagascar
rl_countries("MG")
## End(Not run)
Extinct taxa assessment summary
Description
Get an assessment summary for all possibly extinct taxa
Usage
rl_extinct(key = NULL, parse = TRUE, all = TRUE, page = 1, quiet = FALSE, ...)
rl_extinct_(key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments for specific sets of taxa
rl_comp_groups(),
rl_extinct_wild(),
rl_green(),
rl_growth_forms()
Examples
## Not run:
ex1 <- rl_extinct()
nrow(ex1$assessments)
## End(Not run)
Extinct taxa in the wild assessment summary
Description
Get an assessment summary for all taxa that are possibly extinct in the wild
Usage
rl_extinct_wild(
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_extinct_wild_(key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments for specific sets of taxa
rl_comp_groups(),
rl_extinct(),
rl_green(),
rl_growth_forms()
Examples
## Not run:
ex1 <- rl_extinct_wild()
nrow(ex1$assessments)
## End(Not run)
Family assessment summary
Description
Get an assessment summary for a particular family
Usage
rl_family(
family = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_family_(family = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
family |
(character) The name of the family to look up. If not supplied, a list of all family names will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_class(),
rl_kingdom(),
rl_order(),
rl_phylum(),
rl_sis(),
rl_sis_latest(),
rl_species(),
rl_species_latest()
Examples
## Not run:
# Get assessment summary for family
ex1 <- rl_family(family = "Hominidae")
nrow(ex1$assessments)
## End(Not run)
FAO marine fishing region assessment summary
Description
Return assessments for a given marine fishing region as defined by the Food and Agriculture Organization (FAO) of the United Nations (e.g., Pacific - northwest, Arctic Sea). More details are available here: https://www.fao.org/fishery/en/area.
Usage
rl_faos(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_faos_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the FAO region to look up. If not supplied, a list of all FAO regions will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by geographic regions:
rl_countries(),
rl_realms(),
rl_scopes()
Examples
## Not run:
# Get a list of all scopes
rl_faos()
# Get assessment summary for the Arctic Sea FAO region
rl_faos(code = "18")
## End(Not run)
Green Status assessment summary
Description
List all Green Status assessments.
Usage
rl_green(key = NULL, parse = TRUE, ...)
rl_green_(key = NULL, ...)
Arguments
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
... |
Includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments for specific sets of taxa
rl_comp_groups(),
rl_extinct(),
rl_extinct_wild(),
rl_growth_forms()
Examples
## Not run:
# Get list of Green Status assessments
rl_green()
## End(Not run)
Growth form assessment summary
Description
Returns a list of the latest assessments for a given growth form code.
Usage
rl_growth_forms(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_growth_forms_(
code = NULL,
key = NULL,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
Arguments
code |
(character) The code of the growth form to look up. If not supplied, a list of all growth forms will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments for specific sets of taxa
rl_comp_groups(),
rl_extinct(),
rl_extinct_wild(),
rl_green()
Examples
## Not run:
# Get list of all growth forms
rl_growth_forms()
# Get assessment summary for lichens
rl_growth_forms("LC")
## End(Not run)
Habitat assessment summary
Description
Return the latest assessments for a given habitat (e.g., Forest - Temperate or Marine Intertidal). These habitat codes correspond to the IUCN Red List Habitats Classification Scheme (v3.1).
Usage
rl_habitats(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_habitats_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the habitat to look up. If not supplied, a list of all habitats will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by habitats and systems:
rl_systems()
Examples
## Not run:
# Get list of all habitats
rl_habitats()
# Get assessments for Marine Intertidal habitat
rl_habitats("12")
## End(Not run)
Get historical assessments by taxon name, IUCN id, and region
Description
This function is fully deprecated in favor of rl_species() as of
rredlist version 1.0.0.
Kingdom assessment summary
Description
Get an assessment summary for a particular kingdom
Usage
rl_kingdom(
kingdom = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_kingdom_(
kingdom = NULL,
key = NULL,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
Arguments
kingdom |
(character) The name of the kingdom to look up. If not supplied, a list of all kingdom names will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_class(),
rl_family(),
rl_order(),
rl_phylum(),
rl_sis(),
rl_sis_latest(),
rl_species(),
rl_species_latest()
Examples
## Not run:
# Get assessment summary for kingdom
ex1 <- rl_kingdom(kingdom = "Fungi")
nrow(ex1$assessments)
## End(Not run)
Get species conservation measures by taxon name, IUCN id, and region
Description
This function is fully deprecated in favor of
rl_species_latest()$conservation_actions as of rredlist version
1.0.0.
Get species narrative information by taxon name, IUCN id, and region
Description
This function is fully deprecated in favor of
rl_species_latest()$documentation as of rredlist version 1.0.0.
Get country occurrence by species name or ID
Description
This function is fully deprecated in favor of
rl_species_latest()$locations as of rredlist version 1.0.0.
Order assessment summary
Description
Get an assessment summary for a particular order
Usage
rl_order(
order = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_order_(order = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
order |
(character) The name of the order to look up. If not supplied, a list of all order names will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_class(),
rl_family(),
rl_kingdom(),
rl_phylum(),
rl_sis(),
rl_sis_latest(),
rl_species(),
rl_species_latest()
Examples
## Not run:
# Get assessment summary for order
ex1 <- rl_order(order = "Apiales")
nrow(ex1$assessments)
## End(Not run)
Phylum assessment summary
Description
Get an assessment summary for a particular phylum
Usage
rl_phylum(
phylum = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_phylum_(phylum = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
phylum |
(character) The name of the phylum to look up. If not supplied, a list of all phylum names will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_class(),
rl_family(),
rl_kingdom(),
rl_order(),
rl_sis(),
rl_sis_latest(),
rl_species(),
rl_species_latest()
Examples
## Not run:
# Get assessment summary for phylum
ex1 <- rl_phylum(phylum = "Annelida`")
nrow(ex1$assessments)
## End(Not run)
Population trend assessment summary
Description
Return a list of the latest assessments based on a population trend (i.e. increasing, decreasing, stable or unknown).
Usage
rl_pop_trends(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_pop_trends_(
code = NULL,
key = NULL,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
Arguments
code |
(character) The code of the growth form to look up. If not supplied, a list of all growth forms will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by threat details:
rl_categories(),
rl_stresses(),
rl_threats(),
rl_use_and_trade()
Examples
## Not run:
# Get list of all population trends
rl_pop_trends()
# Get assessment summary for stable population trends
rl_pop_trends("2")
## End(Not run)
Biogeographical realm assessment summary
Description
Get an assessment summary for a particular biogeographical realm (e.g., Neotropical or Palearctic).
Usage
rl_realms(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_realms_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the biogeographical realm to look up. If not supplied, a list of all biogeographical realms will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by geographic regions:
rl_countries(),
rl_faos(),
rl_scopes()
Examples
## Not run:
# Get a list of all biogeographical realms
rl_realms()
# Get assessment summary for the Afrotropical biogeographical realm
rl_realms(code = "0")
## End(Not run)
Get regions
Description
This function is fully deprecated in favor of rl_scopes(code = NULL) as of rredlist version 1.0.0.
Research needed assessment summary
Description
Return the latest assessments with a given research needed (e.g., Taxonomy or Population trends). These research codes correspond to the IUCN Red List Research Needed Classification Scheme (v1.0).
Usage
rl_research(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_research_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the research type to look up. If not supplied, a list of all research types will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by conservation actions or research needed:
rl_actions()
Examples
## Not run:
# Get list of all research types
rl_research()
# Get assessments with Taxonomy research needed
rl_research("1_1")
## End(Not run)
Scope assessment summary
Description
Return assessments for a given geographical assessment scope (e.g., Global,
Mediterranean). This is similar to the region argument of the old Red List
API and old versions of rredlist.
Usage
rl_scopes(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_scopes_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the scope to look up. If not supplied, a list of all scopes will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by geographic regions:
rl_countries(),
rl_faos(),
rl_realms()
Examples
## Not run:
# Get a list of all scopes
rl_scopes()
# Get assessment summary for the Gulf of Mexico scope
rl_scopes(code = "45433062")
## End(Not run)
Search by taxon name, IUCN id, and region
Description
This function is fully deprecated in favor of rl_species(), rl_sis(),
and rl_scopes() as of rredlist version 1.0.0.
SIS ID assessment summary
Description
Get an assessment summary for a particular taxonomic entity based on its ID number from the IUCN Species Information Service (SIS).
Usage
rl_sis(id, key = NULL, parse = TRUE, ...)
rl_sis_(id, key = NULL, ...)
Arguments
id |
(integer) The SIS ID of the taxonomic entity to look up. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
... |
Includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_class(),
rl_family(),
rl_kingdom(),
rl_order(),
rl_phylum(),
rl_sis_latest(),
rl_species(),
rl_species_latest()
Examples
## Not run:
# Get assessment summary for species
ex1 <- rl_sis(id = 9404)
nrow(ex1$assessments)
## End(Not run)
SIS ID latest assessment
Description
Get the latest assessment for a particular taxonomic entity based on its ID
number from the IUCN Species Information Service (SIS). Wraps rl_sis() and
rl_assessment().
Usage
rl_sis_latest(id, key = NULL, parse = TRUE, ...)
Arguments
id |
(integer) The SIS ID of the taxonomic entity to look up. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
... |
Includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_class(),
rl_family(),
rl_kingdom(),
rl_order(),
rl_phylum(),
rl_sis(),
rl_species(),
rl_species_latest()
Examples
## Not run:
# Get latest assessment for species
ex1 <- rl_sis_latest(id = 9404)
ex1$stresses
## End(Not run)
Get species
Description
This function is fully deprecated in favor of rl_kingdom(),
rl_phylum(), rl_class(), rl_order(), and rl_family() as of
rredlist version 1.0.0.
Get species by category
Description
This function is fully deprecated in favor of rl_categories() as of
rredlist version 1.0.0.
Get citations by taxon name, IUCN id, and region
Description
This function is fully deprecated in favor of
rl_species_latest()$citation as of rredlist version 1.0.0.
Get count of species in the Red List
Description
Returns a count of the number of unique species which have assessments.
Usage
rl_sp_count(key = NULL, ...)
rl_sp_count_(key = NULL, ...)
Arguments
key |
(character) An IUCN API token. See |
... |
Curl options passed to HttpClient |
Value
An integer representing the number of unique species represented within the IUCN database.
References
API docs at https://api.iucnredlist.org/.
See Also
Red List information and statistics:
rl_api_version(),
rl_citation(),
rl_version()
Examples
## Not run:
# Get count of species with assessments
rl_sp_count()
## End(Not run)
Get species by country
Description
This function is fully deprecated in favor of rl_countries() as of
rredlist version 1.0.0.
Species assessment summary
Description
Get an assessment summary for a particular species (i.e., Latin binomial) or subspecies/variety/subpopulation (i.e., Latin trinomial).
Usage
rl_species(
genus,
species,
infra = NULL,
subpopulation = NULL,
key = NULL,
parse = TRUE,
...
)
rl_species_(
genus,
species,
infra = NULL,
subpopulation = NULL,
key = NULL,
...
)
Arguments
genus |
(character) The genus name of the species to look up. |
species |
(character) The species epithet of the species to look up. |
infra |
(character) An optional name of the subspecies or variety to look up. |
subpopulation |
(character) An optional name of the geographically separate subpopulation to look up. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
... |
Includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Details
Geographically separate subpopulations of a species are defined as those populations that are so isolated from others of the same species that it is considered extremely unlikely that there is any genetic interchange. In general, listings of such subpopulations are restricted to those that have been isolated for a long period of time.
Assessments of subspecies, varieties, and geographically separate subpopulations must adhere to the same standards as for species assessments. However, these assessments are only included provided there is a global assessment of the species as a whole.
Infraspecific ranks such as formas, subvarieties, cultivars, etc are not included in the Red List.
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_class(),
rl_family(),
rl_kingdom(),
rl_order(),
rl_phylum(),
rl_sis(),
rl_sis_latest(),
rl_species_latest()
Examples
## Not run:
# Get assessment summary for species
ex1 <- rl_species(genus = "Fratercula", species = "arctica")
nrow(ex1$assessments)
# Get assessment summary for subspecies
ex2 <- rl_species(genus = "Gorilla", species = "gorilla",
infra = "gorilla")
nrow(ex2$assessments)
## End(Not run)
Species latest assessment
Description
Get the latest assessment for a particular species (i.e., Latin binomial) or
subspecies/variety/subpopulation (i.e., Latin trinomial). Wraps
rl_species() and rl_assessment().
Usage
rl_species_latest(
genus,
species,
infra = NULL,
subpopulation = NULL,
key = NULL,
parse = TRUE,
...
)
Arguments
genus |
(character) The genus name of the species to look up. |
species |
(character) The species epithet of the species to look up. |
infra |
(character) An optional name of the subspecies or variety to look up. |
subpopulation |
(character) An optional name of the geographically separate subpopulation to look up. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
... |
Includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Details
Geographically separate subpopulations of a species are defined as those populations that are so isolated from others of the same species that it is considered extremely unlikely that there is any genetic interchange. In general, listings of such subpopulations are restricted to those that have been isolated for a long period of time.
Assessments of subspecies, varieties, and geographically separate subpopulations must adhere to the same standards as for species assessments. However, these assessments are only included provided there is a global assessment of the species as a whole.
Infraspecific ranks such as formas, subvarieties, cultivars, etc are not included in the Red List.
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by taxa:
rl_class(),
rl_family(),
rl_kingdom(),
rl_order(),
rl_phylum(),
rl_sis(),
rl_sis_latest(),
rl_species()
Examples
## Not run:
# Get latest assessment for species
ex1 <- rl_species_latest(genus = "Fratercula", species = "arctica")
ex1$stresses
# Get latest assessment for subspecies
ex2 <- rl_species_latest(genus = "Gorilla", species = "gorilla",
infra = "gorilla")
ex2$stresses
## End(Not run)
Stress assessment summary
Description
Return a list of the latest assessments based on the stresses species are subject to (e.g., Ecosystem degradation, species disturbance, etc.).
Usage
rl_stresses(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_stresses_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the stress to look up. If not supplied, a list of all stresses will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by threat details:
rl_categories(),
rl_pop_trends(),
rl_threats(),
rl_use_and_trade()
Examples
## Not run:
# Get all stresses
rl_stresses()
# Get assessment summary for ecosystem degradation stress
rl_stresses("1_2")
## End(Not run)
Get species synonym information by taxonomic name
Description
This function is fully deprecated in favor of
rl_species_latest()$taxon$synonyms as of rredlist version 1.0.0.
System assessment summary
Description
Return the latest assessments for a given system (e.g., terrestrial, freshwater or marine).
Usage
rl_systems(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_systems_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the system to look up. If not supplied, a list of all systems will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by habitats and systems:
rl_habitats()
Examples
## Not run:
# Get list of all systems
rl_systems()
# Get assessment summary for marine system
rl_systems("2")
## End(Not run)
Threat assessment summary
Description
Return a list of the latest assessments which are subject to a specific threat (e.g., energy production and mining, climate change, and severe weather). This will only return assessments for the threat code specified. You will need to do additional requests for sub-threats (e.g., a request for threat code 2_1 will need additional requests for codes 2_1_1, 2_1_2, etc.).
Usage
rl_threats(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_threats_(code = NULL, key = NULL, all = TRUE, page = 1, quiet = FALSE, ...)
Arguments
code |
(character) The code of the threat to look up. If not supplied, a list of all threats will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by threat details:
rl_categories(),
rl_pop_trends(),
rl_stresses(),
rl_use_and_trade()
Examples
## Not run:
# Get all threats
rl_threats()
# Get assessment summary for intentional hunting and trapping
rl_threats("5_1_1")
## End(Not run)
Use and trade assessment summary
Description
Return a list of the latest assessments which are subject to a specific use and trade.
Usage
rl_use_and_trade(
code = NULL,
key = NULL,
parse = TRUE,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
rl_use_and_trade_(
code = NULL,
key = NULL,
all = TRUE,
page = 1,
quiet = FALSE,
...
)
Arguments
code |
(character) The code of the use and trade to look up. If not supplied, a list of all uses and trades will be returned. |
key |
(character) An IUCN API token. See |
parse |
(logical) Whether to parse the output to list ( |
all |
(logical) Whether to retrieve all results at once or not. If
|
page |
(integer/numeric) Page to get if |
quiet |
(logical) Whether to suppress progress for multi-page downloads
or not. Default: |
... |
Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):
Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):
Also supports any curl options passed to the GET request via HttpClient. |
Value
A list unless using a function with a trailing underscore, in which case json as character string is returned.
References
API docs at https://api.iucnredlist.org/.
See Also
Assessments by threat details:
rl_categories(),
rl_pop_trends(),
rl_stresses(),
rl_threats()
Examples
## Not run:
# Get all stresses
rl_use_and_trade()
# Get assessment summary for medicinal use and trade
rl_use_and_trade("3")
## End(Not run)
Helper to get and save IUCN API key
Description
Provides instruction on how to get and store a key for the IUCN
API. Users of rredlist must do this before using any of the package's
other functionality. Note that registering for a key requires an email
address and information about your organization.
Usage
rl_use_iucn()
Details
Note that after filling the online form, you should receive an API key shortly but not immediately.
Value
Invisibly returns the sign-up URL for the IUCN Red List API.
Examples
## Not run:
# Sign up for an API key
rl_use_iucn()
## End(Not run)
Get the Red List version
Description
Returns the current version number of the IUCN Red List of Threatened Species
Usage
rl_version(key = NULL, ...)
Arguments
key |
(character) An IUCN API token. See |
... |
Curl options passed to HttpClient. |
Value
Red List version as character string.
See Also
Red List information and statistics:
rl_api_version(),
rl_citation(),
rl_sp_count()
Examples
## Not run:
rl_version()
## End(Not run)
IUCN Red List color scales
Description
ggplot2 color scales using the colors for the IUCN Red List threat categories, as documented in this chart.
Usage
scale_color_iucn(...)
scale_fill_iucn(...)
scale_discrete_iucn(aesthetics, ...)
Arguments
... |
Arguments passed on to ggplot2::discrete_scale (except for
|
aesthetics |
Character string or vector of character strings listing the
name(s) of the aesthetic(s) that this scale works with. This can be useful,
for example, to apply color settings to the |
Examples
library(ggplot2)
categories <- c("NE", "DD", "LC", "NT", "VU", "EN", "CR", "RE", "EW", "EX")
df <- data.frame(
x = runif(1000, 0, 10), y = runif(1000, 0, 10),
color = sample(categories, 1000, TRUE), shape = 21
)
ggplot(df) +
geom_point(aes(x = x, y = y, fill = color), shape = 21) +
scale_fill_iucn(name = "IUCN Category") +
theme_classic()