Observations#

Summary#

Classes

Functions

`create_observation`(**params)	Create or update an observation.
`delete_observation`(observation_id[, ...])	Delete an observation
`get_observation`(observation_id[, access_token])	Get details about a single observation by ID
`get_observation_histogram`(**params)	Search observations and return histogram data for the given time interval
`get_observation_identifiers`(**params)	Get identifiers of observations matching the search criteria and the count of observations they have identified.
`get_observation_observers`(**params)	Get observers of observations matching the search criteria and the count of observations and distinct taxa of rank species they have observed.
`get_observation_popular_field_values`(**params)	Get controlled terms values and a monthly histogram of observations matching the search criteria.
`get_observation_species_counts`(**params)	Get all species (or other 'leaf taxa') associated with observations matching the search criteria, and the count of observations they are associated with.
`get_observation_taxon_summary`(...)	Get information about an observation's taxon, within the context of the observation's location
`get_observation_taxonomy`(**params)	Get observation counts for all taxa in observations matching the search criteria.
`get_observations`(**params)	Search observations
`get_observations_by_id`(observation_id[, ...])	Get one or more observations by ID
`update_observation`(observation_id, **params)	Update a single observation
`upload`(observation_id[, photos, sounds, ...])	Upload one or more local photo and/or sound files, and add them to an existing observation.

Module Contents#

pyinaturalist.v1.observations.create_observation(**params)#

Create or update an observation.

Notes

