AnnotationController¶

class pyinaturalist.controllers.AnnotationController(*args, **kwargs)¶

Bases: BaseController

Controller for Annotation and ControlledTerm requests

Methods

__init__(*args, **kwargs)¶

all(**params) → List[ControlledTerm]¶

List controlled terms and their possible values

Return type:: List[ControlledTerm]

Notes

API reference: GET /controlled_terms

Example

>>> terms = client.annotations.all()
>>> pprint(terms)
 ID   Label          Values
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 1    Life Stage     Adult, Teneral, Pupa, ...
 17   Alive or Dead  Alive, Dead, Cannot Be Determined
 ...

create(controlled_attribute_id, controlled_value_id, resource_id, resource_type='Observation', **params) → Annotation¶

Create a new annotation on an observation.

Parameters:

controlled_attribute_id (int) – Annotation attribute ID
controlled_value_id (int) – Annotation value ID
resource_id (Union[int, str]) – Observation ID or UUID
resource_type (str) – Resource type, if something other than an observation

Example

Add a ‘Plant phenology: Flowering’ annotation to an observation (via IDs):

>>> client.annotations.create(12, 13, 164609837)

Return type:: Annotation
Returns:: The newly created Annotation object

delete(uuid, **params)¶

Delete an annotation

Parameters:: uuid (str) – Annotation UUID
Returns:: Nothing; success means the item has been deleted

for_taxon(taxon_id, **params) → List[ControlledTerm]¶

List controlled terms that are valid for the specified taxon.

Notes

API reference: GET /controlled_terms/for_taxon

Example

>>> client.annotations.for_taxon(12345)

Parameters:: taxon_id (int) – Taxon ID to get controlled terms for
Raises:: .TaxonNotFound – If an invalid taxon_id is specified
Return type:: List[ControlledTerm]

from_ids(*object_ids, **params) → Paginator¶

Get records by ID

Return type:: Paginator

lookup(annotations) → List[Annotation]¶

Fill in missing information for the specified annotations. If only term and value IDs are present, this will look up, cache, and add complete controlled term details.

Parameters:: annotations (List[Annotation]) – Observation annotations
Return type:: List[Annotation]
Returns:: Annotation objects with controlled_attribute and controlled_value populated