Observations

Summary

Classes

Functions

create_observation(access_token, ...)	Create a new observation.
delete_observation(access_token, dry_run, ...)	Delete an observation
get_observations(q, d1, d2, day, month, ...)	Search observations
set_observation_field(access_token, dry_run, ...)	Create or update an observation field value on an observation
update_observation(access_token, ...)	Update a single observation
upload(observation_uuid, photos, sounds, ...)	Upload one or more local photo and/or sound files, and add them to an existing observation.

Module Contents

pyinaturalist.v2.observations.create_observation(access_token, species_guess, taxon_id, observed_on, observed_on_string, time_zone, ...) → dict[str, Any]

Create a new observation.

Notes

• Requires authentication

• API reference: POST /observations

Parameters:

• access_token (str | None) – An access token for user authentication, as returned by get_access_token()

• species_guess (str | None) – Equivalent to the ‘What did you see?’ field on the observation form. iNat will try to choose a single taxon based on this, but it may fail if it’s ambiguous

• taxon_id (int | None) – ID of the taxon to associate with this observation

• observed_on (date | datetime | str | None) – Alias for observed_on_string; accepts datetime objects.

• observed_on_string (date | datetime | str | None) – Date/time of the observation. Time zone will default to the user’s time zone if not specified.

• time_zone (str | None) – Time zone the observation was made in

• description (str | None) – Observation description

• tag_list (str | Iterable[str] | None) – Comma-separated list of tags

• place_guess (str | None) – Name of the place where the observation was recorded. Note: iNat will not try to automatically look up coordinates based on this string

• latitude (float | None) – Latitude of the observation; presumed datum is WGS84

• longitude (float | None) – Longitude of the observation; presumed datum is WGS84

• map_scale (int | None) – Google Maps zoom level (from 0 to 19) at which to show this observation’s map marker.

• positional_accuracy (int | None) – Positional accuracy of the observation coordinates, in meters

• geoprivacy (Optional[Literal['obscured', 'obscured_private', 'open', 'private']]) – Geoprivacy for the observation

• observation_fields (dict | list[dict] | None) – Dict of observation fields in the format {id: value}. Alias for observation_field_values_attributes.

• photos (BinaryIO | Path | str | Iterable[BinaryIO | Path | str] | None) – One or more image files, file-like objects, file paths, or URLs

• sounds (BinaryIO | Path | str | Iterable[BinaryIO | Path | str] | None) – One or more sound files, file-like objects, file paths, or URLs

• photo_ids (int | Iterable[int] | str | Iterable[str] | None) – One or more IDs of previously uploaded photos to attach to the observation

• captive_flag (bool | None) – Mark observation as captive/cultivated

• coordinate_system (str | None) – Coordinate system used (if not WGS84)

• geo_x (float | None) – X coordinate in alternative coordinate system

• geo_y (float | None) – Y coordinate in alternative coordinate system

• license (str | None) – License to apply to the observation (e.g., ‘cc-by’, ‘cc-by-nc’, ‘cc0’)

• location_is_exact (bool | None) – Whether the location coordinates are exact

• make_license_default (bool | None) – Make this license the user’s default for future observations

• make_licenses_same (bool | None) – Apply the same license to all associated photos

• owners_identification_from_vision (bool | None) – Initial identification came from computer vision

• positioning_device (str | None) – Device used for positioning (e.g., ‘gps’, ‘cell’, ‘network’)

• positioning_method (str | None) – Method used to determine positioning

• prefers_community_taxon (bool | None) – User preference for using community taxon over their own identification

• project_id (int | None) – Project ID to add observation to upon creation

• site_id (int | None) – iNaturalist network site ID (e.g., for iNaturalist.ca, iNaturalist.nz)

• uuid (str | None) – UUID of the observation (for updates to preserve UUID)

• dry_run (bool | None) – Just log the request instead of sending a real request

• session (Session | None) – An existing Session object to use instead of creating a new one

Example

>>> token = get_access_token()
>>> # Create a new observation:
>>> create_observation(
...     access_token=token,
...     species_guess='Pieris rapae',
...     observed_on='2020-09-01',
...     photos='~/observation_photos/2020_09_01_14003156.jpg',
...     observation_fields={
...         297: 3,  # 297 is the obs. field ID for 'Number of individuals'
...         816: 1,  # 816 = 'Number of males'
...         821: 2,  # 821 = 'Number of females'
...     },
... )

Example Response

