IUCNRedListRb

The International Union for Conservation of Nature’s Red List of Threatened Species has evolved to become the world’s most comprehensive information source on the global conservation status of animal, fungi and plant species. It’s a critical indicator of the health of the world’s biodiversity.

The IUCN Red List API has been developed to inform and drive biodiversity conservation and policy change -— critical steps in protecting essential natural resources. It provides programmatic access to data including (but limited to); population size, habitat and ecology, trade and threats to help support informed conservation decisions.

The iucnredlist Ruby Gem aims to serve as a client library for the Red List API, offering the research community and other users an efficient and user-friendly tool to access and interact with the vital data and services provided by the IUCN Red List.

We have open sourced this Gem to promote transparency, enable research community contributions, and drive adoption of the API. As an official IUCN-supported library, we shall maintain synchronisation with any API changes and updates.

The use of the API falls under the same Terms of Use as the Red List. By requesting a token, you are agreeing to abide by the Terms of Use of the Red List. If your token usage is found to be in breach of our terms of use, it will be revoked. We kindly request your cooperation in ensuring responsible and respectful usage of our services.

Please be aware that misusing your API token, such as using it for information extraction (scraping) rather than making legitimate requests for non-commercial purposes, may result in your token being rate limited and/or revoked.

We are committed to maintaining a high-quality service for all users and have implemented a rate limiting system to ensure our resources are accessible equally to all. We actively monitor API usage to prevent abuse. We understand that some users may have unique requirements for making frequent calls in succession. If you find yourself in such a situation, we kindly request that you incorporate appropriate delays between your API calls to ensure smooth operation and prevent overloading our system, otherwise your token may be further rate-limited. It’s important to note that the Red List API is primarily designed to support conservation efforts, particularly in the fields of education and research. We may need to restrict access if the API is being used for purposes that do not align with our mission, such as mobile app development, inclusion in computing courses, or visualization projects unrelated to conservation.

Use of the Red List API for commercial purposes is strictly forbidden. Users who wish to use Red List data for commercial purposes should consider subscribing to IBAT.

We are committed to ensuring fast and reliable access for all users of this API. To this end, we have implemented rate limiting to maintain service reliability for all users. Several functions within this package have an argument called wait_time - we recommend setting this to >=0.5 seconds (default 0.5 seconds) to avoid rate limiting. If you build your own functions from this package, we recommend you implement an appropriate wait time in your code to avoid any such limits.

Install the gem and add to the application's Gemfile by executing:

$ bundle add iucnredlistrb

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install iucnredlistrb

The IUCNRedListRb Gem contains a number of functions to allow quick access to Red List data. The examples below are some quick-start scripts to get you familiar with a basic workflow.

Before running this code, you must first sign up to the Red List API to obtain an API token. You can view (and cycle) your token from your account page.

Please also familiarise yourself with the Red List API Documentation

To start interacting with the IUCN Red List API, first, initialize a Client instance:

client = IUCNRedListRb::Client.new(api_key: 'YOUR_IUCN_RED_LIST_API_KEY')

To get data for a given assessment

# Returns assessment data for the Black Rhino
# https://www.iucnredlist.org/species/6557/152728945
assessment = client.assessment.find(152728945)
assessment

To retrieve a list of all Biogeographical Realms

response = client.biogeographical_realms.list
response

To retrieve a list of all assessments for a given Biogeographical Realm

# e.g. all assessments with an Afrotropical (code "0") biogeographical realm
response = client.biogeographical_realms.all(0)
response

To retrieve a list of all assessments for a given Biogeographical Realm with some additional filtering (this also aplies to the "all" method on every endpoint below)

# e.g. all latest and Global assessments with an Afrotropical (code "0") biogeographical realm
response = client.biogeographical_realms.all(0, { latest: true, scope: 1 })
response

You can also include a progress bar and wait time (this also aplies to the "all" method on every endpoint below)

response = client.biogeographical_realms.all(0, { latest: true, scope: 1 }, show_progress: true, wait_time: 0.8 )
response

