CatalogueOfLife icon

CatalogueOfLife

The most complete authoritative list of the world's species, maintained by hundreds of global taxonomists
Join our community

Actions12

  • Decision Actions
  • Estimate Actions
  • Name Actions
  • Name Usage Actions
  • Name Usage Search Actions
  • Name Usage Suggest Actions
  • Reference Actions
  • Source Metadata Actions
  • Synonym Actions
  • Taxon Actions
  • Tree Actions
  • Vernacular Actions

Overview

The node interacts with the Catalogue of Life API, which provides a comprehensive and authoritative list of the world's species maintained by global taxonomists. Specifically, for the Tree resource with the Get operation, this node fetches taxonomic tree data starting from a specified root taxon ID. It can retrieve hierarchical information about taxa, including children taxa, counts by taxonomic rank, extinct taxa inclusion, and placeholders for missing names.

This node is beneficial in scenarios where users need to explore or analyze biological classification trees, such as:

  • Visualizing the taxonomic hierarchy of a particular species or group.
  • Counting taxa at specific ranks within a subtree.
  • Including extinct species in biodiversity studies.
  • Handling incomplete taxonomic data gracefully with placeholders.

Practical example: A researcher wants to get the full taxonomic tree under a certain genus, including all children taxa and count how many species exist at each family level, optionally including extinct species.

Properties

Name Meaning
Children Boolean flag to include children taxa for the specified taxon ID. If true, the response will contain child nodes in the taxonomic tree.
Count By The taxonomic rank used to count taxa in the tree. Options include a wide range of ranks from Domain down to various infraspecific levels (e.g., Kingdom, Phylum, Class, Order, Family, Genus, Species, Variety, etc.).
Include Extinct Boolean flag to include extinct taxa in the results. When true, extinct species are part of the returned tree.
Include Placeholder Boolean flag to insert a placeholder named Not assigned when a name does not exist at a given rank. This helps handle missing data in the taxonomic hierarchy.
Type Specifies the type of tree data to retrieve. Options are "Catalogue" or "Source", indicating different dataset sources or views.
ID The root taxon ID from which to start retrieving the tree. This is a string identifier representing the taxon node at the root of the requested subtree.

Output

The output is a JSON array containing the taxonomic tree data retrieved from the Catalogue of Life API. The structure includes:

  • Taxon nodes with their properties such as scientific names, taxonomic ranks, and IDs.
  • If Children is enabled, child taxa are nested within parent taxa.
  • Counts of taxa aggregated by the selected rank (Count By).
  • Flags or fields indicating extinct status if included.
  • Placeholders for missing names if Include Placeholder is set.

The exact JSON structure follows the API's taxonomic tree format, typically including nested objects representing the hierarchy.

No binary data output is produced by this node.

Dependencies

  • Requires internet access to call the Catalogue of Life public API endpoint at https://api.checklistbank.org/dataset/3LR.
  • No special credentials or API keys are required as per the provided code.
  • The node uses standard HTTP GET requests with JSON responses.

Troubleshooting

  • Common issues:

    • Invalid or empty root ID (ID property) may result in no data or errors.
    • Requesting children for a taxon that has none will return minimal or empty child arrays.
    • Using unsupported or misspelled taxon ranks in Count By may cause unexpected results or API errors.
    • Network connectivity problems will prevent API calls from succeeding.

  • Error messages:

    • HTTP errors (e.g., 404 Not Found) if the root ID does not exist.
    • API rate limiting or downtime could cause request failures.

  • Resolutions:

    • Verify the root taxon ID is correct and exists in the Catalogue of Life.
    • Use valid options for Count By and other parameters.
    • Ensure stable internet connection.
    • Retry after some time if API rate limits are hit.

Links and References

Discussion