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, ...])

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=None, species_guess=None, taxon_id=None, observed_on=None, observed_on_string=None, time_zone=None, description=None, tag_list=None, place_guess=None, latitude=None, longitude=None, map_scale=None, positional_accuracy=None, geoprivacy=None, observation_fields=None, observation_field_values_attributes=None, flickr_photos=None, picasa_photos=None, facebook_photos=None, local_photos=None, photos=None, sounds=None, photo_ids=None, captive_flag=None, coordinate_system=None, geo_x=None, geo_y=None, license=None, location_is_exact=None, make_license_default=None, make_licenses_same=None, owners_identification_from_vision=None, positioning_device=None, positioning_method=None, prefers_community_taxon=None, project_id=None, site_id=None, uuid=None, dry_run=False, session=None, **kwargs) → Dict[str, Any]

Create a new observation.

Notes

Parameters:

  • access_token (Optional[str]) – An access token for user authentication, as returned by get_access_token()

  • species_guess (Optional[str]) – 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 (Optional[int]) – ID of the taxon to associate with this observation

  • observed_on (Union[date, datetime, str, None]) – Alias for observed_on_string; accepts datetime objects.

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

  • time_zone (Optional[str]) – Time zone the observation was made in

  • description (Optional[str]) – Observation description

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

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

  • latitude (Optional[float]) – Latitude of the observation; presumed datum is WGS84

  • longitude (Optional[float]) – Longitude of the observation; presumed datum is WGS84

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

  • positional_accuracy (Optional[int]) – Positional accuracy of the observation coordinates, in meters

  • geoprivacy (Optional[str]) – Geoprivacy for the observation

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

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

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

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

  • captive_flag (Optional[bool]) – Mark observation as captive/cultivated

  • coordinate_system (Optional[str]) – Coordinate system used (if not WGS84)

  • geo_x (Optional[float]) – X coordinate in alternative coordinate system

  • geo_y (Optional[float]) – Y coordinate in alternative coordinate system

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

  • location_is_exact (Optional[bool]) – Whether the location coordinates are exact

  • make_license_default (Optional[bool]) – Make this license the user’s default for future observations

  • make_licenses_same (Optional[bool]) – Apply the same license to all associated photos

  • owners_identification_from_vision (Optional[bool]) – Initial identification came from computer vision

  • positioning_device (Optional[str]) – Device used for positioning (e.g., ‘gps’, ‘cell’, ‘network’)

  • positioning_method (Optional[str]) – Method used to determine positioning

  • prefers_community_taxon (Optional[bool]) – User preference for using community taxon over their own identification

  • project_id (Optional[int]) – Project ID to add observation to upon creation

  • site_id (Optional[int]) – iNaturalist network site ID (e.g., for iNaturalist.ca, iNaturalist.nz)

  • uuid (Optional[str]) – UUID of the observation (for updates to preserve UUID)

  • dry_run (Optional[bool]) – Just log the request instead of sending a real request

  • session (Optional[Session]) – 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=None, dry_run=False, session=None, **kwargs)

Delete an observation

Notes

Parameters:

Example

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

If successful, no response is returned from this endpoint

Raises:
pyinaturalist.v2.observations.get_observations(q=None, d1=None, d2=None, day=None, month=None, year=None, license=None, list_id=None, photo_license=None, out_of_range=None, quality_grade=None, id=None, taxon_id=None, taxon_name=None, iconic_taxa=None, updated_since=None, acc=None, captive=None, endemic=None, geo=None, id_please=None, identified=None, introduced=None, mappable=None, native=None, pcid=None, photos=None, popular=None, sounds=None, taxon_is_active=None, threatened=None, verifiable=None, not_id=None, sound_license=None, observation_fields=None, ofv_datatype=None, place_id=None, project_id=None, rank=None, site_id=None, without_taxon_id=None, user_id=None, user_login=None, ident_user_id=None, term_id=None, term_value_id=None, without_term_value_id=None, acc_above=None, acc_below=None, acc_below_or_unknown=None, created_d1=None, created_d2=None, created_on=None, observed_on=None, unobserved_by_user_id=None, apply_project_rules_for=None, cs=None, csa=None, csi=None, geoprivacy=None, taxon_geoprivacy=None, max_rank=None, min_rank=None, hrank=None, lrank=None, id_above=None, id_below=None, identifications=None, lat=None, lng=None, radius=None, not_in_project=None, not_matching_project_rules_for=None, search_on=None, viewer_id=None, reviewed=None, locale=None, preferred_place_id=None, ttl=None, nelat=None, nelng=None, swlat=None, swlng=None, fields=None, except_fields=None, page=None, per_page=None, order=None, order_by=None, count_only=None, reverse=None, only_id=None, access_token=None, dry_run=False, session=None, **kwargs) → Dict[str, Any]