Requires authentication
API reference: POST /observations

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.
flickr_photos (Union[int, Iterable[int], None]) – Flickr photo ID(s) to add as photos for this observation. User must have their Flickr and iNat accounts connected, and the user must own the photo(s) on Flickr.
picasa_photos (Union[str, Iterable[str], None]) – Picasa photo ID(s) to add as photos for this observation. User must have their Picasa and iNat accounts connected, and the user must own the photo(s) on Picasa.
facebook_photos (Union[str, Iterable[str], None]) – Facebook photo IDs to add as photos for this observation. User must have their Facebook and iNat accounts connected, and the user must own the photo on Facebook.
photos (Union[BinaryIO, str, Iterable[Union[BinaryIO, str]], None]) – One or more image files, file-like objects, file paths, or URLs
sounds (Union[BinaryIO, str, Iterable[Union[BinaryIO, 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
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',
...     photos='~/observation_photos/2020_09_01_14003156.jpg',
...     observation_fields={297: 1},  # 297 is the obs. field ID for 'Number of individuals'
... )
>>>
>>> # Update an existing observation:
>>> create_observation(
...     access_token=token,
...     uuid='53411fc2-bdf0-434e-afce-4dac33970173',
...     description='Updated description!',
... )

Return type:: Dict[str, Any]
Returns:: JSON response containing the newly created observation(s)

pyinaturalist.v1.observations.delete_observation(observation_id, access_token=None, **params)#

Delete an observation

Notes

Requires authentication
API reference: DELETE /observations/{id}

Parameters:

observation_id (int) – iNaturalist observation ID
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

Example

>>> token = get_access_token()
>>> delete_observation(17932425, token)

Returns:

If successful, no response is returned from this endpoint

Raises:

.ObservationNotFound –
requests.HTTPError –

pyinaturalist.v1.observations.get_observation(observation_id, access_token=None, **params)#

Get details about a single observation by ID

Notes

Deprecated; use get_observations() or get_observations_by_id() instead
Optional authentication (For private/obscured coordinates)
API reference: GET /observations/{id}

Parameters:

observation_id (int) – Get the observation with this ID. Only a single value is allowed.
access_token (Optional[str]) – An access token, 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

Example

>>> response = get_observation(16227955)

Return type:: Dict[str, Any]
Returns:: A dict with details on the observation
Raises:: .ObservationNotFound –

pyinaturalist.v1.observations.get_observation_histogram(**params)#

Search observations and return histogram data for the given time interval

Notes

API reference: GET /observations/histogram
Search parameters are the same as get_observations(), with the addition of date_field and interval.
date_field may be either ‘observed’ (default) or ‘created’.
Observed date ranges can be filtered by parameters d1 and d2
Created date ranges can be filtered by parameters created_d1 and created_d2
interval may be one of: ‘year’, ‘month’, ‘week’, ‘day’, ‘hour’, ‘month_of_year’, or ‘week_of_year’; spaces are also allowed instead of underscores, e.g. ‘month of year’.
The year, month, week, day, and hour interval options will set default values for d1 and created_d1, to limit the number of groups returned. You can override those values if you want data from a longer or shorter time span.
The ‘hour’ interval only works with date_field='created'

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
date_field (str) – Histogram basis: either when the observation was created or observed
interval (str) – Time interval for histogram, with groups starting on or contained within the group value.
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

Get observations per month during 2020 in Austria (place ID 8057)

>>> response = get_observation_histogram(
>>>     interval='month',
>>>     d1='2020-01-01',
>>>     d2='2020-12-31',
>>>     place_id=8057,
>>> )

Return type:: Dict[Union[date, datetime, int], int]
Returns:: Dict of {time_key: observation_count}. Keys are ints for ‘month of year’ and ‘week of year’ intervals, and datetime objects for all other intervals.

pyinaturalist.v1.observations.get_observation_identifiers(**params)#

Get identifiers of observations matching the search criteria and the count of observations they have identified. By default, results are sorted by ID count in descending.

Notes

API reference: GET /observations/identifiers
This endpoint will only return up to 500 results.

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
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'
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

>>> response = get_observation_identifiers(place_id=72645)
>>> pprint(response)
[409010  ] jdoe42 (Jane Doe)
[691216  ] jbrown252 (James Brown)
[3959037 ] tnsparkleberry

Example Response

{
  "total_results": 2999,
  "page": 1,
  "per_page": 500,
  "results": [
    {
      "user_id": 53153,
      "count": 1787,
      "user": {
        "id": 53153,
        "login": "willkuhn",
        "spam": false,
        "suspended": false,
        "created_at": "2014-09-15T18:38:59+00:00",
        "login_autocomplete": "willkuhn",
        "login_exact": "willkuhn",
        "name": "Will Kuhn",
        "name_autocomplete": "Will Kuhn",
        "orcid": "https://orcid.org/0000-0002-5506-6379",
        "icon": "https://static.inaturalist.org/attachments/users/icons/53153/thumb.jpeg?1606488424",
        "observations_count": 2945,
        "identifications_count": 3895,
        "journal_posts_count": 0,
        "activity_count": 6840,
        "species_count": 1230,
        "universal_search_rank": 2945,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/53153/medium.jpeg?1606488424"
      }
    },
    {
      "user_id": 105391,
      "count": 1165,
      "user": {
        "id": 105391,
        "login": "jtuttle",
        "spam": false,
        "suspended": false,
        "created_at": "2015-05-25T21:56:21+00:00",
        "login_autocomplete": "jtuttle",
        "login_exact": "jtuttle",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/105391/thumb.jpg?1475546106",
        "observations_count": 12473,
        "identifications_count": 27628,
        "journal_posts_count": 0,
        "activity_count": 40101,
        "species_count": 3217,
        "universal_search_rank": 12473,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/105391/medium.jpg?1475546106"
      }
    },
    {
      "user_id": 32654,
      "count": 1012,
      "user": {
        "id": 32654,
        "login": "eraskin",
        "spam": false,
        "suspended": false,
        "created_at": "2014-03-19T18:35:39+00:00",
        "login_autocomplete": "eraskin",
        "login_exact": "eraskin",
        "name": "Evan M. Raskin",
        "name_autocomplete": "Evan M. Raskin",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/32654/thumb.jpg?1533126488",
        "observations_count": 5150,
        "identifications_count": 18213,
        "journal_posts_count": 3,
        "activity_count": 23366,
        "species_count": 2320,
        "universal_search_rank": 5150,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/32654/medium.jpg?1533126488"
      }
    },
    {
      "user_id": 1064292,
      "count": 907,
      "user": {
        "id": 1064292,
        "login": "syrherp",
        "spam": false,
        "suspended": false,
        "created_at": "2018-07-04T04:58:43+00:00",
        "login_autocomplete": "syrherp",
        "login_exact": "syrherp",
        "name": "Anthony Brais",
        "name_autocomplete": "Anthony Brais",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1064292/thumb.jpg?1537157949",
        "observations_count": 3788,
        "identifications_count": 33279,
        "journal_posts_count": 0,
        "activity_count": 37067,
        "species_count": 472,
        "universal_search_rank": 3788,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1064292/medium.jpg?1537157949"
      }
    },
    {
      "user_id": 2233645,
      "count": 851,
      "user": {
        "id": 2233645,
        "login": "jak2113",
        "spam": false,
        "suspended": false,
        "created_at": "2019-09-09T15:42:57+00:00",
        "login_autocomplete": "jak2113",
        "login_exact": "jak2113",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": null,
        "observations_count": 287,
        "identifications_count": 1623,
        "journal_posts_count": 0,
        "activity_count": 1910,
        "species_count": 206,
        "universal_search_rank": 287,
        "roles": [],
        "site_id": 1,
        "icon_url": null
      }
    },
    {
      "user_id": 19073,
      "count": 781,
      "user": {
        "id": 19073,
        "login": "choess",
        "spam": false,
        "suspended": false,
        "created_at": "2013-07-13T18:27:48+00:00",
        "login_autocomplete": "choess",
        "login_exact": "choess",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/19073/thumb.jpg?1475537701",
        "observations_count": 5067,
        "identifications_count": 152943,
        "journal_posts_count": 11,
        "activity_count": 158021,
        "species_count": 1284,
        "universal_search_rank": 5067,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/19073/medium.jpg?1475537701"
      }
    },
    {
      "user_id": 26905,
      "count": 668,
      "user": {
        "id": 26905,
        "login": "polemoniaceae",
        "spam": false,
        "suspended": false,
        "created_at": "2013-12-04T20:28:55+00:00",
        "login_autocomplete": "polemoniaceae",
        "login_exact": "polemoniaceae",
        "name": "Jeff",
        "name_autocomplete": "Jeff",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/26905/thumb.jpg?1475541432",
        "observations_count": 251,
        "identifications_count": 129664,
        "journal_posts_count": 0,
        "activity_count": 129915,
        "species_count": 222,
        "universal_search_rank": 251,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/26905/medium.jpg?1475541432"
      }
    },
    {
      "user_id": 854537,
      "count": 622,
      "user": {
        "id": 854537,
        "login": "maxallen",
        "spam": false,
        "suspended": false,
        "created_at": "2018-04-16T22:12:08+00:00",
        "login_autocomplete": "maxallen",
        "login_exact": "maxallen",
        "name": "",
        "name_autocomplete": "",
        "orcid": "https://orcid.org/0000-0001-8976-889X",
        "icon": "https://static.inaturalist.org/attachments/users/icons/854537/thumb.jpg?1529523533",
        "observations_count": 1938,
        "identifications_count": 524561,
        "journal_posts_count": 4,
        "activity_count": 526503,
        "species_count": 675,
        "universal_search_rank": 1938,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/854537/medium.jpg?1529523533"
      }
    },
    {
      "user_id": 755672,
      "count": 621,
      "user": {
        "id": 755672,
        "login": "ddennism",
        "spam": false,
        "suspended": false,
        "created_at": "2018-01-30T02:28:08+00:00",
        "login_autocomplete": "ddennism",
        "login_exact": "ddennism",
        "name": "Daniel McClosky",
        "name_autocomplete": "Daniel McClosky",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/755672/thumb.jpg?1571254550",
        "observations_count": 3369,
        "identifications_count": 38204,
        "journal_posts_count": 8,
        "activity_count": 41581,
        "species_count": 774,
        "universal_search_rank": 3369,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/755672/medium.jpg?1571254550"
      }
    },
    {
      "user_id": 2229996,
      "count": 616,
      "user": {
        "id": 2229996,
        "login": "annkatrinrose",
        "spam": false,
        "suspended": false,
        "created_at": "2019-09-08T18:45:38+00:00",
        "login_autocomplete": "annkatrinrose",
        "login_exact": "annkatrinrose",
        "name": "Annkatrin Rose",
        "name_autocomplete": "Annkatrin Rose",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/2229996/thumb.jpg?1567997735",
        "observations_count": 3799,
        "identifications_count": 9286,
        "journal_posts_count": 6,
        "activity_count": 13091,
        "species_count": 1024,
        "universal_search_rank": 3799,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/2229996/medium.jpg?1567997735"
      }
    },
    {
      "user_id": 324885,
      "count": 599,
      "user": {
        "id": 324885,
        "login": "lucareptile",
        "spam": false,
        "suspended": false,
        "created_at": "2016-09-09T00:19:57+00:00",
        "login_autocomplete": "lucareptile",
        "login_exact": "lucareptile",
        "name": "Luca Catanzaro",
        "name_autocomplete": "Luca Catanzaro",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/324885/thumb.jpg?1566422568",
        "observations_count": 21480,
        "identifications_count": 109080,
        "journal_posts_count": 0,
        "activity_count": 130560,
        "species_count": 2470,
        "universal_search_rank": 21480,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/324885/medium.jpg?1566422568"
      }
    },
    {
      "user_id": 1210028,
      "count": 577,
      "user": {
        "id": 1210028,
        "login": "pynklynx",
        "spam": false,
        "suspended": false,
        "created_at": "2018-09-15T03:55:25+00:00",
        "login_autocomplete": "pynklynx",
        "login_exact": "pynklynx",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1210028/thumb.jpg?1538262214",
        "observations_count": 6673,
        "identifications_count": 74690,
        "journal_posts_count": 0,
        "activity_count": 81363,
        "species_count": 1310,
        "universal_search_rank": 6673,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1210028/medium.jpg?1538262214"
      }
    },
    {
      "user_id": 1168695,
      "count": 530,
      "user": {
        "id": 1168695,
        "login": "trscavo",
        "spam": false,
        "suspended": false,
        "created_at": "2018-08-28T18:14:51+00:00",
        "login_autocomplete": "trscavo",
        "login_exact": "trscavo",
        "name": "Tom Scavo",
        "name_autocomplete": "Tom Scavo",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1168695/thumb.png?1535480090",
        "observations_count": 4541,
        "identifications_count": 30780,
        "journal_posts_count": 0,
        "activity_count": 35321,
        "species_count": 554,
        "universal_search_rank": 4541,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1168695/medium.png?1535480090"
      }
    },
    {
      "user_id": 187480,
      "count": 468,
      "user": {
        "id": 187480,
        "login": "wdvanhem",
        "spam": false,
        "suspended": false,
        "created_at": "2016-03-03T13:54:17+00:00",
        "login_autocomplete": "wdvanhem",
        "login_exact": "wdvanhem",
        "name": "Will Van Hemessen",
        "name_autocomplete": "Will Van Hemessen",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/187480/thumb.jpeg?1586740535",
        "observations_count": 8050,
        "identifications_count": 145345,
        "journal_posts_count": 1,
        "activity_count": 153396,
        "species_count": 2482,
        "universal_search_rank": 8050,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/187480/medium.jpeg?1586740535"
      }
    }
  ]
}

Return type:: Dict[str, Any]
Returns:: Response dict of identifiers

pyinaturalist.v1.observations.get_observation_observers(**params)#

Get observers of observations matching the search criteria and the count of observations and distinct taxa of rank species they have observed.

Notes

API reference: GET /observations/observers
Options for order_by are ‘observation_count’ (default) or ‘species_count’
This endpoint will only return up to 500 results
See this issue for more details: https://github.com/inaturalist/iNaturalistAPI/issues/235

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
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'
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

>>> response = get_observation_observers(place_id=72645, order_by='species_count')
>>> pprint(response)
[1566366 ] fossa1211
[674557  ] schurchin
[5813    ] fluffberger (Fluff Berger)

Example Response

{
  "total_results": 3948,
  "page": 1,
  "per_page": 500,
  "results": [
    {
      "user_id": 15723,
      "observation_count": 2346,
      "species_count": 605,
      "user": {
        "id": 15723,
        "login": "reallifeecology",
        "spam": false,
        "suspended": false,
        "created_at": "2013-04-27T19:32:15+00:00",
        "login_autocomplete": "reallifeecology",
        "login_exact": "reallifeecology",
        "name": "Jonathan (JC) Carpenter",
        "name_autocomplete": "Jonathan (JC) Carpenter",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/15723/thumb.jpg?1475535710",
        "observations_count": 36365,
        "identifications_count": 2086,
        "journal_posts_count": 3,
        "activity_count": 38454,
        "species_count": 5740,
        "universal_search_rank": 36365,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/15723/medium.jpg?1475535710"
      }
    },
    {
      "user_id": 1085809,
      "observation_count": 1125,
      "species_count": 393,
      "user": {
        "id": 1085809,
        "login": "anneturner",
        "spam": false,
        "suspended": false,
        "created_at": "2018-07-14T16:12:14+00:00",
        "login_autocomplete": "anneturner",
        "login_exact": "anneturner",
        "name": "Anne Turner",
        "name_autocomplete": "Anne Turner",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1085809/thumb.jpeg?1555073435",
        "observations_count": 1441,
        "identifications_count": 125,
        "journal_posts_count": 0,
        "activity_count": 1566,
        "species_count": 553,
        "universal_search_rank": 1441,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1085809/medium.jpeg?1555073435"
      }
    },
    {
      "user_id": 53153,
      "observation_count": 890,
      "species_count": 324,
      "user": {
        "id": 53153,
        "login": "willkuhn",
        "spam": false,
        "suspended": false,
        "created_at": "2014-09-15T18:38:59+00:00",
        "login_autocomplete": "willkuhn",
        "login_exact": "willkuhn",
        "name": "Will Kuhn",
        "name_autocomplete": "Will Kuhn",
        "orcid": "https://orcid.org/0000-0002-5506-6379",
        "icon": "https://static.inaturalist.org/attachments/users/icons/53153/thumb.jpeg?1606488424",
        "observations_count": 2945,
        "identifications_count": 3895,
        "journal_posts_count": 0,
        "activity_count": 6840,
        "species_count": 1230,
        "universal_search_rank": 2945,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/53153/medium.jpeg?1606488424"
      }
    },
    {
      "user_id": 176684,
      "observation_count": 806,
      "species_count": 348,
      "user": {
        "id": 176684,
        "login": "gmontgomery",
        "spam": false,
        "suspended": false,
        "created_at": "2016-02-06T21:58:36+00:00",
        "login_autocomplete": "gmontgomery",
        "login_exact": "gmontgomery",
        "name": "Graham Montgomery",
        "name_autocomplete": "Graham Montgomery",
        "orcid": "https://orcid.org/0000-0002-8217-8800",
        "icon": "https://static.inaturalist.org/attachments/users/icons/176684/thumb.jpeg?1600827496",
        "observations_count": 7986,
        "identifications_count": 4072,
        "journal_posts_count": 0,
        "activity_count": 12058,
        "species_count": 4146,
        "universal_search_rank": 7986,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/176684/medium.jpeg?1600827496"
      }
    },
    {
      "user_id": 1019810,
      "observation_count": 791,
      "species_count": 279,
      "user": {
        "id": 1019810,
        "login": "jduffy",
        "spam": false,
        "suspended": false,
        "created_at": "2018-06-11T15:58:21+00:00",
        "login_autocomplete": "jduffy",
        "login_exact": "jduffy",
        "name": "Jim",
        "name_autocomplete": "Jim",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1019810/thumb.jpg?1551496934",
        "observations_count": 823,
        "identifications_count": 2,
        "journal_posts_count": 0,
        "activity_count": 825,
        "species_count": 313,
        "universal_search_rank": 823,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1019810/medium.jpg?1551496934"
      }
    },
    {
      "user_id": 906019,
      "observation_count": 693,
      "species_count": 190,
      "user": {
        "id": 906019,
        "login": "akfishmom",
        "spam": false,
        "suspended": false,
        "created_at": "2018-04-26T20:56:39+00:00",
        "login_autocomplete": "akfishmom",
        "login_exact": "akfishmom",
        "name": null,
        "name_autocomplete": null,
        "orcid": null,
        "icon": null,
        "observations_count": 822,
        "identifications_count": 6,
        "journal_posts_count": 0,
        "activity_count": 828,
        "species_count": 322,
        "universal_search_rank": 822,
        "roles": [],
        "site_id": 1,
        "icon_url": null
      }
    },
    {
      "user_id": 17201,
      "observation_count": 661,
      "species_count": 328,
      "user": {
        "id": 17201,
        "login": "matthewherron",
        "spam": false,
        "suspended": false,
        "created_at": "2013-05-29T02:13:48+00:00",
        "login_autocomplete": "matthewherron",
        "login_exact": "matthewherron",
        "name": "Matthew Herron",
        "name_autocomplete": "Matthew Herron",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/17201/thumb.jpeg?1475536451",
        "observations_count": 7694,
        "identifications_count": 1467,
        "journal_posts_count": 0,
        "activity_count": 9161,
        "species_count": 2195,
        "universal_search_rank": 7694,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/17201/medium.jpeg?1475536451"
      }
    },
    {
      "user_id": 282998,
      "observation_count": 640,
      "species_count": 212,
      "user": {
        "id": 282998,
        "login": "dunhamkc",
        "spam": false,
        "suspended": false,
        "created_at": "2016-08-06T13:19:36+00:00",
        "login_autocomplete": "dunhamkc",
        "login_exact": "dunhamkc",
        "name": "Keely Dunham",
        "name_autocomplete": "Keely Dunham",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/282998/thumb.jpg?1526954269",
        "observations_count": 2418,
        "identifications_count": 725,
        "journal_posts_count": 0,
        "activity_count": 3143,
        "species_count": 796,
        "universal_search_rank": 2418,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/282998/medium.jpg?1526954269"
      }
    },
    {
      "user_id": 843086,
      "observation_count": 562,
      "species_count": 235,
      "user": {
        "id": 843086,
        "login": "b_georgic",
        "spam": false,
        "suspended": false,
        "created_at": "2018-04-10T16:31:49+00:00",
        "login_autocomplete": "b_georgic",
        "login_exact": "b_georgic",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/843086/thumb.jpg?1606070123",
        "observations_count": 1151,
        "identifications_count": 0,
        "journal_posts_count": 0,
        "activity_count": 1151,
        "species_count": 653,
        "universal_search_rank": 1151,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/843086/medium.jpg?1606070123"
      }
    },
    {
      "user_id": 574477,
      "observation_count": 442,
      "species_count": 171,
      "user": {
        "id": 574477,
        "login": "pinus_taeda",
        "spam": false,
        "suspended": false,
        "created_at": "2017-08-10T18:00:10+00:00",
        "login_autocomplete": "pinus_taeda",
        "login_exact": "pinus_taeda",
        "name": null,
        "name_autocomplete": null,
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/574477/thumb.jpg?1527608024",
        "observations_count": 1846,
        "identifications_count": 1141,
        "journal_posts_count": 0,
        "activity_count": 2987,
        "species_count": 551,
        "universal_search_rank": 1846,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/574477/medium.jpg?1527608024"
      }
    },
    {
      "user_id": 2148023,
      "observation_count": 420,
      "species_count": 149,
      "user": {
        "id": 2148023,
        "login": "christopher514",
        "spam": false,
        "suspended": false,
        "created_at": "2019-08-19T02:14:52+00:00",
        "login_autocomplete": "christopher514",
        "login_exact": "christopher514",
        "name": "Christopher Gontarski",
        "name_autocomplete": "Christopher Gontarski",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/2148023/thumb.jpeg?1566180892",
        "observations_count": 567,
        "identifications_count": 0,
        "journal_posts_count": 0,
        "activity_count": 567,
        "species_count": 287,
        "universal_search_rank": 567,
        "roles": [],
        "site_id": null,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/2148023/medium.jpeg?1566180892"
      }
    },
    {
      "user_id": 362446,
      "observation_count": 398,
      "species_count": 237,
      "user": {
        "id": 362446,
        "login": "pwdeacon",
        "spam": false,
        "suspended": false,
        "created_at": "2016-11-02T20:47:19+00:00",
        "login_autocomplete": "pwdeacon",
        "login_exact": "pwdeacon",
        "name": "Pat Deacon",
        "name_autocomplete": "Pat Deacon",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/362446/thumb.jpeg?1575167373",
        "observations_count": 12962,
        "identifications_count": 7883,
        "journal_posts_count": 0,
        "activity_count": 20845,
        "species_count": 3029,
        "universal_search_rank": 12962,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/362446/medium.jpeg?1575167373"
      }
    },
    {
      "user_id": 93979,
      "observation_count": 373,
      "species_count": 23,
      "user": {
        "id": 93979,
        "login": "mcaterino",
        "spam": false,
        "suspended": false,
        "created_at": "2015-04-28T12:18:05+00:00",
        "login_autocomplete": "mcaterino",
        "login_exact": "mcaterino",
        "name": "Michael Caterino",
        "name_autocomplete": "Michael Caterino",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/93979/thumb.jpg?1568554017",
        "observations_count": 1708,
        "identifications_count": 153,
        "journal_posts_count": 0,
        "activity_count": 1861,
        "species_count": 174,
        "universal_search_rank": 1708,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/93979/medium.jpg?1568554017"
      }
    },
    {
      "user_id": 17283,
      "observation_count": 334,
      "species_count": 252,
      "user": {
        "id": 17283,
        "login": "layla",
        "spam": false,
        "suspended": false,
        "created_at": "2013-05-30T20:06:01+00:00",
        "login_autocomplete": "layla",
        "login_exact": "layla",
        "name": "Layla Dishman",
        "name_autocomplete": "Layla Dishman",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/17283/thumb.jpg?1475536494",
        "observations_count": 2831,
        "identifications_count": 1414,
        "journal_posts_count": 0,
        "activity_count": 4245,
        "universal_search_rank": 2831,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/17283/medium.jpg?1475536494"
      }
    },
    {
      "user_id": 2346515,
      "observation_count": 317,
      "species_count": 77,
      "user": {
        "id": 2346515,
        "login": "sarahroth",
        "spam": false,
        "suspended": false,
        "created_at": "2019-10-08T15:37:36+00:00",
        "login_autocomplete": "sarahroth",
        "login_exact": "sarahroth",
        "name": "Sarah Roth",
        "name_autocomplete": "Sarah Roth",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/2346515/thumb.png?1570549056",
        "observations_count": 473,
        "identifications_count": 0,
        "journal_posts_count": 0,
        "activity_count": 473,
        "species_count": 126,
        "universal_search_rank": 473,
        "roles": [],
        "site_id": null,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/2346515/medium.png?1570549056"
      }
    },
    {
      "user_id": 159616,
      "observation_count": 314,
      "species_count": 149,
      "user": {
        "id": 159616,
        "login": "cdance",
        "spam": false,
        "suspended": false,
        "created_at": "2015-12-09T19:36:11+00:00",
        "login_autocomplete": "cdance",
        "login_exact": "cdance",
        "name": "CDance",
        "name_autocomplete": "CDance",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/159616/thumb.jpg?1566762916",
        "observations_count": 2900,
        "identifications_count": 264,
        "journal_posts_count": 3,
        "activity_count": 3167,
        "species_count": 1165,
        "universal_search_rank": 2900,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/159616/medium.jpg?1566762916"
      }
    },
    {
      "user_id": 1359300,
      "observation_count": 310,
      "species_count": 148,
      "user": {
        "id": 1359300,
        "login": "spyingnaturalist",
        "spam": false,
        "suspended": false,
        "created_at": "2018-11-20T01:19:01+00:00",
        "login_autocomplete": "spyingnaturalist",
        "login_exact": "spyingnaturalist",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1359300/thumb.jpg?1552909758",
        "observations_count": 8286,
        "identifications_count": 5371,
        "journal_posts_count": 0,
        "activity_count": 13657,
        "species_count": 2749,
        "universal_search_rank": 8286,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1359300/medium.jpg?1552909758"
      }
    },
    {
      "user_id": 899236,
      "observation_count": 292,
      "species_count": 177,
      "user": {
        "id": 899236,
        "login": "palustris314",
        "spam": false,
        "suspended": false,
        "created_at": "2018-04-25T17:22:45+00:00",
        "login_autocomplete": "palustris314",
        "login_exact": "palustris314",
        "name": "Greg J Schmidt",
        "name_autocomplete": "Greg J Schmidt",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/899236/thumb.jpg?1526651056",
        "observations_count": 1599,
        "identifications_count": 139,
        "journal_posts_count": 0,
        "activity_count": 1738,
        "species_count": 1013,
        "universal_search_rank": 1599,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/899236/medium.jpg?1526651056"
      }
    },
    {
      "user_id": 187480,
      "observation_count": 252,
      "species_count": 172,
      "user": {
        "id": 187480,
        "login": "wdvanhem",
        "spam": false,
        "suspended": false,
        "created_at": "2016-03-03T13:54:17+00:00",
        "login_autocomplete": "wdvanhem",
        "login_exact": "wdvanhem",
        "name": "Will Van Hemessen",
        "name_autocomplete": "Will Van Hemessen",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/187480/thumb.jpeg?1586740535",
        "observations_count": 8050,
        "identifications_count": 145345,
        "journal_posts_count": 1,
        "activity_count": 153396,
        "species_count": 2482,
        "universal_search_rank": 8050,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/187480/medium.jpeg?1586740535"
      }
    }
  ]
}

Return type:: Dict[str, Any]
Returns:: Response dict of observers

pyinaturalist.v1.observations.get_observation_popular_field_values(**params)#

Get controlled terms values and a monthly histogram of observations matching the search criteria.

Notes

API reference: GET /observations/popular_field_values

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
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

>>> response = get_observation_popular_field_values(
...     species_name='Danaus plexippus', place_id=24,
... )

Example Response

{
    'total_results': 10,
    'page': 1,
    'per_page': 10,
    'results': [
        {
            'count': 231,
            'month_of_year': {
                1: 0,
                2: 0,
                3: 0,
                4: 1,
                5: 21,
                6: 38,
                7: 33,
                8: 47,
                9: 62,
                10: 29,
                11: 0,
                12: 0,
            },
            'controlled_attribute': {
                'id': 1,
                'ontology_uri': '',
                'uri': '',
                'is_value': False,
                'multivalued': False,
                'uuid': 'f895e9ce-fb2d-4a63-a486-ac424f497e02',
                'values': [
                    {
                        'id': 2,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '48722062-360d-4b6e-b72c-129c7066b3fa',
                        'taxon_ids': [1],
                        'label': 'Adult',
                    },
                    {
                        'id': 3,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': 'b3b6e6d0-cbce-4886-bb2b-55bd99d44586',
                        'taxon_ids': [47792, 50190],
                        'label': 'Teneral',
                    },
                    {
                        'id': 4,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': 'c883d7b5-4eb5-4ad1-8cbc-56f5e2555869',
                        'taxon_ids': [
                            47208,
                            48763,
                            49369,
                            47157,
                            47822,
                            47201,
                            62164,
                            47864,
                            83204,
                            83202,
                            47794,
                        ],
                        'label': 'Pupa',
                    },
                    {
                        'id': 5,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '0f0c03c2-4741-46db-a19a-7cac8a96d667',
                        'taxon_ids': [
                            47793,
                            81769,
                            56834,
                            47744,
                            47792,
                            47651,
                            47504,
                            48011,
                            48112,
                            53795,
                            47198,
                            83187,
                            83201,
                            83200,
                        ],
                        'label': 'Nymph',
                    },
                    {
                        'id': 6,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '8ff477bd-0949-4a7a-9c67-64a8e3786876',
                        'taxon_ids': [
                            20978,
                            47208,
                            47822,
                            47201,
                            47157,
                            49369,
                            47864,
                            48763,
                            47794,
                            83204,
                            83202,
                            62164,
                        ],
                        'label': 'Larva',
                    },
                    {
                        'id': 7,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': 'fe58aedb-4375-4096-a61f-1cd718cf319f',
                        'taxon_ids': [
                            43233,
                            47120,
                            85497,
                            47178,
                            20978,
                            3,
                            49231,
                            47273,
                            60450,
                            49099,
                            26036,
                            47115,
                        ],
                        'label': 'Egg',
                    },
                    {
                        'id': 8,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '3245d167-ffff-44ce-a366-cfc8f711d73f',
                        'taxon_ids': [1],
                        'excepted_taxon_ids': [184884],
                        'label': 'Juvenile',
                    },
                    {
                        'id': 16,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '6ff4f9f8-7bc0-4d50-bee5-7072d11a04ef',
                        'taxon_ids': [48011],
                        'label': 'Subimago',
                    },
                ],
                'taxon_ids': [1],
                'excepted_taxon_ids': [43583],
                'label': 'Life Stage',
            },
            'controlled_value': {
                'id': 2,
                'ontology_uri': '',
                'uri': '',
                'is_value': True,
                'blocking': False,
                'taxon_ids': [1],
                'label': 'Adult',
                'values': [],
            },
        },
        {
            'count': 150,
            'month_of_year': {
                1: 0,
                2: 0,
                3: 0,
                4: 0,
                5: 0,
                6: 59,
                7: 27,
                8: 40,
                9: 24,
                10: 0,
                11: 0,
                12: 0,
            },
            'controlled_attribute': {
                'id': 1,
                'ontology_uri': '',
                'uri': '',
                'is_value': False,
                'multivalued': False,
                'uuid': 'f895e9ce-fb2d-4a63-a486-ac424f497e02',
                'values': [
                    {
                        'id': 2,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '48722062-360d-4b6e-b72c-129c7066b3fa',
                        'taxon_ids': [1],
                        'label': 'Adult',
                    },
                    {
                        'id': 3,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': 'b3b6e6d0-cbce-4886-bb2b-55bd99d44586',
                        'taxon_ids': [47792, 50190],
                        'label': 'Teneral',
                    },
                    {
                        'id': 4,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': 'c883d7b5-4eb5-4ad1-8cbc-56f5e2555869',
                        'taxon_ids': [
                            47208,
                            48763,
                            49369,
                            47157,
                            47822,
                            47201,
                            62164,
                            47864,
                            83204,
                            83202,
                            47794,
                        ],
                        'label': 'Pupa',
                    },
                    {
                        'id': 5,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '0f0c03c2-4741-46db-a19a-7cac8a96d667',
                        'taxon_ids': [
                            47793,
                            81769,
                            56834,
                            47744,
                            47792,
                            47651,
                            47504,
                            48011,
                            48112,
                            53795,
                            47198,
                            83187,
                            83201,
                            83200,
                        ],
                        'label': 'Nymph',
                    },
                    {
                        'id': 6,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '8ff477bd-0949-4a7a-9c67-64a8e3786876',
                        'taxon_ids': [
                            20978,
                            47208,
                            47822,
                            47201,
                            47157,
                            49369,
                            47864,
                            48763,
                            47794,
                            83204,
                            83202,
                            62164,
                        ],
                        'label': 'Larva',
                    },
                    {
                        'id': 7,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': 'fe58aedb-4375-4096-a61f-1cd718cf319f',
                        'taxon_ids': [
                            43233,
                            47120,
                            85497,
                            47178,
                            20978,
                            3,
                            49231,
                            47273,
                            60450,
                            49099,
                            26036,
                            47115,
                        ],
                        'label': 'Egg',
                    },
                    {
                        'id': 8,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '3245d167-ffff-44ce-a366-cfc8f711d73f',
                        'taxon_ids': [1],
                        'excepted_taxon_ids': [184884],
                        'label': 'Juvenile',
                    },
                    {
                        'id': 16,
                        'ontology_uri': '',
                        'uri': '',
                        'blocking': False,
                        'uuid': '6ff4f9f8-7bc0-4d50-bee5-7072d11a04ef',
                        'taxon_ids': [48011],
                        'label': 'Subimago',
                    },
                ],
                'taxon_ids': [1],
                'excepted_taxon_ids': [43583],
                'label': 'Life Stage',
            },
            'controlled_value': {
                'id': 6,
                'ontology_uri': '',
                'uri': '',
                'is_value': True,
                'blocking': False,
                'taxon_ids': [
                    20978,
                    47208,
                    47822,
                    47201,
                    47157,
                    49369,
                    47864,
                    48763,
                    47794,
                    83204,
                    83202,
                    62164,
                ],
                'label': 'Larva',
                'values': [],
            },
        },
    ],
}

Return type:: Dict[str, Any]
Returns:: Response dict. Each record contains a count, a month_of_year histogram, a controlled_attribute, and a controlled_value.

pyinaturalist.v1.observations.get_observation_species_counts(**params)#

Get all species (or other ‘leaf taxa’) associated with observations matching the search criteria, and the count of observations they are associated with.

Notes

API reference: GET /observations/species_counts
Leaf taxa are the leaves of the taxonomic tree, e.g., species, subspecies, variety, etc.

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
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'
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

>>> response = get_observation_species_counts(user_login='my_username', quality_grade='research')
>>> pprint(response)
[62060] Species: Palomena prasina (Green Shield Bug): 10
[84804] Species: Graphosoma italicum (European Striped Shield Bug): 8
[55727] Species: Cymbalaria muralis (Ivy-leaved toadflax): 3
...

Example Response

{
    'total_results': 243,
    'page': 1,
    'per_page': 500,
    'results': [
        {
            'count': 31,
            'taxon': {
                'observations_count': 81696,
                'taxon_schemes_count': 2,
                'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/471714/48486/333790/333796/48487',
                'is_active': True,
                'flag_counts': {'unresolved': 0, 'resolved': 3},
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Harmonia_axyridis',
                'current_synonymous_taxon_ids': None,
                'iconic_taxon_id': 47158,
                'rank_level': 10,
                'taxon_changes_count': 1,
                'atlas_id': 1241,
                'complete_species_count': None,
                'parent_id': 48487,
                'name': 'Harmonia axyridis',
                'rank': 'species',
                'extinct': False,
                'id': 48484,
                'default_photo': {
                    'square_url': 'https://static.inaturalist.org/photos/30978499/square.jpg?1549228178',
                    'attribution': '(c) Paolo Mazzei, all rights reserved',
                    'flags': [],
                    'medium_url': 'https://static.inaturalist.org/photos/30978499/medium.jpg?1549228178',
                    'id': 30978499,
                    'license_code': None,
                    'original_dimensions': {'width': 800, 'height': 600},
                    'url': 'https://static.inaturalist.org/photos/30978499/square.jpg?1549228178',
                },
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47208,
                    71130,
                    372852,
                    471714,
                    48486,
                    333790,
                    333796,
                    48487,
                    48484,
                ],
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Asian Lady Beetle',
            },
        },
        {
            'count': 19,
            'taxon': {
                'observations_count': 43187,
                'taxon_schemes_count': 3,
                'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/471714/48486/333790/333796/51703',
                'is_active': True,
                'flag_counts': {'unresolved': 0, 'resolved': 1},
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Coccinella_septempunctata',
                'current_synonymous_taxon_ids': None,
                'iconic_taxon_id': 47158,
                'rank_level': 10,
                'taxon_changes_count': 1,
                'atlas_id': None,
                'complete_species_count': None,
                'parent_id': 51703,
                'name': 'Coccinella septempunctata',
                'rank': 'species',
                'extinct': False,
                'id': 51702,
                'default_photo': {
                    'square_url': 'https://static.inaturalist.org/photos/5669923/square.jpg?1480658715',
                    'attribution': '(c) Katja Schulz, some rights reserved (CC BY)',
                    'flags': [],
                    'medium_url': 'https://static.inaturalist.org/photos/5669923/medium.jpg?1480658715',
                    'id': 5669923,
                    'license_code': 'cc-by',
                    'original_dimensions': {'width': 2048, 'height': 1536},
                    'url': 'https://static.inaturalist.org/photos/5669923/square.jpg?1480658715',
                },
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47208,
                    71130,
                    372852,
                    471714,
                    48486,
                    333790,
                    333796,
                    51703,
                    51702,
                ],
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Seven-spotted Lady Beetle',
            },
        },
    ],
}

Return type:: Dict[str, Any]
Returns:: Response dict containing taxon records with counts

pyinaturalist.v1.observations.get_observation_taxon_summary(observation_id, **params)#

Get information about an observation’s taxon, within the context of the observation’s location

Notes

API reference: GET /observations/{id}/taxon_summary

Parameters:

observation_id (int) – Observation ID to get taxon summary for
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

>>> response = get_observation_taxon_summary(7849808)

Return type:: Dict[str, Any]
Returns:: Response dict containing taxon summary, optionally with conservation status and listed taxon

pyinaturalist.v1.observations.get_observation_taxonomy(**params)#

Get observation counts for all taxa in observations matching the search criteria.

Notes

Undocumented in API reference
On iNaturalist.org, this is mainly used for dynamic life lists
Results are returned in a flat list, but are ordered as they would be in a taxonomic tree

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
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

>>> response = get_observation_taxonomy(user_id='my_username')

Return type:: Dict[str, Any]
Returns:: Response dict containing taxon records with counts

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

Search observations

Notes

Optional authentication (For private/obscured coordinates)
API reference: GET /observations

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
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):

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