{
  "id": 54986584,
  "uuid": "3595235e-96b1-450f-92ec-49162721cc6f",
  "species_guess": "Pieris rapae",
  "observed_on": "2021-07-30T19:10:32.323-05:00"
}

Return type:

dict[str, Any]

Returns:

JSON response containing the newly created observation (submitted fields only)

pyinaturalist.v2.observations.delete_observation(access_token, dry_run, session, **kwargs)

Delete an observation

Notes

• Requires authentication

• API reference: DELETE /observations/{uuid}

Parameters:

• observation_uuid – UUID of the observation to delete

• access_token (str | None) – An access token for user authentication, as returned by get_access_token()

• dry_run (bool | None) – Just log the request instead of sending a real request

• session (Session | None) –

  An existing Session object to use instead of creating a new one

Example

>>> token = get_access_token()
>>> delete_observation('53411fc2-bdf0-434e-afce-4dac33970173', token)

Returns:

If successful, no response is returned from this endpoint

Raises:

• .ObservationNotFound –

• requests.HTTPError –

pyinaturalist.v2.observations.get_observations(q, d1, d2, day, month, year, ...) → dict[str, Any]

Search observations

Notes

• Optional authentication For private/obscured coordinates and original filenames

• API reference: GET /observations

• See iNaturalist API v2 documentation for details on selecting return fields using fields parameter

Parameters:

• q (str | None) – Search observation properties

• d1 (date | datetime | str | None) – Must be observed on or after this date

• d2 (date | datetime | str | None) – Must be observed on or before this date

• day (int | Iterable[int] | None) – Must be observed within this day of the month

• month (int | Iterable[int] | None) – Must be observed within this month

• year (int | Iterable[int] | None) – Must be observed within this year

• license (Union[Literal['CC-BY', 'CC-BY-NC', 'CC-BY-ND', 'CC-BY-SA', 'CC-BY-NC-ND', 'CC-BY-NC-SA', 'CC0'], Iterable[Literal['CC-BY', 'CC-BY-NC', 'CC-BY-ND', 'CC-BY-SA', 'CC-BY-NC-ND', 'CC-BY-NC-SA', 'CC0']], None]) – Observation must have this license

• photo_license (Union[Literal['CC-BY', 'CC-BY-NC', 'CC-BY-ND', 'CC-BY-SA', 'CC-BY-NC-ND', 'CC-BY-NC-SA', 'CC0'], Iterable[Literal['CC-BY', 'CC-BY-NC', 'CC-BY-ND', 'CC-BY-SA', 'CC-BY-NC-ND', 'CC-BY-NC-SA', 'CC0']], None]) – Must have at least one photo with this license

• out_of_range (bool | None) – Observations whose taxa are outside their known ranges

• list_id (int | None) – Taxon must be in the list with this ID

• quality_grade (Union[Literal['casual', 'needs_id', 'research'], Iterable[Literal['casual', 'needs_id', 'research']], None]) – Must have this quality grade

• id (int | Iterable[int] | None) – Must have this observation ID

• taxon_id (int | Iterable[int] | None) – Only show observations of these taxa and their descendants

• taxon_name (str | Iterable[str] | None) – Taxon must have a scientific or common name matching this string

• iconic_taxa (Union[Literal['Unknown', 'Animalia', 'Aves', 'Amphibia', 'Reptilia', 'Mammalia', 'Actinopterygii', 'Mollusca', 'Arachnida', 'Insecta', 'Plantae', 'Fungi', 'Chromista', 'Protozoa'], Iterable[Literal['Unknown', 'Animalia', 'Aves', 'Amphibia', 'Reptilia', 'Mammalia', 'Actinopterygii', 'Mollusca', 'Arachnida', 'Insecta', 'Plantae', 'Fungi', 'Chromista', 'Protozoa']], None]) – Taxon must by within this iconic taxon

• updated_since (datetime | str | None) – Must be updated since this time

• acc (bool | None) – Whether or not positional accuracy / coordinate uncertainty has been specified

• captive (bool | None) – Captive or cultivated observations

• endemic (bool | None) – Observations whose taxa are endemic to their location

• geo (bool | None) – Observations that are georeferenced

• id_please (bool | None) – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.

• identified (bool | None) – Observations that have community identifications

• introduced (bool | None) – Observations whose taxa are introduced in their location

• mappable (bool | None) – Observations that show on map tiles

• native (bool | None) – Observations whose taxa are native to their location