Search observations

Notes

Parameters:

  • q (Optional[str]) – Search observation properties

  • d1 (Union[date, datetime, str, None]) – Must be observed on or after this date

  • d2 (Union[date, datetime, str, None]) – Must be observed on or before this date

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

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

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

  • license (Union[str, Iterable[str], None]) – Observation must have this license

  • photo_license (Union[str, Iterable[str], None]) – Must have at least one photo with this license

  • out_of_range (Optional[bool]) – Observations whose taxa are outside their known ranges

  • list_id (Optional[int]) – Taxon must be in the list with this ID

  • quality_grade (Optional[str]) – Must have this quality grade

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

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

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

  • iconic_taxa (Union[str, Iterable[str], None]) – Taxon must by within this iconic taxon

  • updated_since (Union[datetime, str, None]) – Must be updated since this time

  • acc (Optional[bool]) – Whether or not positional accuracy / coordinate uncertainty has been specified

  • captive (Optional[bool]) – Captive or cultivated observations

  • endemic (Optional[bool]) – Observations whose taxa are endemic to their location

  • geo (Optional[bool]) – Observations that are georeferenced

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

  • identified (Optional[bool]) – Observations that have community identifications

  • introduced (Optional[bool]) – Observations whose taxa are introduced in their location

  • mappable (Optional[bool]) – Observations that show on map tiles

  • native (Optional[bool]) – Observations whose taxa are native to their location

  • pcid (Optional[bool]) – 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 (Optional[bool]) – Observations with photos

  • popular (Optional[bool]) – Observations that have been favorited by at least one user

  • sounds (Optional[bool]) – Observations with sounds

  • taxon_is_active (Optional[bool]) – Observations of active taxon concepts

  • threatened (Optional[bool]) – Observations whose taxa are threatened in their location

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

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

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

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

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

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

  • observation_fields (Union[List, Dict, None]) – Must have these observation fields (optionally with values)

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

  • sound_license (Union[str, Iterable[str], None]) – Must have at least one sound with this license

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

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

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

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

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

  • term_value_id (Union[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 (Union[int, Iterable[int], None]) – Exclude observations with annotations using this controlled value ID. Must be combined with the term_id parameter

  • acc_above (Optional[str]) – Must have an positional accuracy above this value (meters)

  • acc_below (Optional[str]) – Must have an positional accuracy below this value (meters)

  • acc_below_or_unknown (Optional[str]) – Must have an positional accuracy below this value (meters) or unknown

  • created_d1 (Union[datetime, str, None]) – Must be created at or after this time

  • created_d2 (Union[datetime, str, None]) – Must be created at or before this time

  • created_on (Union[date, datetime, str, None]) – Must be created on this date

  • observed_on (Union[date, datetime, str, None]) – Must be observed on this date

  • unobserved_by_user_id (Optional[int]) – Must not be of a taxon previously observed by this user

  • apply_project_rules_for (Optional[str]) – Must match the rules of the project with this ID or slug

  • cs (Optional[str]) – 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 (Optional[str]) – 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[str, Iterable[str], 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[str, Iterable[str], None]) – Must have this geoprivacy setting

  • taxon_geoprivacy (Union[str, Iterable[str], 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 (Optional[str]) – Taxon must have this rank or lower

  • lrank (Optional[str]) – Taxon must have this rank or higher

  • id_above (Optional[int]) – Must have an ID above this value

  • id_below (Optional[int]) – Must have an ID below this value

  • identifications (Optional[str]) – Identifications must meet these criteria

  • lat (Optional[float]) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)

  • lng (Optional[float]) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)

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

  • not_in_project (Union[int, str, None]) – Must not be in the project with this ID or slug

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

  • search_on (Optional[str]) – Properties to search on, when combined with q. Searches across all properties by default

  • viewer_id (Optional[int]) – See reviewed

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

  • locale (Optional[str]) – Locale preference for taxon common names

  • preferred_place_id (Optional[int]) – Place preference for regional taxon common names

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

  • nelat (Optional[float]) – NE latitude of bounding box

  • nelng (Optional[float]) – NE longitude of bounding box

  • swlat (Optional[float]) – SW latitude of bounding box

  • swlng (Optional[float]) – SW longitude of bounding box

  • fields (Union[List[str], Dict[str, Any], None]) – Data fields to return in the response

  • except_fields (Optional[List[str]]) – Data fields to exclude from the response (and include all others)

  • page (Optional[int]) – Page number of results to return

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

  • order (Optional[str]) – Sort order

  • order_by (Optional[str]) – Field to sort on

  • count_only (Optional[bool]) – Only return a count of results; alias for per_page=0

  • reverse (Optional[bool]) – Reverse the order of results; alias for order='descending'

  • only_id (Optional[bool]) – Return only the record IDs

  • access_token (Optional[str]) – An access token for user authentication, as returned by get_access_token()

  • dry_run (Optional[bool]) – Just log the request instead of sending a real request

  • session (Optional[Session]) –

    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=None, dry_run=False, session=None, **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: Optional[str] :param access_token: An access token for user authentication, as returned by get_access_token() :type dry_run: Optional[bool] :param dry_run: Just log the request instead of sending a real request :type session: Optional[Session] :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=None, species_guess=None, taxon_id=None, observed_on=None, observed_on_string=None, time_zone=None, description=None, tag_list=None, place_guess=None, latitude=None, longitude=None, map_scale=None, positional_accuracy=None, geoprivacy=None, observation_fields=None, observation_field_values_attributes=None, flickr_photos=None, picasa_photos=None, facebook_photos=None, local_photos=None, photos=None, sounds=None, photo_ids=None, captive_flag=None, coordinate_system=None, geo_x=None, geo_y=None, license=None, location_is_exact=None, make_license_default=None, make_licenses_same=None, owners_identification_from_vision=None, positioning_device=None, positioning_method=None, prefers_community_taxon=None, project_id=None, site_id=None, uuid=None, dry_run=False, session=None, **kwargs) → Dict[str, Any]

Update a single observation

Notes

Parameters:

  • observation_uuid – UUID of the observation to update

  • access_token (Optional[str]) – An access token for user authentication, as returned by get_access_token()

  • species_guess (Optional[str]) – 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 (Optional[int]) – ID of the taxon to associate with this observation

  • observed_on (Union[date, datetime, str, None]) – Alias for observed_on_string; accepts datetime objects.

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

  • time_zone (Optional[str]) – Time zone the observation was made in

  • description (Optional[str]) – Observation description

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

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

  • latitude (Optional[float]) – Latitude of the observation; presumed datum is WGS84

  • longitude (Optional[float]) – Longitude of the observation; presumed datum is WGS84

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

  • positional_accuracy (Optional[int]) – Positional accuracy of the observation coordinates, in meters

  • geoprivacy (Optional[str]) – Geoprivacy for the observation

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

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

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

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

  • captive_flag (Optional[bool]) – Mark observation as captive/cultivated

  • coordinate_system (Optional[str]) – Coordinate system used (if not WGS84)

  • geo_x (Optional[float]) – X coordinate in alternative coordinate system

  • geo_y (Optional[float]) – Y coordinate in alternative coordinate system

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

  • location_is_exact (Optional[bool]) – Whether the location coordinates are exact

  • make_license_default (Optional[bool]) – Make this license the user’s default for future observations

  • make_licenses_same (Optional[bool]) – Apply the same license to all associated photos

  • owners_identification_from_vision (Optional[bool]) – Initial identification came from computer vision

  • positioning_device (Optional[str]) – Device used for positioning (e.g., ‘gps’, ‘cell’, ‘network’)

  • positioning_method (Optional[str]) – Method used to determine positioning

  • prefers_community_taxon (Optional[bool]) – User preference for using community taxon over their own identification

  • project_id (Optional[int]) – Project ID to add observation to upon creation

  • site_id (Optional[int]) – iNaturalist network site ID (e.g., for iNaturalist.ca, iNaturalist.nz)

  • uuid (Optional[str]) – UUID of the observation (for updates to preserve UUID)

  • dry_run (Optional[bool]) – Just log the request instead of sending a real request

  • session (Optional[Session]) –

    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=None, sounds=None, photo_ids=None, **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

Parameters:

  • observation_uuid (str) – The UUID of the observation

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

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

  • photo_ids (Union[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