Get basic info for observations in response:

>>> pprint(response)
ID       Taxon ID Taxon                       Observed on   User      Location
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
57707611 48662    Danaus plexippus (Monarch)  Aug 26, 2020  ingridt3  Michener Dr, Regina, SK, CA
57754375 48662    Danaus plexippus (Monarch)  Aug 27, 2020  samroom   Railway Ave, Wilcox, SK, CA

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

from datetime import datetime

from dateutil.tz import tzoffset, tzutc

{
    'total_results': 2,
    'page': 1,
    'per_page': 30,
    'results': [
        {
            'quality_grade': 'research',
            'time_observed_at': '2020-08-27T08:57:22+00:00',
            'taxon_geoprivacy': 'open',
            'annotations': [],
            'uuid': 'c44b91f3-534d-48c4-933d-a8b4e1d8f87b',
            'id': 57754375,
            'cached_votes_total': 0,
            'identifications_most_agree': True,
            'species_guess': 'Monarch',
            'identifications_most_disagree': False,
            'tags': [],
            'positional_accuracy': None,
            'comments_count': 2,
            'site_id': 5,
            'license_code': 'cc-by-nc',
            'quality_metrics': [],
            'public_positional_accuracy': None,
            'reviewed_by': [115129, 2852555],
            'oauth_application_id': 3,
            'flags': [],
            'created_at': datetime(2020, 8, 27, 18, 0, 51, tzinfo=tzutc()),
            'description': None,
            'project_ids_with_curator_id': [],
            'updated_at': datetime(2020, 8, 28, 12, 4, 18, tzinfo=tzutc()),
            'sounds': [],
            'place_ids': [
                6712,
                7953,
                9853,
                49224,
                59613,
                64422,
                64423,
                66741,
                78395,
                82256,
                97394,
                145030,
                155145,
                164401,
            ],
            'captive': False,
            'taxon': {
                'is_active': True,
                'ancestry': '48460/1/47120/372739/47158/184884/47157/47224/47922/61244/134169/522900/48663',
                'min_species_ancestry': '48460,1,47120,372739,47158,184884,47157,47224,47922,61244,134169,522900,48663,48662',
                'endemic': False,
                'iconic_taxon_id': 47158,
                'min_species_taxon_id': 48662,
                'threatened': True,
                'rank_level': 10,
                'introduced': False,
                'native': True,
                'parent_id': 48663,
                'name': 'Danaus plexippus',
                'rank': 'species',
                'extinct': False,
                'id': 48662,
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47157,
                    47224,
                    47922,
                    61244,
                    134169,
                    522900,
                    48663,
                    48662,
                ],
                'photos_locked': False,
                'taxon_schemes_count': 6,
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Monarch_butterfly',
                'current_synonymous_taxon_ids': None,
                'created_at': '2008-10-26T20:24:33+00:00',
                'taxon_changes_count': 1,
                'complete_species_count': None,
                'universal_search_rank': 131627,
                'observations_count': 131627,
                'flag_counts': {'unresolved': 1, 'resolved': 7},
                'atlas_id': 1231,
                'default_photo': {
                    'square_url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684',
                    'attribution': '(c) fam-esquivel, some rights reserved (CC BY-NC)',
                    'flags': [],
                    'medium_url': 'https://static.inaturalist.org/photos/13824507/medium.jpg?1545715684',
                    'id': 13824507,
                    'license_code': 'cc-by-nc',
                    'original_dimensions': {'width': 2048, 'height': 1361},
                    'url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684',
                },
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Monarch',
                'conservation_status': {
                    'user_id': None,
                    'status_name': 'imperiled',
                    'iucn': 40,
                    'authority': 'NatureServe',
                    'geoprivacy': None,
                    'source_id': 8,
                    'place_id': 7953,
                    'status': 's2b',
                },
            },
            'ident_taxon_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47157,
                47224,
                47922,
                61244,
                134169,
                522900,
                48663,
                48662,
            ],
            'outlinks': [{'source': 'GBIF', 'url': 'http://www.gbif.org/occurrence/2856816457'}],
            'faves_count': 0,
            'ofvs': [],
            'num_identification_agreements': 1,
            'preferences': {'prefers_community_taxon': None},
            'comments': [
                {
                    'moderator_actions': [],
                    'hidden': False,
                    'flags': [],
                    'created_at': '2020-08-28T12:04:18.407Z',
                    'id': 5326888,
                    'created_at_details': {
                        'date': '2020-08-28',
                        'week': 35,
                        'month': 8,
                        'hour': 12,
                        'year': 2020,
                        'day': 28,
                    },
                    'body': 'Thankyou ',
                    'uuid': 'b4d00be4-132d-4e51-bfdd-8515a00f161c',
                    'user': {
                        'created_at': '2020-04-26T15:26:56+00:00',
                        'id': 2852555,
                        'login': 'samroom',
                        'spam': False,
                        'suspended': False,
                        'login_autocomplete': 'samroom',
                        'login_exact': 'samroom',
                        'name': None,
                        'name_autocomplete': None,
                        'orcid': None,
                        'icon': None,
                        'observations_count': 59,
                        'identifications_count': 0,
                        'journal_posts_count': 0,
                        'activity_count': 59,
                        'species_count': 52,
                        'universal_search_rank': 59,
                        'roles': [],
                        'site_id': 5,
                        'icon_url': None,
                    },
                },
                {
                    'moderator_actions': [],
                    'hidden': False,
                    'flags': [],
                    'created_at': '2020-08-28T04:54:19.020Z',
                    'id': 5325706,
                    'created_at_details': {
                        'date': '2020-08-28',
                        'week': 35,
                        'month': 8,
                        'hour': 4,
                        'year': 2020,
                        'day': 28,
                    },
                    'body': 'Neat photo! ',
                    'uuid': '25ac67d5-ba09-47a8-91e3-b6e3590a0b72',
                    'user': {
                        'created_at': '2018-03-18T01:34:25+00:00',
                        'id': 792847,
                        'login': 'ingridt3',
                        'spam': False,
                        'suspended': False,
                        'login_autocomplete': 'ingridt3',
                        'login_exact': 'ingridt3',
                        'name': None,
                        'name_autocomplete': None,
                        'orcid': None,
                        'icon': None,
                        'observations_count': 51,
                        'identifications_count': 29,
                        'journal_posts_count': 0,
                        'activity_count': 80,
                        'species_count': 30,
                        'universal_search_rank': 51,
                        'roles': [],
                        'site_id': 5,
                        'icon_url': None,
                    },
                },
            ],
            'map_scale': None,
            'uri': 'https://www.inaturalist.org/observations/57754375',
            'project_ids': [],
            'community_taxon_id': 48662,
            'geojson': {'coordinates': [-104.71929167, 50.0949055], 'type': 'Point'},
            'owners_identification_from_vision': True,
            'identifications_count': 1,
            'obscured': False,
            'num_identification_disagreements': 0,
            'geoprivacy': None,
            'location': [50.0949055, -104.71929167],
            'votes': [],
            'spam': False,
            'user': {
                'site_id': 5,
                'created_at': '2020-04-26T15:26:56+00:00',
                'id': 2852555,
                'login': 'samroom',
                'spam': False,
                'suspended': False,
                'preferences': {},
                'login_autocomplete': 'samroom',
                'login_exact': 'samroom',
                'name': None,
                'name_autocomplete': None,
                'orcid': None,
                'icon': None,
                'observations_count': 59,
                'identifications_count': 0,
                'journal_posts_count': 0,
                'activity_count': 59,
                'species_count': 52,
                'universal_search_rank': 59,
                'roles': [],
                'icon_url': None,
            },
            'mappable': True,
            'identifications_some_agree': True,
            'project_ids_without_curator_id': [],
            'place_guess': 'Railway Ave, Wilcox, SK, CA',
            'identifications': 'TRUNCATED',
            'project_observations': [],
            'photos': [
                {
                    'id': 92152429,
                    'license_code': 'cc-by-nc',
                    'url': 'https://static.inaturalist.org/photos/92152429/square.jpg?1598551272',
                    'attribution': '(c) samroom, some rights reserved (CC BY-NC)',
                    'original_dimensions': {'width': 1188, 'height': 1188},
                    'flags': [],
                }
            ],
            'observation_photos': [
                {
                    'id': 85887066,
                    'position': 0,
                    'uuid': '6f73a9f2-019f-4566-a393-2c2242a3198d',
                    'photo': {
                        'id': 92152429,
                        'license_code': 'cc-by-nc',
                        'url': 'https://static.inaturalist.org/photos/92152429/square.jpg?1598551272',
                        'attribution': '(c) samroom, some rights reserved (CC BY-NC)',
                        'original_dimensions': {'width': 1188, 'height': 1188},
                        'flags': [],
                    },
                }
            ],
            'faves': [],
            'non_owner_ids': 'TRUNCATED',
            'observed_on': datetime(2020, 8, 27, 8, 57, 22, tzinfo=tzoffset('Etc/UTC', 0)),
        },
        {
            'quality_grade': 'research',
            'time_observed_at': '2020-08-26T22:46:10+00:00',
            'taxon_geoprivacy': 'open',
            'annotations': [],
            'uuid': '588c9ad4-c747-497c-a52f-bf856c30d2ff',
            'id': 57707611,
            'cached_votes_total': 0,
            'identifications_most_agree': True,
            'species_guess': 'Monarch',
            'identifications_most_disagree': False,
            'tags': [],
            'positional_accuracy': 374,
            'comments_count': 0,
            'site_id': 5,
            'license_code': None,
            'quality_metrics': [],
            'public_positional_accuracy': 374,
            'reviewed_by': [35013, 115129, 217571, 412189, 792847, 2173064],
            'oauth_application_id': 3,
            'flags': [],
            'created_at': datetime(2020, 8, 27, 4, 50, 17, tzinfo=tzutc()),
            'description': 'Only one today and likely the last one to eclose from the batch of caterpillars from 10-14 days ago. ',
            'project_ids_with_curator_id': [6905],
            'updated_at': datetime(2020, 11, 2, 19, 26, 40, tzinfo=tzutc()),
            'sounds': [],
            'place_ids': [
                6712,
                7953,
                9853,
                49224,
                59613,
                64422,
                64423,
                66741,
                78395,
                82256,
                97394,
                113642,
                120614,
                120671,
                145030,
                155145,
                164401,
            ],
            'captive': False,
            'taxon': {
                'is_active': True,
                'ancestry': '48460/1/47120/372739/47158/184884/47157/47224/47922/61244/134169/522900/48663',
                'min_species_ancestry': '48460,1,47120,372739,47158,184884,47157,47224,47922,61244,134169,522900,48663,48662',
                'endemic': False,
                'iconic_taxon_id': 47158,
                'min_species_taxon_id': 48662,
                'threatened': True,
                'rank_level': 10,
                'introduced': False,
                'native': True,
                'parent_id': 48663,
                'name': 'Danaus plexippus',
                'rank': 'species',
                'extinct': False,
                'id': 48662,
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47157,
                    47224,
                    47922,
                    61244,
                    134169,
                    522900,
                    48663,
                    48662,
                ],
                'photos_locked': False,
                'taxon_schemes_count': 6,
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Monarch_butterfly',
                'current_synonymous_taxon_ids': None,
                'created_at': '2008-10-26T20:24:33+00:00',
                'taxon_changes_count': 1,
                'complete_species_count': None,
                'universal_search_rank': 131627,
                'observations_count': 131627,
                'flag_counts': {'unresolved': 1, 'resolved': 7},
                'atlas_id': 1231,
                'default_photo': {
                    'square_url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684',
                    'attribution': '(c) fam-esquivel, some rights reserved (CC BY-NC)',
                    'flags': [],
                    'medium_url': 'https://static.inaturalist.org/photos/13824507/medium.jpg?1545715684',
                    'id': 13824507,
                    'license_code': 'cc-by-nc',
                    'original_dimensions': {'width': 2048, 'height': 1361},
                    'url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684',
                },
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Monarch',
                'conservation_status': {
                    'user_id': None,
                    'status_name': 'imperiled',
                    'iucn': 40,
                    'authority': 'NatureServe',
                    'geoprivacy': None,
                    'source_id': 8,
                    'place_id': 7953,
                    'status': 's2b',
                },
            },
            'ident_taxon_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47157,
                47224,
                47922,
                61244,
                134169,
                522900,
                48663,
                48662,
            ],
            'outlinks': [],
            'faves_count': 0,
            'ofvs': [],
            'num_identification_agreements': 5,
            'preferences': {'prefers_community_taxon': None},
            'comments': [],
            'map_scale': None,
            'uri': 'https://www.inaturalist.org/observations/57707611',
            'project_ids': [6905],
            'community_taxon_id': 48662,
            'geojson': {'coordinates': [-104.5628221383, 50.433418274], 'type': 'Point'},
            'owners_identification_from_vision': True,
            'identifications_count': 5,
            'obscured': False,
            'num_identification_disagreements': 0,
            'geoprivacy': None,
            'location': [50.433418274, -104.5628221383],
            'votes': [],
            'spam': False,
            'user': {
                'site_id': 5,
                'created_at': '2018-03-18T01:34:25+00:00',
                'id': 792847,
                'login': 'ingridt3',
                'spam': False,
                'suspended': False,
                'preferences': {},
                'login_autocomplete': 'ingridt3',
                'login_exact': 'ingridt3',
                'name': None,
                'name_autocomplete': None,
                'orcid': None,
                'icon': None,
                'observations_count': 51,
                'identifications_count': 29,
                'journal_posts_count': 0,
                'activity_count': 80,
                'species_count': 30,
                'universal_search_rank': 51,
                'roles': [],
                'icon_url': None,
            },
            'mappable': True,
            'identifications_some_agree': True,
            'project_ids_without_curator_id': [],
            'place_guess': 'Michener Dr, Regina, SK, CA',
            'identifications': 'TRUNCATED',
            'project_observations': [
                {
                    'id': 45561247,
                    'uuid': '912138ca-651d-4d5f-99c1-d89e9c023bb5',
                    'project': {'id': 6905},
                    'user_id': 35013,
                    'preferences': {'allows_curator_coordinate_access': True},
                    'user': {
                        'id': 35013,
                        'login': 'a_b',
                        'spam': False,
                        'suspended': False,
                        'created_at': '2014-04-09T03:27:04+00:00',
                        'login_autocomplete': 'a_b',
                        'login_exact': 'a_b',
                        'name': 'Andrea Benville',
                        'name_autocomplete': 'Andrea Benville',
                        'orcid': None,
                        'icon': 'https://static.inaturalist.org/attachments/users/icons/35013/thumb.jpg?1505750038',
                        'observations_count': 787,
                        'identifications_count': 533,
                        'journal_posts_count': 0,
                        'activity_count': 1320,
                        'species_count': 432,
                        'universal_search_rank': 787,
                        'roles': [],
                        'site_id': 5,
                        'icon_url': 'https://static.inaturalist.org/attachments/users/icons/35013/medium.jpg?1505750038',
                    },
                }
            ],
            'photos': [
                {
                    'id': 92075215,
                    'license_code': None,
                    'url': 'https://static.inaturalist.org/photos/92075215/square.jpg?1598503820',
                    'attribution': '(c) ingridt3, all rights reserved',
                    'original_dimensions': {'width': 1183, 'height': 842},
                    'flags': [],
                }
            ],
            'observation_photos': [
                {
                    'id': 85814399,
                    'position': 0,
                    'uuid': '98dd67ae-79b4-49c6-934b-6a814ea6d6ab',
                    'photo': {
                        'id': 92075215,
                        'license_code': None,
                        'url': 'https://static.inaturalist.org/photos/92075215/square.jpg?1598503820',
                        'attribution': '(c) ingridt3, all rights reserved',
                        'original_dimensions': {'width': 1183, 'height': 842},
                        'flags': [],
                    },
                }
            ],
            'faves': [],
            'non_owner_ids': 'TRUNCATED',
            'observed_on': datetime(2020, 8, 26, 22, 46, 10, tzinfo=tzoffset('Etc/UTC', 0)),
        },
    ],
}

