ObservationController

class pyinaturalist.controllers.ObservationController(client)

Bases: pyinaturalist.controllers.base.BaseController

Controller for Observation requests

Methods

__init__(client)
create(**params)

Create or update a new observation.

Notes

Parameters

  • access_token (Optional[str]) – An access token required 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 ambuguous

  • 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

Return type

Observation

delete(*observation_ids, **params)

Delete observations

Parameters

observation_ids (int) – One or more observation IDs

from_id(*observation_ids, **params)

Get observations by ID

Parameters

observation_ids – One or more observation IDs

Return type

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

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

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

Return type

Dict[Union[date, datetime, int], int]

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

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

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

  • 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 unless otherwise noted

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

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

Return type

UserCounts

life_list(user_id, **params)

Get observation counts for all taxa in a full taxonomic tree. In the web UI, these are used for life lists.

Parameters

user_id (Union[int, str, None]) – iNaturalist user ID or username

Return type

LifeList

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

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

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

  • 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 unless otherwise noted

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

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

Return type

UserCounts

search(**params)

Search observations

Notes

Parameters

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • 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 unless otherwise noted

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

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

  • only_id (bool) – Return only the record IDs

Return type

Paginator[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. Leaf taxa are the leaves of the taxonomic tree, e.g., species, subspecies, variety, etc.

Notes

Parameters

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • 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 unless otherwise noted

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

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

Return type

TaxonCounts

taxon_summary(observation_id, **params)

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

Notes

Parameters

observation_id (int) – Observation ID to get taxon summary for

Return type

TaxonSummary

update(**params)

Update a single observation

Notes

Parameters

  • observation_id (int) – iNaturalist observation ID

  • access_token (Optional[str]) – An access token required 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 ambuguous

  • 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

Return type

Observation

upload(**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

Parameters
Return type

List[Dict[str, Any]]