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 provides access to the Catalogue of Life API, which is an authoritative and comprehensive global species database maintained by taxonomists worldwide. Specifically, for the Name Usage Search resource with the Get operation, this node allows users to perform detailed searches for taxonomic name usages based on a query string and various filtering options.

This node is beneficial in scenarios where you need to:

  • Search for scientific names or authorship information within a large taxonomic dataset.
  • Filter search results by taxonomic rank, status, or other facets.
  • Retrieve paginated and sorted lists of name usages matching specific criteria.
  • Enable fuzzy searching to handle approximate matches.

Practical examples include:

  • Finding all species names that match a partial or exact scientific name.
  • Searching for taxonomic usages authored by a particular author or within a certain rank range.
  • Retrieving name usage data filtered by status (e.g., accepted names only).
  • Using facets to refine search results by dataset keys, nomenclatural codes, or other metadata.

Properties

Name Meaning
Query (q) The search query string used to find matching name usages.
Content The type of content to search: either "Authorship" or "Scientific Name".
Facet One or more search facets to filter or categorize results. Options include Alpha Index, Authorship, Authorship Year, Catalogue Key, Dataset Key, Decision Mode, Environment, Extinct, Field, Issue, Name ID, Name Type, Nomenclatural Code, Nomenclatural Status, Origin, Published In ID, Publisher Key, Rank, Sector Dataset Key, Sector Key, Status, Taxon ID, Unsafe, Usage ID.
Facet Limit Limits the number of facet values returned.
Fuzzy Enables fuzzy search to allow approximate matches rather than exact ones.
Minimum Rank Filters results to include only name usages at or above this taxonomic rank. A wide range of ranks are available, from Domain down to Subform and other fine-grained taxonomic levels.
Maximum Rank Filters results to include only name usages at or below this taxonomic rank. Same extensive list of ranks as Minimum Rank.
Status Filters name usages by their taxonomic status. Options: Accepted, Ambiguous Synonym, Misapplied Name, Provisionally Accepted, Synonym.
Rank Specifies the minimum rank for the search (similar to Minimum Rank).
Reverse If true, orders the results in reverse order.
Sort By Determines how results are sorted. Options: Name, Native, Relevance, Taxonomic.
Type The type of search to perform. Options: Exact, Prefix, Whole Words.
Offset The paging offset for result pagination.
Limit The maximum number of results to return (minimum 1). Default is 50.

Output

The output is a JSON array containing the search results from the Catalogue of Life API's name usage search endpoint. Each item in the array represents a name usage record matching the search criteria, including details such as scientific name, authorship, taxonomic rank, status, and other metadata depending on the facets and filters applied.

The node does not output binary data; all data is structured JSON representing taxonomic name usage information.

Dependencies

  • The node requires internet access to call the Catalogue of Life API at https://api.checklistbank.org/dataset/3LR.
  • No explicit API key or authentication is required according to the code.
  • The node uses standard HTTP GET requests with JSON responses.
  • No additional n8n credentials or environment variables are needed for this resource-operation.

Troubleshooting

  • Empty Results: If the query returns no results, verify that the search query (q) is correctly specified and that filters like rank or status are not overly restrictive.
  • Invalid Parameter Values: Ensure that options like rank, status, and facets use valid values as per the provided options. Invalid values may cause the API to reject the request or return errors.
  • API Unreachable: Network issues or changes in the API endpoint URL could cause failures. Confirm network connectivity and that the base URL https://api.checklistbank.org/dataset/3LR is accessible.
  • Pagination Issues: If expecting many results, ensure that limit and offset parameters are set appropriately to paginate through all data.
  • Fuzzy Search Not Working: If enabling fuzzy search yields unexpected results, try disabling it or adjusting the query for better matches.

Common error messages would likely come from the HTTP request helper and reflect HTTP status codes or JSON parsing errors. These can be resolved by checking parameter correctness and network availability.

Links and References

If you need further details on other resources or operations, feel free to ask!

Discussion