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:
- __init__(client)¶
- create(**params)¶
Create or update an observation.
Notes
API reference: POST /observations
- 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 ambiguoustaxon_id (
Optional
[int
]) – ID of the taxon to associate with this observationobserved_on (
Union
[date
,datetime
,str
,None
]) – Alias forobserved_on_string
; acceptsdatetime
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 intag_list (
Union
[str
,Iterable
[str
],None
]) – Comma-separated list of tagsplace_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 stringlatitude (
Optional
[float
]) – Latitude of the observation; presumed datum is WGS84longitude (
Optional
[float
]) – Longitude of the observation; presumed datum is WGS84map_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 metersobservation_fields (
Union
[Dict
,List
[Dict
],None
]) – Dict of observation fields in the format{id: value}
. Alias forobservation_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
,Path
,str
,Iterable
[Union
[BinaryIO
,Path
,str
]],None
]) – One or more image files, file-like objects, file paths, or URLssounds (
Union
[BinaryIO
,Path
,str
,Iterable
[Union
[BinaryIO
,Path
,str
]],None
]) – One or more sound files, file-like objects, file paths, or URLsphoto_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:
- delete(observation_ids, **params)¶
Delete one or more observations
Notes
API reference: DELETE /observations/{id}
Example
>>> delete_observation(17932425, token)
- from_ids(observation_ids, **params)¶
Get one or more observations by ID
Notes
Optional authentication (For private/obscured coordinates)
API reference: GET /observations/{id}
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:
- 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 ofdate_field
andinterval
.date_field
may be either ‘observed’ (default) or ‘created’.Observed date ranges can be filtered by parameters
d1
andd2
Created date ranges can be filtered by parameters
created_d1
andcreated_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
andcreated_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:
d1 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or after this dated2 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or before this dateday (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this day of the monthmonth (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this monthyear (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this yearlicense (
Union
[str
,Iterable
[str
],None
]) – Observation must have this licensephoto_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one photo with this licenseout_of_range (
Optional
[bool
]) – Observations whose taxa are outside their known rangeslist_id (
Optional
[int
]) – Taxon must be in the list with this IDquality_grade (
Optional
[str
]) – Must have this quality gradeid (
Union
[int
,Iterable
[int
],None
]) – Must have this observation IDtaxon_id (
Union
[int
,Iterable
[int
],None
]) – Only show observations of these taxa and their descendantstaxon_name (
Union
[str
,Iterable
[str
],None
]) – Taxon must have a scientific or common name matching this stringiconic_taxa (
Union
[str
,Iterable
[str
],None
]) – Taxon must by within this iconic taxonupdated_since (
Union
[datetime
,str
,None
]) – Must be updated since this timeacc (
Optional
[bool
]) – Whether or not positional accuracy / coordinate uncertainty has been specifiedcaptive (
Optional
[bool
]) – Captive or cultivated observationsendemic (
Optional
[bool
]) – Observations whose taxa are endemic to their locationid_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 identificationsintroduced (
Optional
[bool
]) – Observations whose taxa are introduced in their locationmappable (
Optional
[bool
]) – Observations that show on map tilesnative (
Optional
[bool
]) – Observations whose taxa are native to their locationpcid (
Optional
[bool
]) – Observations identified by the curator of a project. If theproject_id
parameter is also specified, this will only consider observations identified by curators of the specified project(s)popular (
Optional
[bool
]) – Observations that have been favorited by at least one usertaxon_is_active (
Optional
[bool
]) – Observations of active taxon conceptsthreatened (
Optional
[bool
]) – Observations whose taxa are threatened in their locationverifiable (
Optional
[bool
]) – Observations with aquality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id (
Union
[int
,Iterable
[int
],None
]) – Must not have this IDplace_id (
Union
[int
,Iterable
[int
],None
]) – Must be observed within the place with this IDproject_id (
Union
[int
,Iterable
[int
],None
]) – Must be added to the project this ID or slugrank (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this ranksite_id (
Union
[str
,Iterable
[str
],None
]) – Must be affiliated with the iNaturalist network website with this IDobservation_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 datatypesound_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one sound with this licensewithout_taxon_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations of these taxa and their descendantsuser_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Observer must have this user ID or loginuser_login (
Union
[str
,Iterable
[str
],None
]) – Observer must have this user loginident_user_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Identifier must have this user ID or loginterm_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled term IDterm_value_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled value ID. Must be combined with theterm_id
parameterwithout_term_value_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations with annotations using this controlled value ID. Must be combined with theterm_id
parameteracc_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 unknowncreated_d1 (
Union
[datetime
,str
,None
]) – Must be created at or after this timecreated_d2 (
Union
[datetime
,str
,None
]) – Must be created at or before this timecreated_on (
Union
[date
,datetime
,str
,None
]) – Must be created on this dateobserved_on (
Union
[date
,datetime
,str
,None
]) – Must be observed on this dateunobserved_by_user_id (
Optional
[int
]) – Must not be of a taxon previously observed by this userapply_project_rules_for (
Optional
[str
]) – Must match the rules of the project with this ID or slugcs (
Optional
[str
]) – Taxon must have this conservation status code. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsa (
Optional
[str
]) – Taxon must have a conservation status from this authority. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsi (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this IUCN conservation status. If theplace_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy (
Union
[str
,Iterable
[str
],None
]) – Must have this geoprivacy settingtaxon_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.identifications (
Optional
[str
]) – Identifications must meet these criterialat (
Optional
[float
]) – Must be within aradius
kilometer circle around this lat/lng (lat, lng, radius)lng (
Optional
[float
]) – Must be within aradius
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 slugnot_matching_project_rules_for (
Union
[int
,str
,None
]) – Must not match the rules of the project with this ID or slugsearch_on (
Optional
[str
]) – Properties to search on, when combined with q. Searches across all properties by defaultreviewed (
Optional
[bool
]) – Observations have been reviewed by the user with ID equal to the value of theviewer_id
parameterlocale (
Optional
[str
]) – Locale preference for taxon common namespreferred_place_id (
Optional
[int
]) – Place preference for regional taxon common namesttl (
Optional
[str
]) – Set theCache-Control
HTTP header with this value asmax-age
, in secondsdate_field (
str
) – Histogram basis: either when the observation was created or observedinterval (
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, >>> )
{ 1: 272, 2: 253, 3: 992, 4: 3925, 5: 7983, 6: 7079, 7: 9150, 8: 8895, 9: 8374, 10: 6060, 11: 920, 12: 382, }
{ 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, }
{ 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, }
- identifiers(**params)¶
Get identifiers of observations matching the search criteria and the count of observations they have identified. By default, results are sorted by ID count in descending.
Notes
API reference: GET /observations/identifiers
This endpoint will only return up to 500 results.
- Parameters:
d1 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or after this dated2 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or before this dateday (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this day of the monthmonth (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this monthyear (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this yearlicense (
Union
[str
,Iterable
[str
],None
]) – Observation must have this licensephoto_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one photo with this licenseout_of_range (
Optional
[bool
]) – Observations whose taxa are outside their known rangeslist_id (
Optional
[int
]) – Taxon must be in the list with this IDquality_grade (
Optional
[str
]) – Must have this quality gradeid (
Union
[int
,Iterable
[int
],None
]) – Must have this observation IDtaxon_id (
Union
[int
,Iterable
[int
],None
]) – Only show observations of these taxa and their descendantstaxon_name (
Union
[str
,Iterable
[str
],None
]) – Taxon must have a scientific or common name matching this stringiconic_taxa (
Union
[str
,Iterable
[str
],None
]) – Taxon must by within this iconic taxonupdated_since (
Union
[datetime
,str
,None
]) – Must be updated since this timeacc (
Optional
[bool
]) – Whether or not positional accuracy / coordinate uncertainty has been specifiedcaptive (
Optional
[bool
]) – Captive or cultivated observationsendemic (
Optional
[bool
]) – Observations whose taxa are endemic to their locationid_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 identificationsintroduced (
Optional
[bool
]) – Observations whose taxa are introduced in their locationmappable (
Optional
[bool
]) – Observations that show on map tilesnative (
Optional
[bool
]) – Observations whose taxa are native to their locationpcid (
Optional
[bool
]) – Observations identified by the curator of a project. If theproject_id
parameter is also specified, this will only consider observations identified by curators of the specified project(s)popular (
Optional
[bool
]) – Observations that have been favorited by at least one usertaxon_is_active (
Optional
[bool
]) – Observations of active taxon conceptsthreatened (
Optional
[bool
]) – Observations whose taxa are threatened in their locationverifiable (
Optional
[bool
]) – Observations with aquality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id (
Union
[int
,Iterable
[int
],None
]) – Must not have this IDplace_id (
Union
[int
,Iterable
[int
],None
]) – Must be observed within the place with this IDproject_id (
Union
[int
,Iterable
[int
],None
]) – Must be added to the project this ID or slugrank (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this ranksite_id (
Union
[str
,Iterable
[str
],None
]) – Must be affiliated with the iNaturalist network website with this IDobservation_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 datatypesound_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one sound with this licensewithout_taxon_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations of these taxa and their descendantsuser_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Observer must have this user ID or loginuser_login (
Union
[str
,Iterable
[str
],None
]) – Observer must have this user loginident_user_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Identifier must have this user ID or loginterm_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled term IDterm_value_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled value ID. Must be combined with theterm_id
parameterwithout_term_value_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations with annotations using this controlled value ID. Must be combined with theterm_id
parameteracc_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 unknowncreated_d1 (
Union
[datetime
,str
,None
]) – Must be created at or after this timecreated_d2 (
Union
[datetime
,str
,None
]) – Must be created at or before this timecreated_on (
Union
[date
,datetime
,str
,None
]) – Must be created on this dateobserved_on (
Union
[date
,datetime
,str
,None
]) – Must be observed on this dateunobserved_by_user_id (
Optional
[int
]) – Must not be of a taxon previously observed by this userapply_project_rules_for (
Optional
[str
]) – Must match the rules of the project with this ID or slugcs (
Optional
[str
]) – Taxon must have this conservation status code. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsa (
Optional
[str
]) – Taxon must have a conservation status from this authority. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsi (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this IUCN conservation status. If theplace_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy (
Union
[str
,Iterable
[str
],None
]) – Must have this geoprivacy settingtaxon_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.identifications (
Optional
[str
]) – Identifications must meet these criterialat (
Optional
[float
]) – Must be within aradius
kilometer circle around this lat/lng (lat, lng, radius)lng (
Optional
[float
]) – Must be within aradius
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 slugnot_matching_project_rules_for (
Union
[int
,str
,None
]) – Must not match the rules of the project with this ID or slugsearch_on (
Optional
[str
]) – Properties to search on, when combined with q. Searches across all properties by defaultreviewed (
Optional
[bool
]) – Observations have been reviewed by the user with ID equal to the value of theviewer_id
parameterlocale (
Optional
[str
]) – Locale preference for taxon common namespreferred_place_id (
Optional
[int
]) – Place preference for regional taxon common namesttl (
Optional
[str
]) – Set theCache-Control
HTTP header with this value asmax-age
, in seconds
Example
>>> client.observations.identifiers(place_id=72645)
- Return type:
- 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
- observers(**params)¶
Get observers of observations matching the search criteria and the count of observations and distinct taxa of rank species they have observed.
Notes
API reference: GET /observations/observers
Options for
order_by
are ‘observation_count’ (default) or ‘species_count’This endpoint will only return up to 500 results
See this issue for more details: https://github.com/inaturalist/iNaturalistAPI/issues/235
- Parameters:
d1 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or after this dated2 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or before this dateday (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this day of the monthmonth (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this monthyear (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this yearlicense (
Union
[str
,Iterable
[str
],None
]) – Observation must have this licensephoto_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one photo with this licenseout_of_range (
Optional
[bool
]) – Observations whose taxa are outside their known rangeslist_id (
Optional
[int
]) – Taxon must be in the list with this IDquality_grade (
Optional
[str
]) – Must have this quality gradeid (
Union
[int
,Iterable
[int
],None
]) – Must have this observation IDtaxon_id (
Union
[int
,Iterable
[int
],None
]) – Only show observations of these taxa and their descendantstaxon_name (
Union
[str
,Iterable
[str
],None
]) – Taxon must have a scientific or common name matching this stringiconic_taxa (
Union
[str
,Iterable
[str
],None
]) – Taxon must by within this iconic taxonupdated_since (
Union
[datetime
,str
,None
]) – Must be updated since this timeacc (
Optional
[bool
]) – Whether or not positional accuracy / coordinate uncertainty has been specifiedcaptive (
Optional
[bool
]) – Captive or cultivated observationsendemic (
Optional
[bool
]) – Observations whose taxa are endemic to their locationid_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 identificationsintroduced (
Optional
[bool
]) – Observations whose taxa are introduced in their locationmappable (
Optional
[bool
]) – Observations that show on map tilesnative (
Optional
[bool
]) – Observations whose taxa are native to their locationpcid (
Optional
[bool
]) – Observations identified by the curator of a project. If theproject_id
parameter is also specified, this will only consider observations identified by curators of the specified project(s)popular (
Optional
[bool
]) – Observations that have been favorited by at least one usertaxon_is_active (
Optional
[bool
]) – Observations of active taxon conceptsthreatened (
Optional
[bool
]) – Observations whose taxa are threatened in their locationverifiable (
Optional
[bool
]) – Observations with aquality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id (
Union
[int
,Iterable
[int
],None
]) – Must not have this IDplace_id (
Union
[int
,Iterable
[int
],None
]) – Must be observed within the place with this IDproject_id (
Union
[int
,Iterable
[int
],None
]) – Must be added to the project this ID or slugrank (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this ranksite_id (
Union
[str
,Iterable
[str
],None
]) – Must be affiliated with the iNaturalist network website with this IDobservation_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 datatypesound_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one sound with this licensewithout_taxon_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations of these taxa and their descendantsuser_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Observer must have this user ID or loginuser_login (
Union
[str
,Iterable
[str
],None
]) – Observer must have this user loginident_user_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Identifier must have this user ID or loginterm_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled term IDterm_value_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled value ID. Must be combined with theterm_id
parameterwithout_term_value_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations with annotations using this controlled value ID. Must be combined with theterm_id
parameteracc_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 unknowncreated_d1 (
Union
[datetime
,str
,None
]) – Must be created at or after this timecreated_d2 (
Union
[datetime
,str
,None
]) – Must be created at or before this timecreated_on (
Union
[date
,datetime
,str
,None
]) – Must be created on this dateobserved_on (
Union
[date
,datetime
,str
,None
]) – Must be observed on this dateunobserved_by_user_id (
Optional
[int
]) – Must not be of a taxon previously observed by this userapply_project_rules_for (
Optional
[str
]) – Must match the rules of the project with this ID or slugcs (
Optional
[str
]) – Taxon must have this conservation status code. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsa (
Optional
[str
]) – Taxon must have a conservation status from this authority. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsi (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this IUCN conservation status. If theplace_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy (
Union
[str
,Iterable
[str
],None
]) – Must have this geoprivacy settingtaxon_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.identifications (
Optional
[str
]) – Identifications must meet these criterialat (
Optional
[float
]) – Must be within aradius
kilometer circle around this lat/lng (lat, lng, radius)lng (
Optional
[float
]) – Must be within aradius
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 slugnot_matching_project_rules_for (
Union
[int
,str
,None
]) – Must not match the rules of the project with this ID or slugsearch_on (
Optional
[str
]) – Properties to search on, when combined with q. Searches across all properties by defaultreviewed (
Optional
[bool
]) – Observations have been reviewed by the user with ID equal to the value of theviewer_id
parameterlocale (
Optional
[str
]) – Locale preference for taxon common namespreferred_place_id (
Optional
[int
]) – Place preference for regional taxon common namesttl (
Optional
[str
]) – Set theCache-Control
HTTP header with this value asmax-age
, in seconds
Example
>>> client.observations.observers(place_id=72645, order_by='species_count')
- Return type:
- popular_fields(**params)¶
Get controlled terms values and a monthly histogram of observations matching the search criteria.
Notes
API reference: GET /observations/popular_field_values
- Parameters:
d1 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or after this dated2 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or before this dateday (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this day of the monthmonth (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this monthyear (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this yearlicense (
Union
[str
,Iterable
[str
],None
]) – Observation must have this licensephoto_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one photo with this licenseout_of_range (
Optional
[bool
]) – Observations whose taxa are outside their known rangeslist_id (
Optional
[int
]) – Taxon must be in the list with this IDquality_grade (
Optional
[str
]) – Must have this quality gradeid (
Union
[int
,Iterable
[int
],None
]) – Must have this observation IDtaxon_id (
Union
[int
,Iterable
[int
],None
]) – Only show observations of these taxa and their descendantstaxon_name (
Union
[str
,Iterable
[str
],None
]) – Taxon must have a scientific or common name matching this stringiconic_taxa (
Union
[str
,Iterable
[str
],None
]) – Taxon must by within this iconic taxonupdated_since (
Union
[datetime
,str
,None
]) – Must be updated since this timeacc (
Optional
[bool
]) – Whether or not positional accuracy / coordinate uncertainty has been specifiedcaptive (
Optional
[bool
]) – Captive or cultivated observationsendemic (
Optional
[bool
]) – Observations whose taxa are endemic to their locationid_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 identificationsintroduced (
Optional
[bool
]) – Observations whose taxa are introduced in their locationmappable (
Optional
[bool
]) – Observations that show on map tilesnative (
Optional
[bool
]) – Observations whose taxa are native to their locationpcid (
Optional
[bool
]) – Observations identified by the curator of a project. If theproject_id
parameter is also specified, this will only consider observations identified by curators of the specified project(s)popular (
Optional
[bool
]) – Observations that have been favorited by at least one usertaxon_is_active (
Optional
[bool
]) – Observations of active taxon conceptsthreatened (
Optional
[bool
]) – Observations whose taxa are threatened in their locationverifiable (
Optional
[bool
]) – Observations with aquality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id (
Union
[int
,Iterable
[int
],None
]) – Must not have this IDplace_id (
Union
[int
,Iterable
[int
],None
]) – Must be observed within the place with this IDproject_id (
Union
[int
,Iterable
[int
],None
]) – Must be added to the project this ID or slugrank (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this ranksite_id (
Union
[str
,Iterable
[str
],None
]) – Must be affiliated with the iNaturalist network website with this IDobservation_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 datatypesound_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one sound with this licensewithout_taxon_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations of these taxa and their descendantsuser_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Observer must have this user ID or loginuser_login (
Union
[str
,Iterable
[str
],None
]) – Observer must have this user loginident_user_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Identifier must have this user ID or loginterm_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled term IDterm_value_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled value ID. Must be combined with theterm_id
parameterwithout_term_value_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations with annotations using this controlled value ID. Must be combined with theterm_id
parameteracc_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 unknowncreated_d1 (
Union
[datetime
,str
,None
]) – Must be created at or after this timecreated_d2 (
Union
[datetime
,str
,None
]) – Must be created at or before this timecreated_on (
Union
[date
,datetime
,str
,None
]) – Must be created on this dateobserved_on (
Union
[date
,datetime
,str
,None
]) – Must be observed on this dateunobserved_by_user_id (
Optional
[int
]) – Must not be of a taxon previously observed by this userapply_project_rules_for (
Optional
[str
]) – Must match the rules of the project with this ID or slugcs (
Optional
[str
]) – Taxon must have this conservation status code. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsa (
Optional
[str
]) – Taxon must have a conservation status from this authority. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsi (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this IUCN conservation status. If theplace_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy (
Union
[str
,Iterable
[str
],None
]) – Must have this geoprivacy settingtaxon_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.identifications (
Optional
[str
]) – Identifications must meet these criterialat (
Optional
[float
]) – Must be within aradius
kilometer circle around this lat/lng (lat, lng, radius)lng (
Optional
[float
]) – Must be within aradius
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 slugnot_matching_project_rules_for (
Union
[int
,str
,None
]) – Must not match the rules of the project with this ID or slugsearch_on (
Optional
[str
]) – Properties to search on, when combined with q. Searches across all properties by defaultreviewed (
Optional
[bool
]) – Observations have been reviewed by the user with ID equal to the value of theviewer_id
parameterlocale (
Optional
[str
]) – Locale preference for taxon common namespreferred_place_id (
Optional
[int
]) – Place preference for regional taxon common namesttl (
Optional
[str
]) – Set theCache-Control
HTTP header with this value asmax-age
, in seconds
Example
>>> client.observations.popular_fields(species_name='Danaus plexippus', place_id=24)
- Return type:
- search(**params)¶
Search observations
Notes
Optional authentication (For private/obscured coordinates)
API reference: GET /observations
- Parameters:
d1 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or after this dated2 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or before this dateday (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this day of the monthmonth (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this monthyear (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this yearlicense (
Union
[str
,Iterable
[str
],None
]) – Observation must have this licensephoto_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one photo with this licenseout_of_range (
Optional
[bool
]) – Observations whose taxa are outside their known rangeslist_id (
Optional
[int
]) – Taxon must be in the list with this IDquality_grade (
Optional
[str
]) – Must have this quality gradeid (
Union
[int
,Iterable
[int
],None
]) – Must have this observation IDtaxon_id (
Union
[int
,Iterable
[int
],None
]) – Only show observations of these taxa and their descendantstaxon_name (
Union
[str
,Iterable
[str
],None
]) – Taxon must have a scientific or common name matching this stringiconic_taxa (
Union
[str
,Iterable
[str
],None
]) – Taxon must by within this iconic taxonupdated_since (
Union
[datetime
,str
,None
]) – Must be updated since this timeacc (
Optional
[bool
]) – Whether or not positional accuracy / coordinate uncertainty has been specifiedcaptive (
Optional
[bool
]) – Captive or cultivated observationsendemic (
Optional
[bool
]) – Observations whose taxa are endemic to their locationid_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 identificationsintroduced (
Optional
[bool
]) – Observations whose taxa are introduced in their locationmappable (
Optional
[bool
]) – Observations that show on map tilesnative (
Optional
[bool
]) – Observations whose taxa are native to their locationpcid (
Optional
[bool
]) – Observations identified by the curator of a project. If theproject_id
parameter is also specified, this will only consider observations identified by curators of the specified project(s)popular (
Optional
[bool
]) – Observations that have been favorited by at least one usertaxon_is_active (
Optional
[bool
]) – Observations of active taxon conceptsthreatened (
Optional
[bool
]) – Observations whose taxa are threatened in their locationverifiable (
Optional
[bool
]) – Observations with aquality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id (
Union
[int
,Iterable
[int
],None
]) – Must not have this IDplace_id (
Union
[int
,Iterable
[int
],None
]) – Must be observed within the place with this IDproject_id (
Union
[int
,Iterable
[int
],None
]) – Must be added to the project this ID or slugrank (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this ranksite_id (
Union
[str
,Iterable
[str
],None
]) – Must be affiliated with the iNaturalist network website with this IDobservation_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 datatypesound_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one sound with this licensewithout_taxon_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations of these taxa and their descendantsuser_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Observer must have this user ID or loginuser_login (
Union
[str
,Iterable
[str
],None
]) – Observer must have this user loginident_user_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Identifier must have this user ID or loginterm_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled term IDterm_value_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled value ID. Must be combined with theterm_id
parameterwithout_term_value_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations with annotations using this controlled value ID. Must be combined with theterm_id
parameteracc_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 unknowncreated_d1 (
Union
[datetime
,str
,None
]) – Must be created at or after this timecreated_d2 (
Union
[datetime
,str
,None
]) – Must be created at or before this timecreated_on (
Union
[date
,datetime
,str
,None
]) – Must be created on this dateobserved_on (
Union
[date
,datetime
,str
,None
]) – Must be observed on this dateunobserved_by_user_id (
Optional
[int
]) – Must not be of a taxon previously observed by this userapply_project_rules_for (
Optional
[str
]) – Must match the rules of the project with this ID or slugcs (
Optional
[str
]) – Taxon must have this conservation status code. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsa (
Optional
[str
]) – Taxon must have a conservation status from this authority. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsi (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this IUCN conservation status. If theplace_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy (
Union
[str
,Iterable
[str
],None
]) – Must have this geoprivacy settingtaxon_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.identifications (
Optional
[str
]) – Identifications must meet these criterialat (
Optional
[float
]) – Must be within aradius
kilometer circle around this lat/lng (lat, lng, radius)lng (
Optional
[float
]) – Must be within aradius
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 slugnot_matching_project_rules_for (
Union
[int
,str
,None
]) – Must not match the rules of the project with this ID or slugsearch_on (
Optional
[str
]) – Properties to search on, when combined with q. Searches across all properties by defaultreviewed (
Optional
[bool
]) – Observations have been reviewed by the user with ID equal to the value of theviewer_id
parameterlocale (
Optional
[str
]) – Locale preference for taxon common namespreferred_place_id (
Optional
[int
]) – Place preference for regional taxon common namesttl (
Optional
[str
]) – Set theCache-Control
HTTP header with this value asmax-age
, in seconds
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:
- species_counts(**params)¶
Get all species (or other ‘leaf taxa’) associated with observations matching the search criteria, and the count of observations they are associated with.
Notes
API reference: GET /observations/species_counts
Leaf taxa are the leaves of the taxonomic tree, e.g., species, subspecies, variety, etc.
- Parameters:
d1 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or after this dated2 (
Union
[date
,datetime
,str
,None
]) – Must be observed on or before this dateday (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this day of the monthmonth (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this monthyear (
Union
[int
,Iterable
[int
],None
]) – Must be observed within this yearlicense (
Union
[str
,Iterable
[str
],None
]) – Observation must have this licensephoto_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one photo with this licenseout_of_range (
Optional
[bool
]) – Observations whose taxa are outside their known rangeslist_id (
Optional
[int
]) – Taxon must be in the list with this IDquality_grade (
Optional
[str
]) – Must have this quality gradeid (
Union
[int
,Iterable
[int
],None
]) – Must have this observation IDtaxon_id (
Union
[int
,Iterable
[int
],None
]) – Only show observations of these taxa and their descendantstaxon_name (
Union
[str
,Iterable
[str
],None
]) – Taxon must have a scientific or common name matching this stringiconic_taxa (
Union
[str
,Iterable
[str
],None
]) – Taxon must by within this iconic taxonupdated_since (
Union
[datetime
,str
,None
]) – Must be updated since this timeacc (
Optional
[bool
]) – Whether or not positional accuracy / coordinate uncertainty has been specifiedcaptive (
Optional
[bool
]) – Captive or cultivated observationsendemic (
Optional
[bool
]) – Observations whose taxa are endemic to their locationid_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 identificationsintroduced (
Optional
[bool
]) – Observations whose taxa are introduced in their locationmappable (
Optional
[bool
]) – Observations that show on map tilesnative (
Optional
[bool
]) – Observations whose taxa are native to their locationpcid (
Optional
[bool
]) – Observations identified by the curator of a project. If theproject_id
parameter is also specified, this will only consider observations identified by curators of the specified project(s)popular (
Optional
[bool
]) – Observations that have been favorited by at least one usertaxon_is_active (
Optional
[bool
]) – Observations of active taxon conceptsthreatened (
Optional
[bool
]) – Observations whose taxa are threatened in their locationverifiable (
Optional
[bool
]) – Observations with aquality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id (
Union
[int
,Iterable
[int
],None
]) – Must not have this IDplace_id (
Union
[int
,Iterable
[int
],None
]) – Must be observed within the place with this IDproject_id (
Union
[int
,Iterable
[int
],None
]) – Must be added to the project this ID or slugrank (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this ranksite_id (
Union
[str
,Iterable
[str
],None
]) – Must be affiliated with the iNaturalist network website with this IDobservation_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 datatypesound_license (
Union
[str
,Iterable
[str
],None
]) – Must have at least one sound with this licensewithout_taxon_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations of these taxa and their descendantsuser_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Observer must have this user ID or loginuser_login (
Union
[str
,Iterable
[str
],None
]) – Observer must have this user loginident_user_id (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – Identifier must have this user ID or loginterm_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled term IDterm_value_id (
Union
[int
,Iterable
[int
],None
]) – Must have an annotation using this controlled value ID. Must be combined with theterm_id
parameterwithout_term_value_id (
Union
[int
,Iterable
[int
],None
]) – Exclude observations with annotations using this controlled value ID. Must be combined with theterm_id
parameteracc_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 unknowncreated_d1 (
Union
[datetime
,str
,None
]) – Must be created at or after this timecreated_d2 (
Union
[datetime
,str
,None
]) – Must be created at or before this timecreated_on (
Union
[date
,datetime
,str
,None
]) – Must be created on this dateobserved_on (
Union
[date
,datetime
,str
,None
]) – Must be observed on this dateunobserved_by_user_id (
Optional
[int
]) – Must not be of a taxon previously observed by this userapply_project_rules_for (
Optional
[str
]) – Must match the rules of the project with this ID or slugcs (
Optional
[str
]) – Taxon must have this conservation status code. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsa (
Optional
[str
]) – Taxon must have a conservation status from this authority. If theplace_id
parameter is also specified, this will only consider statuses specific to that placecsi (
Union
[str
,Iterable
[str
],None
]) – Taxon must have this IUCN conservation status. If theplace_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy (
Union
[str
,Iterable
[str
],None
]) – Must have this geoprivacy settingtaxon_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.identifications (
Optional
[str
]) – Identifications must meet these criterialat (
Optional
[float
]) – Must be within aradius
kilometer circle around this lat/lng (lat, lng, radius)lng (
Optional
[float
]) – Must be within aradius
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 slugnot_matching_project_rules_for (
Union
[int
,str
,None
]) – Must not match the rules of the project with this ID or slugsearch_on (
Optional
[str
]) – Properties to search on, when combined with q. Searches across all properties by defaultreviewed (
Optional
[bool
]) – Observations have been reviewed by the user with ID equal to the value of theviewer_id
parameterlocale (
Optional
[str
]) – Locale preference for taxon common namespreferred_place_id (
Optional
[int
]) – Place preference for regional taxon common namesttl (
Optional
[str
]) – Set theCache-Control
HTTP header with this value asmax-age
, in seconds
Example
>>> client.observations.species_counts(user_login='my_username', quality_grade='research')
- Return type:
- taxon_summary(observation_id, **params)¶
Get information about an observation’s taxon, within the context of the observation’s location
Notes
API reference: GET /observations/{id}/taxon_summary
- Parameters:
observation_id (
int
) – Observation ID to get taxon summary for
Example
>>> client.observations.taxon_summary(7849808)
- Return type:
- update(**params)¶
Update a single observation
Notes
API reference: PUT /observations
- Parameters:
observation_id (
int
) – iNaturalist observation IDspecies_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 ambiguoustaxon_id (
Optional
[int
]) – ID of the taxon to associate with this observationobserved_on (
Union
[date
,datetime
,str
,None
]) – Alias forobserved_on_string
; acceptsdatetime
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 intag_list (
Union
[str
,Iterable
[str
],None
]) – Comma-separated list of tagsplace_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 stringlatitude (
Optional
[float
]) – Latitude of the observation; presumed datum is WGS84longitude (
Optional
[float
]) – Longitude of the observation; presumed datum is WGS84map_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 metersobservation_fields (
Union
[Dict
,List
[Dict
],None
]) – Dict of observation fields in the format{id: value}
. Alias forobservation_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
,Path
,str
,Iterable
[Union
[BinaryIO
,Path
,str
]],None
]) – One or more image files, file-like objects, file paths, or URLssounds (
Union
[BinaryIO
,Path
,str
,Iterable
[Union
[BinaryIO
,Path
,str
]],None
]) – One or more sound files, file-like objects, file paths, or URLsphoto_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:
- 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
API reference: POST /observation_photos
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], ... )
[ { "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:
observation_id (
int
) – the ID of the observationphotos (
Union
[BinaryIO
,Path
,str
,Iterable
[Union
[BinaryIO
,Path
,str
]],None
]) – One or more image files, file-like objects, file paths, or URLssounds (
Union
[BinaryIO
,Path
,str
,Iterable
[Union
[BinaryIO
,Path
,str
]],None
]) – One or more audio files, file-like objects, file paths, or URLsphoto_ids (
Union
[int
,Iterable
[int
],str
,Iterable
[str
],None
]) – One or more IDs of previously uploaded photos to attach to the observationaccess_token – Access token for user authentication, as returned by
get_access_token()
- Return type:
- Returns: