Taxon

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

Bases: 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
uuid	str	Unversally unique record ID
ancestry	str	Slash-delimited string of ancestor IDs
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=highest)
reference_url	str	Reference URL for the taxonomy source
ranges	bool	Indicates if there is range data for this taxon
rank	str	Taxon rank Options: infrahybrid, form, variety, subspecies, hybrid, species, complex, subsection, section, subgenus, genushybrid, genus, subtribe, tribe, supertribe, subfamily, family, epifamily, superfamily, zoosubsection, zoosection, parvorder, infraorder, suborder, order, superorder, subterclass, 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
kingdom (property)	Optional[Taxon]
phylum (property)	Optional[Taxon]
class_ (property)	Optional[Taxon]
order (property)	Optional[Taxon]
family (property)	Optional[Taxon]
genus (property)	Optional[Taxon]
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, and common name (if available)
rich_full_name (property)	str	Taxon full name, with italicized scientific name depending on rank (genus and below)
icon (property)	IconPhoto
icon_url (property)	str	Iconic URL for the icon of the iconic taxon
indent_level (property)	int	Tree indentation level. This may either be manually set, or determined based on rank.
gbif_url (property)	str	URL for the GBIF info page for this taxon
parent (property)	Optional[Taxon]	Immediate parent, if any
taxonomy (property)	Dict[str, str]	Ancestor + current taxon as a {rank: name} dict
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, uuid=None, ancestry=None, ancestor_ids=_Nothing.NOTHING, complete_rank=None, complete_species_count=None, created_at=None, current_synonymous_taxon_ids=_Nothing.NOTHING, extinct=None, gbif_id=None, iconic_taxon_id=0, iconic_taxon_name=None, is_active=None, listed_places=None, listed_taxa_count=None, matched_term=None, name=None, names=_Nothing.NOTHING, observations_count=None, parent_id=None, preferred_common_name='', preferred_establishment_means=None, rank_level=None, reference_url=None, ranges=None, rank=None, taxon_changes_count=None, taxon_schemes_count=None, vision=None, wikipedia_summary=None, wikipedia_url=None, artificial=False, partial=False, indent_level=None, ancestors=_Nothing.NOTHING, children=_Nothing.NOTHING, conservation_status=None, conservation_statuses=_Nothing.NOTHING, default_photo=None, establishment_means=None, listed_taxa=_Nothing.NOTHING, taxon_photos=_Nothing.NOTHING)

Method generated by attrs for class Taxon.

classmethod copy(obj)

Copy a model object. This is defined as a classmethod to easily initialize a subclass from a parent class instance. For copying an instance to the same type, copy.deepcopy() can be used.

Return type:

BaseModel

flatten(hide_root=False)

Return this taxon and all its descendants as a flat list. Taxon.indent_level is set to indicate the tree depth of each taxon.

Parameters:

hide_root (bool) – Exclude the current taxon from the list if it was automatically inserted by make_tree()

Return type:

List[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, **kwargs)

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, **kwargs)

Sort Taxon objects by rank then by name

Return type:

List[Taxon]

to_dict(keys=None, recurse=True)

Convert this object back to dict format

Parameters:

• keys (Optional[List[str]]) – Only keep the specified keys (attribute names)

• recurse (bool) – Recurse into nested model objects

Return type:

Dict[str, Any]