• pcid (bool | None) – Observations identified by the curator of a project. If the project_id parameter is also specified, this will only consider observations identified by curators of the specified project(s)

• photos (bool | None) – Observations with photos

• popular (bool | None) – Observations that have been favorited by at least one user

• sounds (bool | None) – Observations with sounds

• taxon_is_active (bool | None) – Observations of active taxon concepts

• threatened (bool | None) – Observations whose taxa are threatened in their location

• verifiable (bool | None) – Observations with a quality_grade of either needs_id or research. Equivalent to quality_grade=needs_id,research

• not_id (int | Iterable[int] | None) – Must not have this ID

• place_id (int | Iterable[int] | None) – Must be observed within the place with this ID

• project_id (int | Iterable[int] | None) – Must be added to the project this ID or slug

• rank (str | Iterable[str] | None) – Taxon must have this rank

• site_id (str | Iterable[str] | None) – Must be affiliated with the iNaturalist network website with this ID

• observation_fields (list | dict | None) – Must have these observation fields (optionally with values)

• ofv_datatype (str | Iterable[str] | None) – Must have an observation field value with this datatype

• sound_license (Union[Literal['CC-BY', 'CC-BY-NC', 'CC-BY-ND', 'CC-BY-SA', 'CC-BY-NC-ND', 'CC-BY-NC-SA', 'CC0'], Iterable[Literal['CC-BY', 'CC-BY-NC', 'CC-BY-ND', 'CC-BY-SA', 'CC-BY-NC-ND', 'CC-BY-NC-SA', 'CC0']], None]) – Must have at least one sound with this license

• without_taxon_id (int | Iterable[int] | None) – Exclude observations of these taxa and their descendants

• user_id (int | Iterable[int] | str | Iterable[str] | None) – Observer must have this user ID or login

• user_login (str | Iterable[str] | None) – Observer must have this user login

• ident_user_id (int | Iterable[int] | str | Iterable[str] | None) – Identifier must have this user ID or login

• term_id (int | Iterable[int] | None) – Must have an annotation using this controlled term ID

• term_value_id (int | Iterable[int] | None) – Must have an annotation using this controlled value ID. Must be combined with the term_id parameter

• without_term_value_id (int | Iterable[int] | None) – Exclude observations with annotations using this controlled value ID. Must be combined with the term_id parameter

• acc_above (str | None) – Must have an positional accuracy above this value (meters)

• acc_below (str | None) – Must have an positional accuracy below this value (meters)

• acc_below_or_unknown (str | None) – Must have an positional accuracy below this value (meters) or unknown

• created_d1 (datetime | str | None) – Must be created at or after this time

• created_d2 (datetime | str | None) – Must be created at or before this time

• created_on (date | datetime | str | None) – Must be created on this date

• observed_on (date | datetime | str | None) – Must be observed on this date

• unobserved_by_user_id (int | None) – Must not be of a taxon previously observed by this user

• apply_project_rules_for (str | None) – Must match the rules of the project with this ID or slug

• cs (str | None) – Taxon must have this conservation status code. If the place_id parameter is also specified, this will only consider statuses specific to that place

• csa (str | None) – Taxon must have a conservation status from this authority. If the place_id parameter is also specified, this will only consider statuses specific to that place

• csi (Union[Literal['LC', 'NT', 'VU', 'EN', 'CR', 'EW', 'EX'], Iterable[Literal['LC', 'NT', 'VU', 'EN', 'CR', 'EW', 'EX']], None]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place

• geoprivacy (Union[Literal['obscured', 'obscured_private', 'open', 'private'], Iterable[Literal['obscured', 'obscured_private', 'open', 'private']], None]) – Must have this geoprivacy setting

• taxon_geoprivacy (Union[Literal['obscured', 'obscured_private', 'open', 'private'], Iterable[Literal['obscured', 'obscured_private', 'open', 'private']], None]) – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.

• hrank (str | None) – Taxon must have this rank or lower

• lrank (str | None) – Taxon must have this rank or higher

• id_above (int | None) – Must have an ID above this value

• id_below (int | None) – Must have an ID below this value

• identifications (Optional[Literal['most_agree', 'most_disagree', 'some_agree']]) – Identifications must meet these criteria

• lat (float | None) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)

• lng (float | None) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)

• radius (float | None) – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)

• not_in_project (int | str | None) – Must not be in the project with this ID or slug

• not_matching_project_rules_for (int | str | None) – Must not match the rules of the project with this ID or slug