To retrieve a list of all Comprehensive Groups

response = client.comprehensive_groups.list
response

To retrieve a list of all assessments for a given Comprehensive Group

# e.g. all assessments belonging to an Amphibian (code "amphibians") Comprehensive Group
response = client.comprehensive_groups.all("amphibians")
response

To retrieve a list of all assessments for a given Comprehensive Group with some additional filtering

# e.g. all assessments belonging to an Amphibian (code "amphibians") Comprehensive Group
response = client.comprehensive_groups.all("amphibians", { latest: true, scope: 1 })
response

To retrieve a list of all Conservation Actions

response = client.conservation_actions.list
response

To retrieve a list of all assessments for a given Conservation Action

# e.g. all assessments belonging to an "Land/water protection" Conservation Action
response = client.conservation_actions.all(1)
response

To retrieve a list of all assessments for a given Conservation Action with some additional filtering

# e.g. all assessments belonging to an "Land/water protection" Conservation Action
response = client.conservation_actions.all(1, { latest: true, scope: 1 })
response

To retrieve a list of all Countries

response = client.countries.list
response

To retrieve a list of all assessments for a given Country

# e.g. all assessments belonging to Andorra ("AD")
response = client.countries.all("AD")
response

To retrieve a list of all assessments for a given Country with some additional filtering

# e.g. all assessments belonging to Andorra ("AD")
response = client.countries.all("AD", { latest: true, scope: 1 })
response

To retrieve a list of all FAOs

response = client.faos.list
response

To retrieve a list of all assessments for a given FAO

# e.g. all assessments belonging to the Arctic Sea (18) FAO
response = client.faos.all(18)
response

To retrieve a list of all assessments for a given FAO with some additional filtering

# e.g. all latest Global assessments belonging to the Arctic Sea (18) FAO
response = client.faos.all(18, { latest: true, scope: 1 })
response

To retrieve a list of all Growth Forms

response = client.growth_forms.list
response

To retrieve a list of all assessments for a given Growth Form

# e.g. all assessments belonging to the Annual (A) Growth Form
response = client.growth_forms.all('A')
response

To retrieve a list of all assessments for a given Growth Form with some additional filtering

# e.g. all latest Global assessments belonging to the Annual (A) Growth Form
response = client.growth_forms.all('A', { latest: true, scope: 1 })
response

To retrieve a list of all Habitats

response = client.habitats.list
response

To retrieve a list of all Population Trends

response = client.population_trends.list
response

To retrieve a list of all Red List Categories

response = client.red_list_categories.list
response

To retrieve a list of all Research

response = client.research.list
response

To retrieve a list of all Scopes

response = client.scopes.list
response

To retrieve a list of all Stresses

response = client.stresses.list
response

To retrieve a list of all Systems

response = client.systems.list
response

To retrieve a list of all Threats

response = client.threats.list
response

To retrieve a list of all Use and Trade

response = client.use_and_trade.list
response

To retrieve a list of all Kingdoms

response = client.taxa.kingdom.list
response

To retrieve a list of assessments for a given Kingdom

response = client.taxa.kingdom.all('FUNGI')
response

To retrieve a list of all Phyla

response = client.taxa.phylum.list
response

To retrieve a list of assessments for a given Phylum

response = client.taxa.phylum.all('ANNELIDA')
response

To retrieve a list of all Classes

response = client.taxa.class.list
response

To retrieve a list of assessments for a given Class

response = client.taxa.class.all('ACTINOPTERYGII')
response

To retrieve a list of all Orders

response = client.taxa.order.list
response

To retrieve a list of assessments for a given Order

response = client.taxa.order.all('ACORALES')
response

To retrieve a list of all Families

response = client.taxa.family.list
response

To retrieve a list of assessments for a given Family

response = client.taxa.family.all('ACANTHACEAE')
response

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/IUCN-UK/iucnredlistrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Iucnredlistrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.