pyinaturalist.v1.observations.get_observations_by_id(observation_id, access_token=None, **params)#

Get one or more observations by ID

Notes

Optional authentication (For private/obscured coordinates)
API reference: GET /observations/{id}
This endpoint returns more complete annotation details compared to get_observations(). See Annotation for details.

Parameters:

observation_id (Union[int, Iterable[int]]) – Get an observation with this ID. Multiple IDs are allowed.
access_token (Optional[str]) – An access token, 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

Example

>>> response = get_observations_by_id(16227955)
>>> response = get_observations_by_id([16227955, 16227956])

Example Response

from datetime import datetime

from dateutil.tz import tzoffset

{
    'total_results': 1,
    'page': 1,
    'per_page': 1,
    'results': [
        {
            'id': 16227955,
            'annotations': [
                {
                    'concatenated_attr_val': '1|2',
                    'controlled_attribute_id': 1,
                    'controlled_value_id': 2,
                    'user': {
                        'activity_count': 1184,
                        'created_at': '2018-04-23T17:11:14+00:00',
                        'icon': 'https://static.inaturalist.org/attachments/users/icons/886482/thumb.jpg?1529671435',
                        'icon_url': 'https://static.inaturalist.org/attachments/users/icons/886482/medium.jpg?1529671435',
                        'id': 886482,
                        'identifications_count': 120,
                        'journal_posts_count': 0,
                        'login': 'niconoe',
                        'login_autocomplete': 'niconoe',
                        'login_exact': 'niconoe',
                        'name': 'Nicolas Noé',
                        'name_autocomplete': 'Nicolas Noé',
                        'observations_count': 1064,
                        'orcid': 'https://orcid.org/0000-0002-9503-4750',
                        'roles': [],
                        'site_id': 1,
                        'spam': False,
                        'species_count': 471,
                        'suspended': False,
                        'universal_search_rank': 1064,
                    },
                    'user_id': 886482,
                    'uuid': '14bbd34f-73f8-4b99-b591-8517913788a1',
                    'vote_score': 0,
                    'votes': [],
                }
            ],
            'cached_votes_total': 0,
            'captive': False,
            'comments': [
                {
                    'body': 'suspect L. bardanae - but sits on Solanum (non-host)',
                    'created_at': '2018-09-05T14:08:09+00:00',
                    'created_at_details': {
                        'date': '2018-09-05',
                        'day': 5,
                        'hour': 14,
                        'month': 9,
                        'week': 36,
                        'year': 2018,
                    },
                    'flags': [],
                    'hidden': False,
                    'id': 2071611,
                    'moderator_actions': [],
                    'user': {
                        'activity_count': 503804,
                        'created_at': '2016-02-18T10:19:19+00:00',
                        'icon': None,
                        'icon_url': None,
                        'id': 180811,
                        'identifications_count': 503804,
                        'journal_posts_count': 0,
                        'login': 'borisb',
                        'login_autocomplete': 'borisb',
                        'login_exact': 'borisb',
                        'name': '',
                        'name_autocomplete': '',
                        'observations_count': 0,
                        'orcid': None,
                        'roles': ['curator'],
                        'site_id': 1,
                        'spam': False,
                        'species_count': 0,
                        'suspended': False,
                        'universal_search_rank': 0,
                    },
                    'uuid': 'e6fc62ea-e22b-4427-bb65-1ba3bc591c77',
                },
                {
                    'body': 'I now see: Bonus species on observation! You may make '
                    'a duplicate . . . \n'
                    '(Flea beetle Epitrix pubescens on Solanum bud) \n',
                    'created_at': '2018-09-05T16:03:40+00:00',
                    'created_at_details': {
                        'date': '2018-09-05',
                        'day': 5,
                        'hour': 16,
                        'month': 9,
                        'week': 36,
                        'year': 2018,
                    },
                    'flags': [],
                    'hidden': False,
                    'id': 2071896,
                    'moderator_actions': [],
                    'user': {
                        'activity_count': 503804,
                        'created_at': '2016-02-18T10:19:19+00:00',
                        'icon': None,
                        'icon_url': None,
                        'id': 180811,
                        'identifications_count': 503804,
                        'journal_posts_count': 0,
                        'login': 'borisb',
                        'login_autocomplete': 'borisb',
                        'login_exact': 'borisb',
                        'name': '',
                        'name_autocomplete': '',
                        'observations_count': 0,
                        'orcid': None,
                        'roles': ['curator'],
                        'site_id': 1,
                        'spam': False,
                        'species_count': 0,
                        'suspended': False,
                        'universal_search_rank': 0,
                    },
                    'uuid': '4d401d20-1b08-464a-8287-351f5b57443e',
                },
            ],
            'comments_count': 2,
            'community_taxon_id': 493595,
            'created_at': datetime(2018, 9, 5, 14, 31, 8, tzinfo=tzoffset(None, 7200)),
            'created_at_details': {
                'date': '2018-09-05',
                'day': 5,
                'hour': 14,
                'month': 9,
                'week': 36,
                'year': 2018,
            },
            'created_time_zone': 'Europe/Paris',
            'description': '',
            'faves': [],
            'faves_count': 0,
            'flags': [],
            'geojson': {'coordinates': [4.360086, 50.646894], 'type': 'Point'},
            'geoprivacy': None,
            'ident_taxon_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47208,
                71130,
                372852,
                60473,
                48736,
                272543,
                507383,
                71157,
                1101667,
                493595,
            ],
            'identifications': 'TRUNCATED',
            'identifications_count': 2,
            'identifications_most_agree': True,
            'identifications_most_disagree': False,
            'identifications_some_agree': True,
            'license_code': 'cc0',
            'location': [50.646894, 4.360086],
            'map_scale': 17,
            'mappable': True,
            'non_owner_ids': 'TRUNCATED',
            'num_identification_agreements': 2,
            'num_identification_disagreements': 0,
            'oauth_application_id': None,
            'obscured': False,
            'observation_photos': [
                {
                    'id': 22080796,
                    'photo': {
                        'attribution': '(c) Nicolas Noé, some ' 'rights reserved (CC BY)',
                        'flags': [],
                        'id': 24355315,
                        'license_code': 'cc-by',
                        'original_dimensions': {'height': 1057, 'width': 1445},
                        'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/24355315/square.jpeg',
                    },
                    'position': 0,
                    'uuid': '76b54495-3497-4e96-b07c-7ad346939a02',
                },
                {
                    'id': 22080797,
                    'photo': {
                        'attribution': '(c) Nicolas Noé, some ' 'rights reserved (CC BY)',
                        'flags': [],
                        'id': 24355313,
                        'license_code': 'cc-by',
                        'original_dimensions': {'height': 1364, 'width': 2048},
                        'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/24355313/square.jpeg',
                    },
                    'position': 1,
                    'uuid': '06b90a88-d98d-4447-b14c-5d354d2d68d1',
                },
            ],
            'observed_on': datetime(2018, 9, 5, 14, 6, tzinfo=tzoffset(None, 7200)),
            'observed_on_details': {
                'date': '2018-09-05',
                'day': 5,
                'hour': 14,
                'month': 9,
                'week': 36,
                'year': 2018,
            },
            'observed_on_string': '2018/09/05 2:06 PM CEST',
            'observed_time_zone': 'Europe/Paris',
            'ofvs': [],
            'outlinks': [{'source': 'GBIF', 'url': 'http://www.gbif.org/occurrence/1914197587'}],
            'owners_identification_from_vision': True,
            'photos': [
                {
                    'attribution': '(c) Nicolas Noé, some rights reserved (CC BY)',
                    'flags': [],
                    'id': 24355315,
                    'license_code': 'cc-by',
                    'original_dimensions': {'height': 1057, 'width': 1445},
                    'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/24355315/square.jpeg',
                },
                {
                    'attribution': '(c) Nicolas Noé, some rights reserved (CC BY)',
                    'flags': [],
                    'id': 24355313,
                    'license_code': 'cc-by',
                    'original_dimensions': {'height': 1364, 'width': 2048},
                    'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/24355313/square.jpeg',
                },
            ],
            'place_guess': '54 rue des Badauds',
            'place_ids': [
                7008,
                8657,
                14999,
                59614,
                67952,
                80627,
                81490,
                96372,
                96794,
                97391,
                97582,
                108692,
            ],
            'positional_accuracy': 23,
            'preferences': {'prefers_community_taxon': None},
            'project_ids': [],
            'project_ids_with_curator_id': [],
            'project_ids_without_curator_id': [],
            'project_observations': [],
            'public_positional_accuracy': 23,
            'quality_grade': 'research',
            'quality_metrics': [],
            'reviewed_by': [180811, 886482, 1226913],
            'site_id': 1,
            'sounds': [],
            'spam': False,
            'species_guess': 'Lixus bardanae',
            'tags': [],
            'taxon': {
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47208,
                    71130,
                    372852,
                    60473,
                    48736,
                    272543,
                    507383,
                    71157,
                    1101667,
                    493595,
                ],
                'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/60473/48736/272543/507383/71157/1101667',
                'atlas_id': None,
                'complete_species_count': None,
                'created_at': '2016-04-25T22:35:20+00:00',
                'current_synonymous_taxon_ids': None,
                'default_photo': {
                    'attribution': '(c) Andy Van de Velde, all rights '
                    'reserved, uploaded by Andy Van de '
                    'Velde',
                    'flags': [],
                    'id': 69087254,
                    'license_code': None,
                    'medium_url': 'https://static.inaturalist.org/photos/69087254/medium.jpg',
                    'original_dimensions': {'height': 1638, 'width': 2048},
                    'square_url': 'https://static.inaturalist.org/photos/69087254/square.jpg',
                    'url': 'https://static.inaturalist.org/photos/69087254/square.jpg',
                },
                'endemic': False,
                'extinct': False,
                'flag_counts': {'resolved': 0, 'unresolved': 0},
                'iconic_taxon_id': 47158,
                'iconic_taxon_name': 'Insecta',
                'id': 493595,
                'introduced': False,
                'is_active': True,
                'min_species_ancestry': '48460,1,47120,372739,47158,184884,47208,71130,372852,60473,48736,272543,507383,71157,1101667,493595',
                'min_species_taxon_id': 493595,
                'name': 'Lixus bardanae',
                'native': False,
                'observations_count': 86,
                'parent_id': 1101667,
                'photos_locked': False,
                'rank': 'species',
                'rank_level': 10,
                'taxon_changes_count': 0,
                'taxon_schemes_count': 1,
                'threatened': False,
                'universal_search_rank': 86,
                'wikipedia_url': None,
            },
            'taxon_geoprivacy': None,
            'time_zone_offset': '+01:00',
            'updated_at': datetime(2018, 9, 22, 19, 19, 27, tzinfo=tzoffset(None, 7200)),
            'uri': 'https://www.inaturalist.org/observations/16227955',
            'user': {
                'activity_count': 1184,
                'created_at': '2018-04-23T17:11:14+00:00',
                'icon': 'https://static.inaturalist.org/attachments/users/icons/886482/thumb.jpg?1529671435',
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/886482/medium.jpg?1529671435',
                'id': 886482,
                'identifications_count': 120,
                'journal_posts_count': 0,
                'login': 'niconoe',
                'login_autocomplete': 'niconoe',
                'login_exact': 'niconoe',
                'name': 'Nicolas Noé',
                'name_autocomplete': 'Nicolas Noé',
                'observations_count': 1064,
                'orcid': 'https://orcid.org/0000-0002-9503-4750',
                'preferences': {},
                'roles': [],
                'site_id': 1,
                'spam': False,
                'species_count': 471,
                'suspended': False,
                'universal_search_rank': 1064,
            },
            'uuid': '6448d03a-7f9a-4099-86aa-ca09a7740b00',
            'votes': [],
        },
    ],
}