• search_on (Union[Literal['names', 'tags', 'description', 'place'], Iterable[Literal['names', 'tags', 'description', 'place']], None]) – Properties to search on, when combined with q. Searches across all properties by default

• viewer_id (int | None) – See reviewed

• reviewed (bool | None) – Observations have been reviewed by the user with ID equal to the value of the viewer_id parameter

• locale (str | None) – Locale preference for taxon common names

• preferred_place_id (int | None) – Place preference for regional taxon common names

• ttl (str | None) – Set the Cache-Control HTTP header with this value as max-age, in seconds

• nelat (float | None) – NE latitude of bounding box

• nelng (float | None) – NE longitude of bounding box

• swlat (float | None) – SW latitude of bounding box

• swlng (float | None) – SW longitude of bounding box

• fields (list[str] | dict[str, Any] | None) – Data fields to return in the response

• except_fields (list[str] | None) – Data fields to exclude from the response (and include all others)

• page (int | None) – Page number of results to return

• per_page (int | None) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted

• order (Optional[Literal['asc', 'desc']]) – Sort order

• order_by (str | None) – Field to sort on

• count_only (bool | None) – Only return a count of results; alias for per_page=0

• reverse (bool | None) – Reverse the order of results; alias for order='descending'

• only_id (bool | None) – Return only the record IDs

• access_token (str | None) – An access token for user authentication, as returned by get_access_token()

• dry_run (bool | None) – Just log the request instead of sending a real request

• session (Session | None) –

  An existing Session object to use instead of creating a new one

Return type:

dict[str, Any]

Returns:

Response dict containing observation records

Examples

Get observations of Monarch butterflies with photos + public location info, on a specific date in the province of Saskatchewan, CA (place ID 7953), and return all available fields:

>>> response = get_observations(
>>>     taxon_name='Danaus plexippus',
>>>     created_on='2020-08-27',
>>>     photos=True,
>>>     geo=True,
>>>     geoprivacy='open',
>>>     place_id=7953,
>>>     fields='all',
>>> )

Get basic info for observations in response:

>>> pprint(response)
'[57754375] Species: Danaus plexippus (Monarch) observed by samroom on 2020-08-27 at Railway Ave, Wilcox, SK'
'[57707611] Species: Danaus plexippus (Monarch) observed by ingridt3 on 2020-08-26 at Michener Dr, Regina, SK'

Return only observation UUIDs and users:

>>> response = get_observations(
>>>     taxon_name='Danaus plexippus',
>>>     created_on='2020-08-27',
>>>     fields={'uuid':True, 'user':{'login':True}},
>>> )

Return all response fields except identifications:

>>> response = get_observations(id=14150125, except_fields=['identifications'])

Search for observations with a given observation field:

>>> response = get_observations(observation_fields=['Species count'])

Or observation field value:

>>> response = get_observations(observation_fields={'Species count': 2})

Example Response (default/minimal)

{
    'total_results': 1,
    'page': 1,
    'per_page': 30,
    'results': [
        {
            'uuid': '91a29d5f-d2bf-47ff-b629-d0b79d51e46c',
            'created_at': None,
        }
    ],
}

Example Response (all fields)

from datetime import datetime

from dateutil.tz import tzoffset

