ObservationController#

class pyinaturalist.controllers.ObservationController(client)#

Bases: BaseController

Controller for Observation requests

Methods

__call__(observation_id, **params)#

Get a single observation by ID

Example

>>> client.observations(16227955)
Parameters:

observation_ids – A single observation ID

Return type:

Optional[Observation]

__init__(client)#
create(**params)#

Create or update an observation.

Notes

Parameters:
  • 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

Example

>>> client.observations.create(
...     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'
... )
Return type:

Observation

delete(observation_ids, **params)#

Delete one or more observations

Notes

Example

>>> delete_observation(17932425, token)
Parameters:

observation_ids (Union[int, Iterable[int]]) – One or more observation IDs

from_ids(observation_ids, **params)#

Get one or more observations by ID

Notes

Examples

>>> obs = client.observations.from_ids(16227955).all()
>>> obs = client.observations.from_ids([16227955, 16227956]).all()
Parameters:

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

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

Example

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

>>> client.observations.histogram(
>>>     interval='month',
>>>     d1='2020-01-01',
>>>     d2='2020-12-31',
>>>     place_id=8057,
>>> )
Example Response (observations per month of year)
{
    1: 272,
    2: 253,
    3: 992,
    4: 3925,
    5: 7983,
    6: 7079,
    7: 9150,
    8: 8895,
    9: 8374,
    10: 6060,
    11: 920,
    12: 382,
}
Example Response (observations per month)
{
    datetime(2020, 1, 1, 0, 0): 272,
    datetime(2020, 2, 1, 0, 0): 253,
    datetime(2020, 3, 1, 0, 0): 992,
    datetime(2020, 4, 1, 0, 0): 3925,
    datetime(2020, 5, 1, 0, 0): 7983,
    datetime(2020, 6, 1, 0, 0): 7080,
    datetime(2020, 7, 1, 0, 0): 9150,
    datetime(2020, 8, 1, 0, 0): 8895,
    datetime(2020, 9, 1, 0, 0): 8374,
    datetime(2020, 10, 1, 0, 0): 6060,
    datetime(2020, 11, 1, 0, 0): 920,
    datetime(2020, 12, 1, 0, 0): 382,
}
Example Response (observations per day)
{
    datetime(2020, 1, 1, 0, 0): 11,
    datetime(2020, 1, 2, 0, 0): 6,
    datetime(2020, 1, 3, 0, 0): 2,
    datetime(2020, 1, 4, 0, 0): 3,
    datetime(2020, 1, 5, 0, 0): 13,
    datetime(2020, 1, 6, 0, 0): 4,
    datetime(2020, 1, 7, 0, 0): 4,
    datetime(2020, 1, 8, 0, 0): 0,
    datetime(2020, 1, 9, 0, 0): 1,
    datetime(2020, 1, 10, 0, 0): 5,
    datetime(2020, 1, 11, 0, 0): 6,
    datetime(2020, 1, 12, 0, 0): 7,
    datetime(2020, 1, 13, 0, 0): 2,
    datetime(2020, 1, 14, 0, 0): 7,
    datetime(2020, 1, 15, 0, 0): 11,
    datetime(2020, 1, 16, 0, 0): 0,
    datetime(2020, 1, 17, 0, 0): 5,
    datetime(2020, 1, 18, 0, 0): 13,
    datetime(2020, 1, 19, 0, 0): 1,
    datetime(2020, 1, 20, 0, 0): 5,
    datetime(2020, 1, 21, 0, 0): 3,
    datetime(2020, 1, 22, 0, 0): 8,
    datetime(2020, 1, 23, 0, 0): 21,
    datetime(2020, 1, 24, 0, 0): 7,
    datetime(2020, 1, 25, 0, 0): 14,
    datetime(2020, 1, 26, 0, 0): 62,
    datetime(2020, 1, 27, 0, 0): 10,
    datetime(2020, 1, 28, 0, 0): 17,
    datetime(2020, 1, 29, 0, 0): 7,
    datetime(2020, 1, 30, 0, 0): 9,
    datetime(2020, 1, 31, 0, 0): 7,
}
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.

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

  • 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

Example

>>> client.observations.identifiers(place_id=72645)
Return type:

UserCounts

life_list(user_id=None, locale=None, **params)#

Get taxa from a user’s dynamic life list

Notes

  • Results are returned in a flat list, but are ordered as they would be in a taxonomic tree

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

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

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

  • 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

