Observations#

Summary#

Classes

Functions

get_observations(**params)

Search observations

Module Contents#

pyinaturalist.v2.observations.get_observations(**params)#

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 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},
                    '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},
                    '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': [],
        }
    ],
}