TaxonController#

class pyinaturalist.controllers.TaxonController(client)#

Bases: BaseController

Controller for Taxon requests

Methods

__call__(taxon_id, **kwargs)#

Get a single taxon by ID

Return type:

Optional[Taxon]

__init__(client)#
autocomplete(**params)#

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

Notes

  • API reference: GET /taxa/autocomplete

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

Parameters:

  • q – Name must begin with this value

  • is_active – Taxon is active

  • taxon_id – Only show taxa with this ID, or its descendants

  • rank – Taxon must have this exact rank

  • min_rank – Taxon must have this rank or higher; overrides rank

  • max_rank – Taxon must have this rank or lower; overrides rank

  • rank_level – 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 – 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]

from_ids(*taxon_ids, **params)#

Get taxa by ID

Parameters:

taxon_ids (int) – One or more taxon IDs

Return type:

Paginator[Taxon]

populate(taxon, **params)#

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(**params)#

Search taxa

Notes

Parameters:

  • q – Name must begin with this value

  • is_active – Taxon is active

  • taxon_id – Only show taxa with this ID, or its descendants

  • rank – Taxon must have this exact rank

  • min_rank – Taxon must have this rank or higher; overrides rank

  • max_rank – Taxon must have this rank or lower; overrides rank

  • rank_level – 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 – 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

  • id_above – Must have an ID above this value

  • id_below – Must have an ID below this value

  • only_id – Return only the record IDs

  • parent_id – Taxon’s parent must have this ID unless otherwise noted

  • order_by – Field to sort on

  • reverse – Reverse the order of results; alias for order='descending'

Return type:

Paginator[Taxon]