{
    'total_results': 1,
    'page': 1,
    'per_page': 30,
    'results': [
        {
            'id': 14150125,
            'annotations': [],
            'application': {
                'id': 3,
                'icon': 'https://static.inaturalist.org/oauth_applications/3-thumb.png',
                'name': 'iNaturalist iPhone App',
                'url': 'https://itunes.apple.com/us/app/inaturalist/id421397028?mt=8',
            },
            'cached_votes_total': 0,
            'captive': False,
            'comments': [],
            'comments_count': 0,
            'community_taxon_id': 4626,
            'created_at': datetime(2018, 7, 7, 19, 12, 40, tzinfo=tzoffset(None, -18000)),
            'created_at_details': {
                'date': '2018-07-07',
                'day': 7,
                'hour': 19,
                'month': 7,
                'week': 27,
                'year': 2018,
            },
            'created_time_zone': 'America/Chicago',
            'description': 'This was very clearly a common loon through visual and binoculars.  I have seen loons at this location before and two summers before there were two nesting pairs with young about 2.5 kilometres south',
            'faves': [],
            'faves_count': 0,
            'flags': [],
            'geojson': {'coordinates': [-105.1650693422, 50.9316206893], 'type': 'Point'},
            'geoprivacy': None,
            'ident_taxon_ids': [48460, 1, 2, 355675, 3, 67562, 4619, 4620, 4626],
            'identifications': [
                {
                    'id': 30712840,
                    'body': None,
                    'category': 'improving',
                    'created_at': '2018-07-08T00:12:40+00:00',
                    'created_at_details': {
                        'date': '2018-07-08',
                        'day': 8,
                        'hour': 0,
                        'month': 7,
                        'week': 27,
                        'year': 2018,
                    },
                    'current': True,
                    'disagreement': False,
                    'flags': [],
                    'hidden': False,
                    'moderator_actions': [],
                    'own_observation': True,
                    'previous_observation_taxon_id': 4626,
                    'previous_observation_taxon': 'TRUNCATED',
                    'spam': False,
                    'taxon': {'id': 4626},
                    'taxon_change': None,
                    'taxon_id': 4626,
                    'user': {
                        'id': 1020044,
                        'created_at': '2018-06-11T17:31:48+00:00',
                        'icon': None,
                        'icon_url': None,
                        'identifications_count': 0,
                        'journal_posts_count': 0,
                        'login': 'jmilligan',
                        'name': None,
                        'observations_count': 26,
                        'orcid': None,
                        'roles': [],
                        'site_id': 5,
                        'spam': False,
                        'species_count': 24,
                        'suspended': False,
                    },
                    'uuid': '341063ea-4553-4caf-8df4-27287773652c',
                    'vision': True,
                },
                {
                    'id': 30712897,
                    'body': None,
                    'category': 'supporting',
                    'created_at': '2018-07-08T00:13:35+00:00',
                    'created_at_details': {
                        'date': '2018-07-08',
                        'day': 8,
                        'hour': 0,
                        'month': 7,
                        'week': 27,
                        'year': 2018,
                    },
                    'current': True,
                    'disagreement': False,
                    'flags': [],
                    'hidden': False,
                    'moderator_actions': [],
                    'own_observation': False,
                    'previous_observation_taxon_id': 4626,
                    'previous_observation_taxon': 'TRUNCATED',
                    'spam': False,
                    'taxon': {'id': 4626},
                    'taxon_change': None,
                    'taxon_id': 4626,
                    'user': {
                        'id': 854537,
                        'created_at': '2018-04-16T22:12:08+00:00',
                        'icon': 'https://static.inaturalist.org/attachments/users/icons/854537/thumb.jpg?1529523533',
                        'icon_url': 'https://static.inaturalist.org/attachments/users/icons/854537/medium.jpg?1529523533',
                        'identifications_count': 660192,
                        'journal_posts_count': 4,
                        'login': 'maxallen',
                        'name': '',
                        'observations_count': 3241,
                        'orcid': 'https://orcid.org/0000-0001-8976-889X',
                        'roles': ['curator'],
                        'site_id': 1,
                        'spam': False,
                        'species_count': 730,
                        'suspended': False,
                    },
                    'uuid': 'ae42a86f-3f42-475b-b6ba-05e2b979860f',
                    'vision': False,
                },
                {
                    'id': 32809047,
                    'body': None,
                    'category': 'supporting',
                    'created_at': '2018-08-07T13:37:57+00:00',
                    'created_at_details': {
                        'date': '2018-08-07',
                        'day': 7,
                        'hour': 13,
                        'month': 8,
                        'week': 32,
                        'year': 2018,
                    },
                    'current': True,
                    'disagreement': False,
                    'flags': [],
                    'hidden': False,
                    'moderator_actions': [],
                    'own_observation': False,
                    'previous_observation_taxon_id': 4626,
                    'previous_observation_taxon': 'TRUNCATED',
                    'spam': False,
                    'taxon': {'id': 4626},
                    'taxon_change': None,
                    'taxon_id': 4626,
                    'user': {
                        'id': 1066032,
                        'created_at': '2018-07-05T03:06:57+00:00',
                        'icon': 'https://static.inaturalist.org/attachments/users/icons/1066032/thumb.jpg?1577404661',
                        'icon_url': 'https://static.inaturalist.org/attachments/users/icons/1066032/medium.jpg?1577404661',
                        'identifications_count': 37,
                        'journal_posts_count': 0,
                        'login': 'ashton3d',
                        'name': None,
                        'observations_count': 15,
                        'orcid': None,
                        'roles': [],
                        'site_id': 5,
                        'spam': False,
                        'species_count': 12,
                        'suspended': False,
                    },
                    'uuid': '4e8a8903-faa2-460c-8b00-1022ad659ea9',
                    'vision': False,
                },
            ],
            'identifications_count': 2,
            'identifications_most_agree': True,
            'identifications_most_disagree': False,
            'identifications_some_agree': True,
            'license_code': None,
            'location': [50.9316206893, -105.1650693422],
            'map_scale': None,
            'mappable': True,
            'non_owner_ids': 'TRUNCATED',
            'num_identification_agreements': 2,
            'num_identification_disagreements': 0,
            'oauth_application_id': 3,
            'obscured': False,
            'observation_photos': [
                {
                    'id': 19226130,
                    'photo': {
                        'id': 20970868,
                        'attribution': '(c) jmilligan, all rights reserved',
                        'flags': [],
                        'license_code': None,
                        'original_dimensions': {'height': 1176, 'width': 860},
                        'url': 'https://static.inaturalist.org/photos/20970868/square.jpg',
                    },
                    'position': 0,
                    'uuid': '742aaffb-f65d-4177-8794-432b406f688a',
                },
                {
                    'id': 19226126,
                    'photo': {
                        'id': 20970862,
                        'attribution': '(c) jmilligan, all rights reserved',
                        'flags': [],
                        'license_code': None,
                        'original_dimensions': {'height': 1512, 'width': 2016},
                        'url': 'https://static.inaturalist.org/photos/20970862/square.jpg',
                    },
                    'position': 1,
                    'uuid': '6587937e-bead-45de-a2e7-83057f0b15e4',
                },
            ],
            'observed_on': datetime(2018, 7, 7, 8, 10, 6, tzinfo=tzoffset(None, -18000)),
            'observed_on_details': {
                'date': '2018-07-07',
                'day': 7,
                'hour': 8,
                'month': 7,
                'week': 27,
                'year': 2018,
            },
            'observed_on_string': 'Sat Jul 07 2018 08:10:06 GMT-0600 (CST)',
            'observed_time_zone': 'America/Chicago',
            'ofvs': [],
            'outlinks': [],
            'owners_identification_from_vision': True,
            'photos': [
                {
                    'id': 20970868,
                    'attribution': '(c) jmilligan, all rights reserved',
                    'flags': [],
                    'license_code': None,
                    'original_dimensions': {'height': 1176, 'width': 860},
                    'original_filename': '20180707_081006.jpg',
                    'url': 'https://static.inaturalist.org/photos/20970868/square.jpg',
                },
                {
                    'id': 20970862,
                    'attribution': '(c) jmilligan, all rights reserved',
                    'flags': [],
                    'license_code': None,
                    'original_dimensions': {'height': 1512, 'width': 2016},
                    'original_filename': '20180707_081007.jpg',
                    'url': 'https://static.inaturalist.org/photos/20970862/square.jpg',
                },
            ],
            'place_guess': '189 Marine Dr, , SK, CA',
            'place_ids': [
                6712,
                7953,
                9853,
                49224,
                59613,
                64422,
                64423,
                66741,
                78395,
                82256,
                97394,
                145030,
                155145,
            ],
            'positional_accuracy': 44,
            'preferences': {'prefers_community_taxon': None},
            'project_ids': [],
            'project_ids_with_curator_id': [],
            'project_ids_without_curator_id': [],
            'project_observations': [],
            'public_positional_accuracy': 44,
            'quality_grade': 'research',
            'quality_metrics': [],
            'reviewed_by': [854537, 1020044, 1066032],
            'site_id': 5,
            'sounds': [],
            'spam': False,
            'species_guess': 'Common Loon',
            'tags': [],
            'taxon': {
                'id': 4626,
                'ancestor_ids': [48460, 1, 2, 355675, 3, 67562, 4619, 4620, 4626],
                'ancestry': '48460/1/2/355675/3/67562/4619/4620',
                'atlas_id': None,
                'complete_rank': 'subspecies',
                'complete_species_count': None,
                'created_at': '2008-03-13T02:45:55+00:00',
                'current_synonymous_taxon_ids': None,
                'default_photo': {
                    'id': 54184759,
                    'attribution': '(c) Liz Osborn, some rights reserved (CC BY-NC), uploaded by Liz Osborn',
                    'flags': [],
                    'license_code': 'cc-by-nc',
                    'medium_url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/54184759/medium.jpg',
                    'original_dimensions': {'height': 1159, 'width': 1854},
                    'square_url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/54184759/square.jpg',
                    'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/54184759/square.jpg',
                },
                'endemic': False,
                'extinct': False,
                'flag_counts': {'resolved': 0, 'unresolved': 0},
                'iconic_taxon_id': 3,
                'iconic_taxon_name': 'Aves',
                'introduced': False,
                'is_active': True,
                'min_species_ancestry': '48460,1,2,355675,3,67562,4619,4620,4626',
                'min_species_taxon_id': 4626,
                'name': 'Gavia immer',
                'native': True,
                'observations_count': 31016,
                'parent_id': 4620,
                'photos_locked': False,
                'preferred_common_name': 'Common Loon',
                'rank': 'species',
                'rank_level': 10,
                'taxon_changes_count': 0,
                'taxon_schemes_count': 9,
                'threatened': False,
                'universal_search_rank': 31016,
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Common_loon',
            },
            'taxon_geoprivacy': 'open',
            'time_zone_offset': '-06:00',
            'updated_at': datetime(2018, 8, 7, 8, 37, 57, tzinfo=tzoffset(None, -18000)),
            'uri': 'https://www.inaturalist.org/observations/14150125',
            'user': {
                'id': 1020044,
                'created_at': '2018-06-11T17:31:48+00:00',
                'icon': None,
                'icon_url': None,
                'identifications_count': 0,
                'journal_posts_count': 0,
                'login': 'jmilligan',
                'name': None,
                'observations_count': 26,
                'orcid': None,
                'preferences': {},
                'roles': [],
                'site_id': 5,
                'spam': False,
                'species_count': 24,
                'suspended': False,
            },
            'uuid': '91a29d5f-d2bf-47ff-b629-d0b79d51e46c',
            'votes': [],
        }
    ],
}