Example

>>> client.observations.observers(place_id=72645, order_by='species_count')
Return type:

UserCounts

popular_fields(**params)#

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

Notes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • csi (Union[str, Iterable[str], None]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place

  • geoprivacy (Union[str, Iterable[str], None]) – Must have this geoprivacy setting

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

  • hrank (Optional[str]) – Taxon must have this rank or lower

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

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

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

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

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

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

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

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

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

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

  • viewer_id (Optional[int]) – See reviewed

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

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

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

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

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

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

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

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

Example

>>> client.observations.popular_fields(species_name='Danaus plexippus', place_id=24)
Return type:

ControlledTermCounts

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

  • 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

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

Examples

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

>>> query = client.observations.search(
>>>     taxon_name='Danaus plexippus',
>>>     created_on='2020-08-27',
>>>     photos=True,
>>>     geo=True,
>>>     geoprivacy='open',
>>>     place_id=7953,
>>> )
>>> observations = query.all()

Get basic info for observations in response:

>>> pprint(observations)
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:

>>> obs = client.observations.search(observation_fields=['Species count']).all()

Or observation field value:

>>> obs = client.observations.search(observation_fields={'Species count': 2}).all()
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.

Notes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • csi (Union[str, Iterable[str], None]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place

  • geoprivacy (Union[str, Iterable[str], None]) – Must have this geoprivacy setting

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

  • hrank (Optional[str]) – Taxon must have this rank or lower

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

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

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

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

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

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

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

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

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

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

  • viewer_id (Optional[int]) – See reviewed

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

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

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

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

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

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

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

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

Example

>>> client.observations.species_counts(user_login='my_username', quality_grade='research')
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

Example

>>> client.observations.taxon_summary(7849808)
Return type:

TaxonSummary

update(**params)#

Update a single observation

Notes

Parameters:
  • observation_id (int) – iNaturalist observation ID

  • 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

Example

>>> client.observations.update(
>>>     17932425,
>>>     description='updated description!',
>>> )
Return type:

Observation

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

Example

>>> client.observations.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],
... )
Example Response
[
  {
    "id": 137606630,
    "observation_id": 89279185,
    "photo_id": 147418592,
    "position": null,
    "created_at": "2021-07-30T22:46:26.476-05:00",
    "updated_at": "2021-07-30T22:46:26.476-05:00",
    "old_uuid": null,
    "uuid": "6bda79d9-4be2-4f2a-b91e-57b4f7e0348e",
    "created_at_utc": "2021-07-31T03:46:26.476Z",
    "updated_at_utc": "2021-07-31T03:46:26.476Z",
    "photo": {
      "id": 147418592,
      "user_id": 2115051,
      "native_photo_id": "147418592",
      "square_url": null,
      "thumb_url": null,
      "small_url": null,
      "medium_url": null,
      "large_url": null,
      "created_at": "2021-07-30T22:46:25.023-05:00",
      "updated_at": "2021-07-30T22:46:25.023-05:00",
      "native_page_url": null,
      "native_username": "jkcook",
      "native_realname": "Jordan Cook",
      "license": 2,
      "subtype": null,
      "native_original_image_url": null,
      "uuid": "8274ade9-9edb-4e07-8695-b4578416ff1e",
      "license_code": "cc-by-nc",
      "license_name": "Creative Commons Attribution-NonCommercial License",
      "license_url": "http://creativecommons.org/licenses/by-nc/4.0/",
      "attribution": "(c) Jordan Cook, some rights reserved (CC BY-NC)",
      "type": "LocalPhoto"
    }
  },
  {
    "id": 278097,
    "uuid": "5c858ffa-696b-4bf2-beab-9f519901bd17",
    "created_at": "2021-07-30T22:46:28.828-05:00",
    "updated_at": "2021-07-30T22:46:28.828-05:00",
    "sound": {
      "id": 284703,
      "license_code": "cc-by-nc",
      "attribution": "(c) Jordan Cook, some rights reserved (CC BY-NC)",
      "native_sound_id": null,
      "secret_token": null,
      "file_url": "https://static.inaturalist.org/sounds/284703.wav?1627703188",
      "file_content_type": "audio/x-wav",
      "play_local": true,
      "subtype": null,
      "flags": []
    }
  }
]
Parameters:
Return type:

List[Union[Photo, Sound]]

Returns:

Photo or Sound objects for each uploaded file