TaxonController#

class pyinaturalist.controllers.TaxonController(client)#

Bases: BaseController

Controller for Taxon requests

Methods

__call__(taxon_id, **kwargs)#

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:

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 (Optional[str]) – Name must begin with this value

  • is_active (Optional[bool]) – Taxon is active

  • taxon_id (Optional[int]) – Only show taxa with this ID, or its descendants

  • rank (Optional[str]) – Taxon must have this exact rank

  • min_rank (Optional[str]) – Taxon must have this rank or higher; overrides rank

  • max_rank (Optional[str]) – Taxon must have this rank or lower; overrides rank

  • rank_level (Optional[int]) – 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 (Optional[str]) – Locale preference for taxon common names

  • preferred_place_id (Optional[int]) – Place preference for regional taxon common names

  • all_names (Optional[bool]) – Include all taxon names in the response

Example

>>> client.taxa.autocomplete(q='vespi')
Return type:

Paginator[Taxon]

from_ids(taxon_ids, **params)#

Get one or more taxa by ID

Notes

Example

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

  • taxon_ids (Union[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)#

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 (Optional[str]) – Name must begin with this value

  • is_active (Optional[bool]) – Taxon is active

  • taxon_id (Optional[int]) – Only show taxa with this ID, or its descendants

  • rank (Optional[str]) – Taxon must have this exact rank

  • min_rank (Optional[str]) – Taxon must have this rank or higher; overrides rank

  • max_rank (Optional[str]) – Taxon must have this rank or lower; overrides rank

  • rank_level (Optional[int]) – 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 (Optional[str]) – Locale preference for taxon common names

  • preferred_place_id (Optional[int]) – Place preference for regional taxon common names

  • all_names (Optional[bool]) – Include all taxon names in the response

  • id_above (Optional[int]) – Must have an ID above this value

  • id_below (Optional[int]) – Must have an ID below this value

  • only_id (Optional[bool]) – Return only the record IDs

  • parent_id (Optional[int]) – Taxon’s parent must have this ID

Example

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

Paginator[Taxon]