pyinaturalist.v2.observations.set_observation_field(access_token, dry_run, session, **kwargs) → dict[str, Any]

Create or update an observation field value on an observation

Parameters:

• observation_id – ID or UUID of the observation to update observation_field_id: ID of the observation field for this observation field value value: Value for the observation field

• rubric: (..) – Notes:

:param * Requires authentication: :param * API reference: POST /observation_field_values/{id} :param * To find an observation_field_id: search observation fields on iNaturalist :param either user get_observation_fields() or: search observation fields on iNaturalist :type access_token: str | None :param access_token: An access token for user authentication, as returned by get_access_token() :type dry_run: bool | None :param dry_run: Just log the request instead of sending a real request :type session: Session | None :param session: An existing Session object to use instead of creating a new one

Example

>>> set_observation_field(
...     7345179,
...     observation_field_id,
...     value=250,
...     access_token=token,
... )

Example Response

{
  "id": 31,
  "observation_id": 18166477,
  "observation_field_id": 31,
  "value": "fouraging",
  "created_at": "2012-09-29T11:05:44.935+02:00",
  "updated_at": "2018-11-13T10:49:47.985+01:00",
  "user_id": 1,
  "updater_id": 1263313,
  "uuid": "b404b654-1bf0-4299-9288-52eeda7ac0db",
  "created_at_utc": "2012-09-29T09:05:44.935Z",
  "updated_at_utc": "2018-11-13T09:49:47.985Z"
}