Return type:: Dict[str, Any]
Returns:: Response dict containing observation records

pyinaturalist.v1.observations.update_observation(observation_id, **params)#

Update a single observation

Notes

Requires authentication
API reference: PUT /observations

Parameters:

observation_id (int) – iNaturalist observation ID
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.
flickr_photos (Union[int, Iterable[int], None]) – Flickr photo ID(s) to add as photos for this observation. User must have their Flickr and iNat accounts connected, and the user must own the photo(s) on Flickr.
picasa_photos (Union[str, Iterable[str], None]) – Picasa photo ID(s) to add as photos for this observation. User must have their Picasa and iNat accounts connected, and the user must own the photo(s) on Picasa.
facebook_photos (Union[str, Iterable[str], None]) – Facebook photo IDs to add as photos for this observation. User must have their Facebook and iNat accounts connected, and the user must own the photo on Facebook.
photos (Union[BinaryIO, str, Iterable[Union[BinaryIO, str]], None]) – One or more image files, file-like objects, file paths, or URLs
sounds (Union[BinaryIO, str, Iterable[Union[BinaryIO, 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
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(
>>>     17932425,
>>>     access_token=token,
>>>     description='updated description!',
>>> )

Return type:: List[Dict[str, Any]]
Returns:: JSON response containing the newly updated observation(s)

pyinaturalist.v1.observations.upload(observation_id, photos=None, sounds=None, photo_ids=None, **params)#

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

Parameters:

observation_id (int) – the ID of the observation
photos (Union[BinaryIO, str, Iterable[Union[BinaryIO, str]], None]) – One or more image files, file-like objects, file paths, or URLs
sounds (Union[BinaryIO, str, Iterable[Union[BinaryIO, 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 (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()
>>> upload(
...     1234,
...     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,
... )

Return type:: List[Dict[str, Any]]
Returns:: Information about the uploaded file(s)