TaxonController

class pyinaturalist.controllers.TaxonController(client)

Bases: BaseController

Controller for Taxon requests

Methods

__call__(taxon_id, **kwargs) → Taxon | None

Get a single taxon by ID

Example

>>> client.taxa(343248)
Parameters:

  • taxon_id (int) – A single taxon ID

  • locale – Locale preference for taxon common names

  • preferred_place_id – Place preference for regional taxon common names

  • all_names – Include all taxon names in the response

Return type:

Taxon | None

__init__(client)
autocomplete(q, is_active, taxon_id, rank, max_rank, min_rank, ...) → Paginator[Taxon]

Given a query string, return taxa with names starting with the search term

Notes

  • Paginated endpoint

  • API reference: GET /taxa/autocomplete

  • There appears to currently be a bug in the API that causes per_page to not have any effect.

  • exact_match is a best effort to get an exact match on common name. Due to lack of standardization and uniqueness in common names, though, multiple results are still likely. Results are sorted by observation count, so the first result is more likely to be what you’re looking for. Filtering by rank will further increase your chances.

Parameters:

  • full_records – Fetch full taxon records by ID for each autocomplete match

  • exact_match – Filter results to only taxa whose common name or matched term exactly matches q (case-insensitive).

  • q (str | None) – Name must begin with this value

  • is_active (bool | None) – Taxon is active

  • taxon_id (int | None) – Only show taxa with this ID, or its descendants

  • rank (str | None) – Taxon must have this exact rank

  • min_rank (str | None) – Taxon must have this rank or higher; overrides rank

  • max_rank (str | None) – Taxon must have this rank or lower; overrides rank

  • rank_level (int | None) – Taxon must have this rank level. Some example values are 70 (kingdom), 60 (phylum), 50 (class), 40 (order), 30 (family), 20 (genus), 10 (species), 5 (subspecies)

  • locale (str | None) – Locale preference for taxon common names

  • preferred_place_id (int | None) – Place preference for regional taxon common names

  • all_names (bool | None) – Include all taxon names in the response

Return type:

Paginator[Taxon]

Examples

Get all matches:

>>> taxa = client.taxa.autocomplete(q='vespi').all()

Search for only exact matches that are species, and get the first result:

>>> best_guess = client.taxa.autocomplete(q='raven', exact_match=True, rank='species').one()
>>> print(best_guess)
"Taxon(id=8010, full_name=Corvus corax (Common Raven))"

Verify the term that was matched (if different from preferred_common_name):

>>> print(best_guess.matched_term)
"Raven"
from_ids(taxon_ids, **params) → Paginator[Taxon]

Get one or more taxa by ID

Notes

Example

>>> client.get_taxa_by_id([3, 343248])
Parameters:

  • taxon_ids (int | Iterable[int]) – One or more taxon IDs

  • locale – Locale preference for taxon common names

  • preferred_place_id – Place preference for regional taxon common names

  • all_names – Include all taxon names in the response

Return type:

Paginator[Taxon]

populate(taxon, **params) → Taxon

Update a partial Taxon record with full taxonomy info, including ancestors + children

Parameters:

taxon (Taxon) – A partial Taxon record

Return type:

Taxon

Returns:

The same Taxon record, updated with full taxonomy info

search(q, is_active, taxon_id, rank, max_rank, min_rank, ...) → Paginator[Taxon]

Search taxa

Notes

Parameters:

  • q (str | None) – Name must begin with this value

  • is_active (bool | None) – Taxon is active

  • taxon_id (int | None) – Only show taxa with this ID, or its descendants

  • rank (str | None) – Taxon must have this exact rank

  • min_rank (str | None) – Taxon must have this rank or higher; overrides rank

  • max_rank (str | None) – Taxon must have this rank or lower; overrides rank

  • rank_level (int | None) – Taxon must have this rank level. Some example values are 70 (kingdom), 60 (phylum), 50 (class), 40 (order), 30 (family), 20 (genus), 10 (species), 5 (subspecies)

  • locale (str | None) – Locale preference for taxon common names

  • preferred_place_id (int | None) – Place preference for regional taxon common names

  • all_names (bool | None) – Include all taxon names in the response

  • id_above (int | None) – Must have an ID above this value

  • id_below (int | None) – Must have an ID below this value

  • only_id (bool | None) – Return only the record IDs

  • parent_id (int | None) – Taxon’s parent must have this ID

Return type:

Paginator[Taxon]

Example

>>> client.taxa.search(q='vespi', rank=['genus', 'family'])