Taxon

class pyinaturalist.models.Taxon(id=None, ancestor_ids=NOTHING, complete_rank=None, complete_species_count=None, created_at=None, current_synonymous_taxon_ids=NOTHING, extinct=None, gbif_id=None, iconic_taxon_id=0, iconic_taxon_name='unknown', is_active=None, listed_places=None, listed_taxa_count=None, matched_term=None, name=None, names=NOTHING, observations_count=None, parent_id=None, preferred_common_name='', preferred_establishment_means=None, rank_level=None, ranges=None, rank=None, taxon_changes_count=None, taxon_schemes_count=None, vision=None, wikipedia_summary=None, wikipedia_url=None, ancestors=NOTHING, children=NOTHING, conservation_status=None, conservation_statuses=NOTHING, default_photo=None, establishment_means=None, listed_taxa=NOTHING, taxon_photos=NOTHING)

Bases: pyinaturalist.models.base.BaseModel

An iNaturalist taxon, based on the schema of GET /taxa.

Can be constructed from either a full or partial JSON record. Examples of partial records include nested ancestors, children, and results from get_taxa_autocomplete().

Attributes

Name	Type	Description
id	int	Unique record ID
ancestor_ids	List[int]	Taxon IDs of ancestors, from highest rank to lowest
complete_rank	str	Complete or “leaf taxon” rank, e.g. species or subspecies
complete_species_count	int	Total number of species descended from this taxon
created_at	datetime	Date and time the taxon was added to iNaturalist
current_synonymous_taxon_ids	List[int]	Taxon IDs of taxa that are accepted synonyms
extinct	bool	Indicates if the taxon is extinct
gbif_id	int	GBIF taxon ID
iconic_taxon_id	int	ID of the iconic taxon (e.g., general taxon “category”)
iconic_taxon_name	str	Name of the iconic taxon (e.g., general taxon “category”)
is_active	bool	Indicates if the taxon is active (and not renamed, moved, etc.)
listed_places	bool	Indicates if there are listed places for this taxon
listed_taxa_count	int	Number of listed taxa from this taxon + descendants
matched_term	str	Matched search term, from autocomplete results
name	str	Taxon name; contains full scientific name at species level and below
names	List[Dict]	All regional common names; only returned if all_names is specified
observations_count	int	Total number of observations of this taxon and its descendants
parent_id	int	Taxon ID of immediate ancestor
preferred_common_name	str	Common name for the preferred place, if any
preferred_establishment_means	str	Establishment means for this taxon in the given preferred place (if any)
rank_level	int	Number indicating rank level, for easier comparison between ranks (kingdom=higest)
ranges	bool	Indicates if there is range data for this taxon
rank	str	Taxon rank Options: form, variety, subspecies, hybrid, species, genushybrid, subgenus, genus, subtribe, tribe, supertribe, subfamily, family, epifamily, superfamily, infraorder, suborder, order, superorder, infraclass, subclass, class, superclass, subphylum, phylum, kingdom
taxon_changes_count	int	Number of curator changes to this taxon
taxon_schemes_count	int	Taxon schemes that include this taxon
vision	bool	Indicates if this taxon is included in the computer vision model
wikipedia_summary	str	Taxon summary from Wikipedia article
wikipedia_url	str	URL to Wikipedia article for the taxon
ancestry (property)	str	String containing either ancestor names (if available) or IDs
child_ids (property)	List[int]	Taxon IDs of direct children, sorted by rank then name
emoji (property)	str	Get an emoji representing the taxon
full_name (property)	str	Taxon rank, scientific name, common name (if available), and emoji
icon_url (property)	str	URL for the iconic taxon’s icon
gbif_url (property)	str	URL for the GBIF info page for this taxon
parent (property)	Taxon	Immediate parent, if any
url (property)	str	Info URL on iNaturalist.org
ancestors (LazyProperty)	List[Taxon]	Ancestor taxa, from highest rank to lowest
children (LazyProperty)	List[Taxon]	Child taxa, sorted by rank then name
conservation_status (LazyProperty)	ConservationStatus	Conservation status of the taxon in a given location
conservation_statuses (LazyProperty)	List[ConservationStatus]	Conservation statuses of the taxon in different locations
default_photo (LazyProperty)	Photo	Taxon default photo
establishment_means (LazyProperty)	EstablishmentMeans	Establishment means for a taxon in a given location
listed_taxa (LazyProperty)	List[ListedTaxon]	Details about this taxon associated with a list
taxon_photos (LazyProperty)	List[Photo]	All taxon photos shown on taxon info page

Methods

__init__(id=None, ancestor_ids=NOTHING, complete_rank=None, complete_species_count=None, created_at=None, current_synonymous_taxon_ids=NOTHING, extinct=None, gbif_id=None, iconic_taxon_id=0, iconic_taxon_name='unknown', is_active=None, listed_places=None, listed_taxa_count=None, matched_term=None, name=None, names=NOTHING, observations_count=None, parent_id=None, preferred_common_name='', preferred_establishment_means=None, rank_level=None, ranges=None, rank=None, taxon_changes_count=None, taxon_schemes_count=None, vision=None, wikipedia_summary=None, wikipedia_url=None, ancestors=NOTHING, children=NOTHING, conservation_status=None, conservation_statuses=NOTHING, default_photo=None, establishment_means=None, listed_taxa=NOTHING, taxon_photos=NOTHING)

Method generated by attrs for class Taxon.

classmethod from_id(id)

Lookup and create a new Taxon object by ID

Return type

Taxon

classmethod from_json(value, **kwargs)

Initialize a single model object from an API response or response result.

Omits any invalid fields and None values, so default factories are used instead (e.g. for empty dicts and lists).

Return type

TypeVar(T, bound= BaseModel)

classmethod from_json_file(value)

Initialize a collection of model objects from a JSON string, file path, or file-like object

Return type

List[TypeVar(T, bound= BaseModel)]

classmethod from_json_list(value)

Initialize a collection of model objects from an API response or response results

Return type

List[TypeVar(T, bound= BaseModel)]

classmethod from_sorted_json_list(value)

Sort Taxon objects by rank then by name

Return type

List[Taxon]

load_full_record()

Update this Taxon with full taxon info, including ancestors + children

to_json()

Convert this object back to JSON (dict) format

Return type

Dict[str, Any]