Return type:

dict[str, Any]

Returns:

The newly updated field value record

pyinaturalist.v2.observations.update_observation(access_token, species_guess, taxon_id, observed_on, observed_on_string, time_zone, ...) → dict[str, Any]

Update a single observation

Notes

• Requires authentication

• API reference: PUT /observations/{uuid}

Parameters:

• observation_uuid – UUID of the observation to update

• access_token (str | None) – An access token for user authentication, as returned by get_access_token()

• species_guess (str | None) – Equivalent to the ‘What did you see?’ field on the observation form. iNat will try to choose a single taxon based on this, but it may fail if it’s ambiguous

• taxon_id (int | None) – ID of the taxon to associate with this observation

• observed_on (date | datetime | str | None) – Alias for observed_on_string; accepts datetime objects.

• observed_on_string (date | datetime | str | None) – Date/time of the observation. Time zone will default to the user’s time zone if not specified.

• time_zone (str | None) – Time zone the observation was made in

• description (str | None) – Observation description

• tag_list (str | Iterable[str] | None) – Comma-separated list of tags

• place_guess (str | None) – Name of the place where the observation was recorded. Note: iNat will not try to automatically look up coordinates based on this string

• latitude (float | None) – Latitude of the observation; presumed datum is WGS84

• longitude (float | None) – Longitude of the observation; presumed datum is WGS84

