iucn-red-list

IUCN Red List

IUCN Red List API wrapper for Node.js

This project uses modern ES2016+ syntax, which means you can use promises (as shown in the documentation) or async/await.

Installation

npm install --save iucn-red-list

Usage

import {
  Country,
  GrowthForms,
  Habitat,
  Measure,
  Region,
  Species,
  Threat,
} from 'iucn-red-list';

Only import the modules you need. For example, if you only need the Country and Threat modules:

import {
  Country,
  Threat,
} from 'iucn-red-list';

To set your API Key, set the environment variable RED_LIST_TOKEN. Alternatively, you can set the configuration manually:

import { setRedListToken } from 'iucn-red-list';
setRedListToken('<your-token>')

Checking the Red List version

To check what version of the IUCN Red List is driving the API:

import { redListVersion } from 'iucn-red-list';
redListVersion().then(data => console.log(data));

Be sure to reference the Red List API docs

Country - Country information

• Country.all()
• Country.species()

Growth Forms - Plant growth form information

• GrowthForms.fetch()

Habitat - Species habitat information

• Habitat.fetch()

Measure - Species conservation measures information

• Measure.fetch()

Region - Region information

• Region.all()

Species - Published species on the Red List

• Species.fetch()
• Species.count()
• Species.citation()
• Species.byCategory()
• Species.find()
• Species.narrative()
• Species.synonym()
• Species.commonNames()
• Species.countries()
• Species.historical()

Threat - Species threat information

• Threat.fetch()

Country.all()

Retrieves a list of countries

Country
  .all()
  .then(data => console.log(data))
  .catch(err => console.log(err));

Country.species(options)

Retrieves a list of species by country

options (required) - [Object]

• country (required) - [String] ISO-code of the country for which you want the list of species

Country
  .species({ country: 'AZ' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

GrowthForm.fetch(options)

Retrieves a list of plant growth forms by species

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region (optional) - [String] If provided, this option will return a regional assessment of the growth forms. Must be a valid region (see Region.all())

GrowthForms
  .fetch({ name: 'Quercus robur', region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Habitat.fetch(options)

Retrieves a list of habitats by species

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region (optional) - [String] If provided, this option will return a regional assessment of the habitats. Must be a valid region (see Region.all())

Habitat
  .fetch({ name: 'Ursus maritimus', region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Measure.fetch(options)

Retrieves a list of conservation measures by species

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region (optional) - [String] If provided, this option will return a regional assessment of the measures. Must be a valid region (see Region.all())

Measure
  .fetch({ name: 'Ursus maritimus', region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Region.all()

Retrieves a list of regions

Region
  .all()
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.fetch(options)

Retrieves a list of species in a paginated list of 10,000 species per page.

options (required) - [Object]

• page (required) - [Number] Page number to retrieve. First page is 0
• region (optional) - [String] If provided, this option will return a regional assessment of the available species. Must be a valid region (see Region.all())

Species
  .fetch({ page: 2, region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.count(options)

Retrieves a count of species globally or by region.

options (required) - [Object]

• region - [String] Region to filter species count by. Must be a valid region (see Region.all())

Species
  .count({ region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.citation(options)

Retrieves a citation for a given species

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region - [String] If provided, this option will return a regional assessment of the species. Must be a valid region (see Region.all())

Species
  .citation({ name: 'Loxodonta Africana' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.byCategory(options)

Retrieves a list of species by category

options (required) - [Object]

• category (required) - [String] Valid categories are DD, LC, NT, VU, EN, CR, EW, EX, LR/lc, LR/nt, LR/cd.

Species
  .category({ category: 'VU' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.find(options)

Retrieve information about a specific species

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region - [String] If provided, this option will return a regional assessment of the species. Must be a valid region (see Region.all())

Species
  .find({ id: '22694927' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.narrative(options)

Retrieve narrative information about a specific species

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region - [String] If provided, this option will return a regional assessment of the species. Must be a valid region (see Region.all())

Species
  .narrative({ name: 'Fratercula artica', region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.synonym(options)

Retrieve information about synonyms via an accepted species name, or vice versa i.e. this call tells you if there are synonyms for the species name, or whether it's a synonym of an accepted name

options (required) - [Object]

• name (required) - [String] Name (or synonym) of species.

Species
  .synonym({ name: 'Loxodonta Africana' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.commonNames(options)

Retrieve list of common names in various languages for a species

options (required) - [Object]

• name (required) - [String] Name of species.

Species
  .commonNames({ name: 'Loxodonta Africana' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.countries(options)

Retrieve a list of countries of occurrence by species name

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region - [String] If provided, this option will return a regional assessment of the species. Must be a valid region (see Region.all())

Species
  .narrative({ name: 'Ursus maritimus', region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.historical(options)

Retrieve a list of historical assessments by species name (including the current listing)

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region - [String] If provided, this option will return a regional assessment of the species. Must be a valid region (see Region.all())

Species
  .narrative({ name: 'Ursus maritimus', region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Species.synonym(options)

Retrieve a direct link to the species page on the Red List website

options (required) - [Object]

• name (required) - [String] Name (or synonym) of species.

Species
  .link({ name: 'Loxodonta Africana' })
  .then(data => console.log(data))
  .catch(err => console.log(err));

Threat.fetch(options)

Retrieves a list of threats by species

options (required) - [Object]

• name (required) - [String] Name of species. If name is not provided, id must be provided
• id (required) - [String/Number] ID of species. If id is not provided, name must be provided. If both id and name are provided, id will take precedent and name will be ignored
• region (optional) - [String] If provided, this option will return a regional assessment of the threats. Must be a valid region (see Region.all())

Threat
  .fetch({ name: 'Fratercula arctica', region: 'europe' })
  .then(data => console.log(data))
  .catch(err => console.log(err));