AnnotationController

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

Bases: BaseController

Controller for Annotation and ControlledTerm requests

Methods

__init__(*args, **kwargs)
all(**params)

List controlled terms and their possible values

Notes

Example

>>> terms = client.annotations
>>> pprint(response[0])
1: Life Stage
    2: Adult
    3: Teneral
    4: Pupa
...
Return type:

List[ControlledTerm]

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

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 controlled terms that are valid for the specified taxon.

Notes

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)

Get records by ID

Return type:

Paginator

lookup(annotations)

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