• map_scale (int | None) – Google Maps zoom level (from 0 to 19) at which to show this observation’s map marker.

• positional_accuracy (int | None) – Positional accuracy of the observation coordinates, in meters

• geoprivacy (Optional[Literal['obscured', 'obscured_private', 'open', 'private']]) – Geoprivacy for the observation

• observation_fields (dict | list[dict] | None) – Dict of observation fields in the format {id: value}. Alias for observation_field_values_attributes.

• photos (BinaryIO | Path | str | Iterable[BinaryIO | Path | str] | None) – One or more image files, file-like objects, file paths, or URLs

• sounds (BinaryIO | Path | str | Iterable[BinaryIO | Path | str] | None) – One or more sound files, file-like objects, file paths, or URLs

• photo_ids (int | Iterable[int] | str | Iterable[str] | None) – One or more IDs of previously uploaded photos to attach to the observation

• captive_flag (bool | None) – Mark observation as captive/cultivated

• coordinate_system (str | None) – Coordinate system used (if not WGS84)

• geo_x (float | None) – X coordinate in alternative coordinate system

• geo_y (float | None) – Y coordinate in alternative coordinate system

• license (str | None) – License to apply to the observation (e.g., ‘cc-by’, ‘cc-by-nc’, ‘cc0’)

• location_is_exact (bool | None) – Whether the location coordinates are exact

• make_license_default (bool | None) – Make this license the user’s default for future observations

• make_licenses_same (bool | None) – Apply the same license to all associated photos

• owners_identification_from_vision (bool | None) – Initial identification came from computer vision

• positioning_device (str | None) – Device used for positioning (e.g., ‘gps’, ‘cell’, ‘network’)

• positioning_method (str | None) – Method used to determine positioning

• prefers_community_taxon (bool | None) – User preference for using community taxon over their own identification

• project_id (int | None) – Project ID to add observation to upon creation

• site_id (int | None) – iNaturalist network site ID (e.g., for iNaturalist.ca, iNaturalist.nz)

• uuid (str | None) – UUID of the observation (for updates to preserve UUID)

• dry_run (bool | None) – Just log the request instead of sending a real request

• session (Session | None) –

  An existing Session object to use instead of creating a new one

Example

>>> token = get_access_token()
>>> update_observation(
>>>     '53411fc2-bdf0-434e-afce-4dac33970173',
>>>     access_token=token,
>>>     description='updated description!',
>>>     captive_flag=True,
>>> )

Example Response

{"uuid": "6444ede0-9831-47bd-8c3b-ee32e08cbfe4"}

Return type:

dict[str, Any]

Returns:

JSON response containing the updated observation

pyinaturalist.v2.observations.upload(observation_uuid, photos, sounds, photo_ids, **params) → list[dict[str, Any]]

Upload one or more local photo and/or sound files, and add them to an existing observation.

You may also attach a previously uploaded photo by photo ID, e.g. if your photo contains multiple organisms and you want to create a separate observation for each one.

Notes

• Requires authentication

• API reference: POST /observation_photos

• API reference: POST /observation_sounds

Parameters:

• observation_uuid (str) – The UUID of the observation

• photos (BinaryIO | Path | str | Iterable[BinaryIO | Path | str] | None) – One or more image files, file-like objects, file paths, or URLs

• sounds (BinaryIO | Path | str | Iterable[BinaryIO | Path | str] | None) – One or more audio files, file-like objects, file paths, or URLs

• photo_ids (int | Iterable[int] | str | Iterable[str] | None) – One or more IDs of previously uploaded photos to attach to the observation

• access_token – Access token for user authentication, as returned by get_access_token()

• dry_run – Just log the request instead of sending a real request

• session –

  An existing Session object to use instead of creating a new one

Example

>>> token = get_access_token()
>>> upload(
...     '53411fc2-bdf0-434e-afce-4dac33970173',
...     photos=['~/observations/2020_09_01_140031.jpg', '~/observations/2020_09_01_140042.jpg'],
...     sounds='~/observations/2020_09_01_140031.mp3',
...     photo_ids=[1234, 5678],
...     access_token=token,
... )

Example Response

[{"id": 178539}, {"id": 955963}]

Return type:

list[dict[str, Any]]

Returns:

IDs only for newly created files