Observations#
Summary#
|
Create or update a new observation. |
|
Delete an observation |
|
Get details about a single observation by ID |
|
Search observations and return histogram data for the given time interval |
|
Get identifiers of observations matching the search criteria and the count of observations they have identified. |
|
Get observers of observations matching the search criteria and the count of observations and distinct taxa of rank species they have observed. |
|
Get controlled terms values and a monthly histogram of observations matching the search |
|
Get all species (or other 'leaf taxa') associated with observations matching the search criteria, and the count of observations they are associated with. |
Get information about an observation's taxon, within the context of the observation's location |
|
|
Get observation counts for all taxa in a full taxonomic tree. |
|
Search observations |
|
Get one or more observations by ID |
|
Update a single observation |
|
Upload one or more local photo and/or sound files, and add them to an existing observation. |
Module Contents#
- pyinaturalist.v1.observations.create_observation(**params)#
Create or update a new observation.
Notes
API reference: POST /observations
- Parameters:
access_token – An access token for user authentication, as returned by
get_access_token()
species_guess – Equivalent to the ‘What did you see?’ field on the observation form. iNat will try to choose a single taxon based on this, but it may fail if it’s ambuguous
taxon_id – ID of the taxon to associate with this observation
observed_on – Alias for
observed_on_string
; acceptsdatetime
objects.observed_on_string – Date/time of the observation. Time zone will default to the user’s time zone if not specified.
time_zone – Time zone the observation was made in
description – Observation description
tag_list – Comma-separated list of tags
place_guess – Name of the place where the observation was recorded. Note: iNat will not try to automatically look up coordinates based on this string
latitude – Latitude of the observation; presumed datum is WGS84
longitude – Longitude of the observation; presumed datum is WGS84
map_scale – Google Maps zoom level (from 0 to 19) at which to show this observation’s map marker.
positional_accuracy – Positional accuracy of the observation coordinates, in meters
geoprivacy – Geoprivacy for the observation
observation_fields – Dict of observation fields in the format
{id: value}
. Alias forobservation_field_values_attributes
.flickr_photos – 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 – 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 – 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 – One or more image files, file-like objects, file paths, or URLs
sounds – One or more sound files, file-like objects, file paths, or URLs
photo_ids – One or more IDs of previously uploaded photos to attach to the observation
dry_run – Just log the request instead of sending a real request
session – An existing Session object to use instead of creating a new one
Example
>>> token = get_access_token() >>> # Create a new observation: >>> create_observation( ... access_token=token, ... species_guess='Pieris rapae', ... photos='~/observation_photos/2020_09_01_14003156.jpg', ... observation_fields={297: 1}, # 297 is the obs. field ID for 'Number of individuals' ... ) >>> >>> # Update an existing observation: >>> create_observation( ... access_token=token, ... uuid='53411fc2-bdf0-434e-afce-4dac33970173', ... description='Updated description!', ... )
Example Response
{ "id": 54986584, "project_id": 24237, "observation_id": 81366450, "created_at": "2021-07-30T19:10:32.323-05:00", "updated_at": "2021-07-30T19:10:32.345-05:00", "curator_identification_id": null, "tracking_code": null, "user_id": 2115051, "uuid": "3595235e-96b1-450f-92ec-49162721cc6f", "created_at_utc": "2021-07-31T00:10:32.323Z", "updated_at_utc": "2021-07-31T00:10:32.345Z" }
- pyinaturalist.v1.observations.delete_observation(observation_id, access_token=None, **params)#
Delete an observation
Notes
API reference: DELETE /observations/{id}
- Parameters:
observation_id (
int
) – iNaturalist observation IDaccess_token (
Optional
[str
]) – An access token for user authentication, as returned byget_access_token()
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> token = get_access_token() >>> delete_observation(17932425, token)
- Returns:
If successful, no response is returned from this endpoint
- Raises:
.ObservationNotFound –
- pyinaturalist.v1.observations.get_observation(observation_id, access_token=None, **params)#
Get details about a single observation by ID
Notes
Deprecated; use
get_observations()
orget_observations_by_id()
insteadOptional authentication (For private/obscured coordinates)
API reference: GET /observations/{id}
- Parameters:
observation_id (
int
) – Get the observation with this ID. Only a single value is allowed.access_token (
Optional
[str
]) – An access token, as returned byget_access_token()
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> response = get_observation(16227955)
- pyinaturalist.v1.observations.get_observation_histogram(**params)#
Search observations and return histogram data for the given time interval
Notes
API reference: GET /observations/histogram
Search parameters are the same as
get_observations()
, with the addition 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:
q – Search observation properties
d1 – Must be observed on or after this date
d2 – Must be observed on or before this date
day – Must be observed within this day of the month
month – Must be observed within this month
year – Must be observed within this year
license – Observation must have this license
photo_license – Must have at least one photo with this license
out_of_range – Observations whose taxa are outside their known ranges
list_id – Taxon must be in the list with this ID
quality_grade – Must have this quality grade
id – Must have this observation ID
taxon_id – Only show observations of these taxa and their descendants
taxon_name – Taxon must have a scientific or common name matching this string
iconic_taxa – Taxon must by within this iconic taxon
updated_since – Must be updated since this time
acc – Whether or not positional accuracy / coordinate uncertainty has been specified
captive – Captive or cultivated observations
endemic – Observations whose taxa are endemic to their location
geo – Observations that are georeferenced
id_please – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified – Observations that have community identifications
introduced – Observations whose taxa are introduced in their location
mappable – Observations that show on map tiles
native – Observations whose taxa are native to their location
pcid – 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 – Observations with photos
popular – Observations that have been favorited by at least one user
sounds – Observations with sounds
taxon_is_active – Observations of active taxon concepts
threatened – Observations whose taxa are threatened in their location
verifiable – Observations with a
quality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id – Must not have this ID
place_id – Must be observed within the place with this ID
project_id – Must be added to the project this ID or slug
rank – Taxon must have this rank
site_id – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype – Must have an observation field value with this datatype
sound_license – Must have at least one sound with this license
without_taxon_id – Exclude observations of these taxa and their descendants
user_id – Observer must have this user ID or login
user_login – Observer must have this user login
ident_user_id – Identifier must have this user ID or login
term_id – Must have an annotation using this controlled term ID
term_value_id – Must have an annotation using this controlled value ID. Must be combined with the
term_id
parameterwithout_term_value_id – Exclude observations with annotations using this controlled value ID. Must be combined with the
term_id
parameteracc_above – Must have an positional accuracy above this value (meters)
acc_below – Must have an positional accuracy below this value (meters)
acc_below_or_unknown – Must have an positional accuracy below this value (meters) or unknown
created_d1 – Must be created at or after this time
created_d2 – Must be created at or before this time
created_on – Must be created on this date
observed_on – Must be observed on this date
unobserved_by_user_id – Must not be of a taxon previously observed by this user
apply_project_rules_for – Must match the rules of the project with this ID or slug
cs – Taxon must have this conservation status code. If the
place_id
parameter is also specified, this will only consider statuses specific to that placecsa – 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 placecsi – Taxon must have this IUCN conservation status. If the
place_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy – Must have this geoprivacy setting
taxon_geoprivacy – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank – Taxon must have this rank or lower
lrank – Taxon must have this rank or higher
id_above – Must have an ID above this value
id_below – Must have an ID below this value
identifications – Identifications must meet these criteria
lat – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)lng – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)radius – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project – Must not be in the project with this ID or slug
not_matching_project_rules_for – Must not match the rules of the project with this ID or slug
search_on – Properties to search on, when combined with q. Searches across all properties by default
viewer_id – See reviewed
reviewed – Observations have been reviewed by the user with ID equal to the value of the
viewer_id
parameterlocale – Locale preference for taxon common names
preferred_place_id – Place preference for regional taxon common names
ttl – Set the
Cache-Control
HTTP header with this value asmax-age
, in secondsnelat – NE latitude of bounding box
nelng – NE longitude of bounding box
swlat – SW latitude of bounding box
swlng – SW longitude of bounding box
date_field – Histogram basis: either when the observation was created or observed
interval – Time interval for histogram, with groups starting on or contained within the group value.
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
Get observations per month during 2020 in Austria (place ID 8057)
>>> response = get_observation_histogram( >>> interval='month', >>> d1='2020-01-01', >>> d2='2020-12-31', >>> place_id=8057, >>> )
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)
from datetime import datetime { 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)
from datetime import datetime { 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, }
- pyinaturalist.v1.observations.get_observation_identifiers(**params)#
Get identifiers of observations matching the search criteria and the count of observations they have identified. By default, results are sorted by ID count in descending.
Notes
API reference: GET /observations/identifiers
This endpoint will only return up to 500 results.
- Parameters:
q – Search observation properties
d1 – Must be observed on or after this date
d2 – Must be observed on or before this date
day – Must be observed within this day of the month
month – Must be observed within this month
year – Must be observed within this year
license – Observation must have this license
photo_license – Must have at least one photo with this license
out_of_range – Observations whose taxa are outside their known ranges
list_id – Taxon must be in the list with this ID
quality_grade – Must have this quality grade
id – Must have this observation ID
taxon_id – Only show observations of these taxa and their descendants
taxon_name – Taxon must have a scientific or common name matching this string
iconic_taxa – Taxon must by within this iconic taxon
updated_since – Must be updated since this time
acc – Whether or not positional accuracy / coordinate uncertainty has been specified
captive – Captive or cultivated observations
endemic – Observations whose taxa are endemic to their location
geo – Observations that are georeferenced
id_please – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified – Observations that have community identifications
introduced – Observations whose taxa are introduced in their location
mappable – Observations that show on map tiles
native – Observations whose taxa are native to their location
pcid – 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 – Observations with photos
popular – Observations that have been favorited by at least one user
sounds – Observations with sounds
taxon_is_active – Observations of active taxon concepts
threatened – Observations whose taxa are threatened in their location
verifiable – Observations with a
quality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id – Must not have this ID
place_id – Must be observed within the place with this ID
project_id – Must be added to the project this ID or slug
rank – Taxon must have this rank
site_id – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype – Must have an observation field value with this datatype
sound_license – Must have at least one sound with this license
without_taxon_id – Exclude observations of these taxa and their descendants
user_id – Observer must have this user ID or login
user_login – Observer must have this user login
ident_user_id – Identifier must have this user ID or login
term_id – Must have an annotation using this controlled term ID
term_value_id – Must have an annotation using this controlled value ID. Must be combined with the
term_id
parameterwithout_term_value_id – Exclude observations with annotations using this controlled value ID. Must be combined with the
term_id
parameteracc_above – Must have an positional accuracy above this value (meters)
acc_below – Must have an positional accuracy below this value (meters)
acc_below_or_unknown – Must have an positional accuracy below this value (meters) or unknown
created_d1 – Must be created at or after this time
created_d2 – Must be created at or before this time
created_on – Must be created on this date
observed_on – Must be observed on this date
unobserved_by_user_id – Must not be of a taxon previously observed by this user
apply_project_rules_for – Must match the rules of the project with this ID or slug
cs – Taxon must have this conservation status code. If the
place_id
parameter is also specified, this will only consider statuses specific to that placecsa – 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 placecsi – Taxon must have this IUCN conservation status. If the
place_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy – Must have this geoprivacy setting
taxon_geoprivacy – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank – Taxon must have this rank or lower
lrank – Taxon must have this rank or higher
id_above – Must have an ID above this value
id_below – Must have an ID below this value
identifications – Identifications must meet these criteria
lat – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)lng – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)radius – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project – Must not be in the project with this ID or slug
not_matching_project_rules_for – Must not match the rules of the project with this ID or slug
search_on – Properties to search on, when combined with q. Searches across all properties by default
viewer_id – See reviewed
reviewed – Observations have been reviewed by the user with ID equal to the value of the
viewer_id
parameterlocale – Locale preference for taxon common names
preferred_place_id – Place preference for regional taxon common names
ttl – Set the
Cache-Control
HTTP header with this value asmax-age
, in secondsnelat – NE latitude of bounding box
nelng – NE longitude of bounding box
swlat – SW latitude of bounding box
swlng – SW longitude of bounding box
page – Page number of results to return
per_page – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order – Sort order
order_by – Field to sort on
count_only – Only return a count of results; alias for
per_page=0
reverse – Reverse the order of results; alias for
order='descending'
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> response = get_observation_identifiers(place_id=72645) >>> pprint(response) [409010 ] jdoe42 (Jane Doe) [691216 ] jbrown252 (James Brown) [3959037 ] tnsparkleberry
Example Response
{ "total_results": 2999, "page": 1, "per_page": 500, "results": [ { "user_id": 53153, "count": 1787, "user": { "id": 53153, "login": "willkuhn", "spam": false, "suspended": false, "created_at": "2014-09-15T18:38:59+00:00", "login_autocomplete": "willkuhn", "login_exact": "willkuhn", "name": "Will Kuhn", "name_autocomplete": "Will Kuhn", "orcid": "https://orcid.org/0000-0002-5506-6379", "icon": "https://static.inaturalist.org/attachments/users/icons/53153/thumb.jpeg?1606488424", "observations_count": 2945, "identifications_count": 3895, "journal_posts_count": 0, "activity_count": 6840, "species_count": 1230, "universal_search_rank": 2945, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/53153/medium.jpeg?1606488424" } }, { "user_id": 105391, "count": 1165, "user": { "id": 105391, "login": "jtuttle", "spam": false, "suspended": false, "created_at": "2015-05-25T21:56:21+00:00", "login_autocomplete": "jtuttle", "login_exact": "jtuttle", "name": "", "name_autocomplete": "", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/105391/thumb.jpg?1475546106", "observations_count": 12473, "identifications_count": 27628, "journal_posts_count": 0, "activity_count": 40101, "species_count": 3217, "universal_search_rank": 12473, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/105391/medium.jpg?1475546106" } }, { "user_id": 32654, "count": 1012, "user": { "id": 32654, "login": "eraskin", "spam": false, "suspended": false, "created_at": "2014-03-19T18:35:39+00:00", "login_autocomplete": "eraskin", "login_exact": "eraskin", "name": "Evan M. Raskin", "name_autocomplete": "Evan M. Raskin", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/32654/thumb.jpg?1533126488", "observations_count": 5150, "identifications_count": 18213, "journal_posts_count": 3, "activity_count": 23366, "species_count": 2320, "universal_search_rank": 5150, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/32654/medium.jpg?1533126488" } }, { "user_id": 1064292, "count": 907, "user": { "id": 1064292, "login": "syrherp", "spam": false, "suspended": false, "created_at": "2018-07-04T04:58:43+00:00", "login_autocomplete": "syrherp", "login_exact": "syrherp", "name": "Anthony Brais", "name_autocomplete": "Anthony Brais", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/1064292/thumb.jpg?1537157949", "observations_count": 3788, "identifications_count": 33279, "journal_posts_count": 0, "activity_count": 37067, "species_count": 472, "universal_search_rank": 3788, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/1064292/medium.jpg?1537157949" } }, { "user_id": 2233645, "count": 851, "user": { "id": 2233645, "login": "jak2113", "spam": false, "suspended": false, "created_at": "2019-09-09T15:42:57+00:00", "login_autocomplete": "jak2113", "login_exact": "jak2113", "name": "", "name_autocomplete": "", "orcid": null, "icon": null, "observations_count": 287, "identifications_count": 1623, "journal_posts_count": 0, "activity_count": 1910, "species_count": 206, "universal_search_rank": 287, "roles": [], "site_id": 1, "icon_url": null } }, { "user_id": 19073, "count": 781, "user": { "id": 19073, "login": "choess", "spam": false, "suspended": false, "created_at": "2013-07-13T18:27:48+00:00", "login_autocomplete": "choess", "login_exact": "choess", "name": "", "name_autocomplete": "", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/19073/thumb.jpg?1475537701", "observations_count": 5067, "identifications_count": 152943, "journal_posts_count": 11, "activity_count": 158021, "species_count": 1284, "universal_search_rank": 5067, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/19073/medium.jpg?1475537701" } }, { "user_id": 26905, "count": 668, "user": { "id": 26905, "login": "polemoniaceae", "spam": false, "suspended": false, "created_at": "2013-12-04T20:28:55+00:00", "login_autocomplete": "polemoniaceae", "login_exact": "polemoniaceae", "name": "Jeff", "name_autocomplete": "Jeff", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/26905/thumb.jpg?1475541432", "observations_count": 251, "identifications_count": 129664, "journal_posts_count": 0, "activity_count": 129915, "species_count": 222, "universal_search_rank": 251, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/26905/medium.jpg?1475541432" } }, { "user_id": 854537, "count": 622, "user": { "id": 854537, "login": "maxallen", "spam": false, "suspended": false, "created_at": "2018-04-16T22:12:08+00:00", "login_autocomplete": "maxallen", "login_exact": "maxallen", "name": "", "name_autocomplete": "", "orcid": "https://orcid.org/0000-0001-8976-889X", "icon": "https://static.inaturalist.org/attachments/users/icons/854537/thumb.jpg?1529523533", "observations_count": 1938, "identifications_count": 524561, "journal_posts_count": 4, "activity_count": 526503, "species_count": 675, "universal_search_rank": 1938, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/854537/medium.jpg?1529523533" } }, { "user_id": 755672, "count": 621, "user": { "id": 755672, "login": "ddennism", "spam": false, "suspended": false, "created_at": "2018-01-30T02:28:08+00:00", "login_autocomplete": "ddennism", "login_exact": "ddennism", "name": "Daniel McClosky", "name_autocomplete": "Daniel McClosky", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/755672/thumb.jpg?1571254550", "observations_count": 3369, "identifications_count": 38204, "journal_posts_count": 8, "activity_count": 41581, "species_count": 774, "universal_search_rank": 3369, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/755672/medium.jpg?1571254550" } }, { "user_id": 2229996, "count": 616, "user": { "id": 2229996, "login": "annkatrinrose", "spam": false, "suspended": false, "created_at": "2019-09-08T18:45:38+00:00", "login_autocomplete": "annkatrinrose", "login_exact": "annkatrinrose", "name": "Annkatrin Rose", "name_autocomplete": "Annkatrin Rose", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/2229996/thumb.jpg?1567997735", "observations_count": 3799, "identifications_count": 9286, "journal_posts_count": 6, "activity_count": 13091, "species_count": 1024, "universal_search_rank": 3799, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/2229996/medium.jpg?1567997735" } }, { "user_id": 324885, "count": 599, "user": { "id": 324885, "login": "lucareptile", "spam": false, "suspended": false, "created_at": "2016-09-09T00:19:57+00:00", "login_autocomplete": "lucareptile", "login_exact": "lucareptile", "name": "Luca Catanzaro", "name_autocomplete": "Luca Catanzaro", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/324885/thumb.jpg?1566422568", "observations_count": 21480, "identifications_count": 109080, "journal_posts_count": 0, "activity_count": 130560, "species_count": 2470, "universal_search_rank": 21480, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/324885/medium.jpg?1566422568" } }, { "user_id": 1210028, "count": 577, "user": { "id": 1210028, "login": "pynklynx", "spam": false, "suspended": false, "created_at": "2018-09-15T03:55:25+00:00", "login_autocomplete": "pynklynx", "login_exact": "pynklynx", "name": "", "name_autocomplete": "", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/1210028/thumb.jpg?1538262214", "observations_count": 6673, "identifications_count": 74690, "journal_posts_count": 0, "activity_count": 81363, "species_count": 1310, "universal_search_rank": 6673, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/1210028/medium.jpg?1538262214" } }, { "user_id": 1168695, "count": 530, "user": { "id": 1168695, "login": "trscavo", "spam": false, "suspended": false, "created_at": "2018-08-28T18:14:51+00:00", "login_autocomplete": "trscavo", "login_exact": "trscavo", "name": "Tom Scavo", "name_autocomplete": "Tom Scavo", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/1168695/thumb.png?1535480090", "observations_count": 4541, "identifications_count": 30780, "journal_posts_count": 0, "activity_count": 35321, "species_count": 554, "universal_search_rank": 4541, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/1168695/medium.png?1535480090" } }, { "user_id": 187480, "count": 468, "user": { "id": 187480, "login": "wdvanhem", "spam": false, "suspended": false, "created_at": "2016-03-03T13:54:17+00:00", "login_autocomplete": "wdvanhem", "login_exact": "wdvanhem", "name": "Will Van Hemessen", "name_autocomplete": "Will Van Hemessen", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/187480/thumb.jpeg?1586740535", "observations_count": 8050, "identifications_count": 145345, "journal_posts_count": 1, "activity_count": 153396, "species_count": 2482, "universal_search_rank": 8050, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/187480/medium.jpeg?1586740535" } } ] }
- pyinaturalist.v1.observations.get_observation_observers(**params)#
Get observers of observations matching the search criteria and the count of observations and distinct taxa of rank species they have observed.
Notes
API reference: GET /observations/observers
Options for
order_by
are ‘observation_count’ (default) or ‘species_count’This endpoint will only return up to 500 results
See this issue for more details: https://github.com/inaturalist/iNaturalistAPI/issues/235
- Parameters:
q – Search observation properties
d1 – Must be observed on or after this date
d2 – Must be observed on or before this date
day – Must be observed within this day of the month
month – Must be observed within this month
year – Must be observed within this year
license – Observation must have this license
photo_license – Must have at least one photo with this license
out_of_range – Observations whose taxa are outside their known ranges
list_id – Taxon must be in the list with this ID
quality_grade – Must have this quality grade
id – Must have this observation ID
taxon_id – Only show observations of these taxa and their descendants
taxon_name – Taxon must have a scientific or common name matching this string
iconic_taxa – Taxon must by within this iconic taxon
updated_since – Must be updated since this time
acc – Whether or not positional accuracy / coordinate uncertainty has been specified
captive – Captive or cultivated observations
endemic – Observations whose taxa are endemic to their location
geo – Observations that are georeferenced
id_please – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified – Observations that have community identifications
introduced – Observations whose taxa are introduced in their location
mappable – Observations that show on map tiles
native – Observations whose taxa are native to their location
pcid – 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 – Observations with photos
popular – Observations that have been favorited by at least one user
sounds – Observations with sounds
taxon_is_active – Observations of active taxon concepts
threatened – Observations whose taxa are threatened in their location
verifiable – Observations with a
quality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id – Must not have this ID
place_id – Must be observed within the place with this ID
project_id – Must be added to the project this ID or slug
rank – Taxon must have this rank
site_id – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype – Must have an observation field value with this datatype
sound_license – Must have at least one sound with this license
without_taxon_id – Exclude observations of these taxa and their descendants
user_id – Observer must have this user ID or login
user_login – Observer must have this user login
ident_user_id – Identifier must have this user ID or login
term_id – Must have an annotation using this controlled term ID
term_value_id – Must have an annotation using this controlled value ID. Must be combined with the
term_id
parameterwithout_term_value_id – Exclude observations with annotations using this controlled value ID. Must be combined with the
term_id
parameteracc_above – Must have an positional accuracy above this value (meters)
acc_below – Must have an positional accuracy below this value (meters)
acc_below_or_unknown – Must have an positional accuracy below this value (meters) or unknown
created_d1 – Must be created at or after this time
created_d2 – Must be created at or before this time
created_on – Must be created on this date
observed_on – Must be observed on this date
unobserved_by_user_id – Must not be of a taxon previously observed by this user
apply_project_rules_for – Must match the rules of the project with this ID or slug
cs – Taxon must have this conservation status code. If the
place_id
parameter is also specified, this will only consider statuses specific to that placecsa – 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 placecsi – Taxon must have this IUCN conservation status. If the
place_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy – Must have this geoprivacy setting
taxon_geoprivacy – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank – Taxon must have this rank or lower
lrank – Taxon must have this rank or higher
id_above – Must have an ID above this value
id_below – Must have an ID below this value
identifications – Identifications must meet these criteria
lat – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)lng – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)radius – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project – Must not be in the project with this ID or slug
not_matching_project_rules_for – Must not match the rules of the project with this ID or slug
search_on – Properties to search on, when combined with q. Searches across all properties by default
viewer_id – See reviewed
reviewed – Observations have been reviewed by the user with ID equal to the value of the
viewer_id
parameterlocale – Locale preference for taxon common names
preferred_place_id – Place preference for regional taxon common names
ttl – Set the
Cache-Control
HTTP header with this value asmax-age
, in secondsnelat – NE latitude of bounding box
nelng – NE longitude of bounding box
swlat – SW latitude of bounding box
swlng – SW longitude of bounding box
page – Page number of results to return
per_page – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order – Sort order
order_by – Field to sort on
count_only – Only return a count of results; alias for
per_page=0
reverse – Reverse the order of results; alias for
order='descending'
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> response = get_observation_observers(place_id=72645, order_by='species_count') >>> pprint(response) [1566366 ] fossa1211 [674557 ] schurchin [5813 ] fluffberger (Fluff Berger)
Example Response
{ "total_results": 3948, "page": 1, "per_page": 500, "results": [ { "user_id": 15723, "observation_count": 2346, "species_count": 605, "user": { "id": 15723, "login": "reallifeecology", "spam": false, "suspended": false, "created_at": "2013-04-27T19:32:15+00:00", "login_autocomplete": "reallifeecology", "login_exact": "reallifeecology", "name": "Jonathan (JC) Carpenter", "name_autocomplete": "Jonathan (JC) Carpenter", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/15723/thumb.jpg?1475535710", "observations_count": 36365, "identifications_count": 2086, "journal_posts_count": 3, "activity_count": 38454, "species_count": 5740, "universal_search_rank": 36365, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/15723/medium.jpg?1475535710" } }, { "user_id": 1085809, "observation_count": 1125, "species_count": 393, "user": { "id": 1085809, "login": "anneturner", "spam": false, "suspended": false, "created_at": "2018-07-14T16:12:14+00:00", "login_autocomplete": "anneturner", "login_exact": "anneturner", "name": "Anne Turner", "name_autocomplete": "Anne Turner", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/1085809/thumb.jpeg?1555073435", "observations_count": 1441, "identifications_count": 125, "journal_posts_count": 0, "activity_count": 1566, "species_count": 553, "universal_search_rank": 1441, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/1085809/medium.jpeg?1555073435" } }, { "user_id": 53153, "observation_count": 890, "species_count": 324, "user": { "id": 53153, "login": "willkuhn", "spam": false, "suspended": false, "created_at": "2014-09-15T18:38:59+00:00", "login_autocomplete": "willkuhn", "login_exact": "willkuhn", "name": "Will Kuhn", "name_autocomplete": "Will Kuhn", "orcid": "https://orcid.org/0000-0002-5506-6379", "icon": "https://static.inaturalist.org/attachments/users/icons/53153/thumb.jpeg?1606488424", "observations_count": 2945, "identifications_count": 3895, "journal_posts_count": 0, "activity_count": 6840, "species_count": 1230, "universal_search_rank": 2945, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/53153/medium.jpeg?1606488424" } }, { "user_id": 176684, "observation_count": 806, "species_count": 348, "user": { "id": 176684, "login": "gmontgomery", "spam": false, "suspended": false, "created_at": "2016-02-06T21:58:36+00:00", "login_autocomplete": "gmontgomery", "login_exact": "gmontgomery", "name": "Graham Montgomery", "name_autocomplete": "Graham Montgomery", "orcid": "https://orcid.org/0000-0002-8217-8800", "icon": "https://static.inaturalist.org/attachments/users/icons/176684/thumb.jpeg?1600827496", "observations_count": 7986, "identifications_count": 4072, "journal_posts_count": 0, "activity_count": 12058, "species_count": 4146, "universal_search_rank": 7986, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/176684/medium.jpeg?1600827496" } }, { "user_id": 1019810, "observation_count": 791, "species_count": 279, "user": { "id": 1019810, "login": "jduffy", "spam": false, "suspended": false, "created_at": "2018-06-11T15:58:21+00:00", "login_autocomplete": "jduffy", "login_exact": "jduffy", "name": "Jim", "name_autocomplete": "Jim", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/1019810/thumb.jpg?1551496934", "observations_count": 823, "identifications_count": 2, "journal_posts_count": 0, "activity_count": 825, "species_count": 313, "universal_search_rank": 823, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/1019810/medium.jpg?1551496934" } }, { "user_id": 906019, "observation_count": 693, "species_count": 190, "user": { "id": 906019, "login": "akfishmom", "spam": false, "suspended": false, "created_at": "2018-04-26T20:56:39+00:00", "login_autocomplete": "akfishmom", "login_exact": "akfishmom", "name": null, "name_autocomplete": null, "orcid": null, "icon": null, "observations_count": 822, "identifications_count": 6, "journal_posts_count": 0, "activity_count": 828, "species_count": 322, "universal_search_rank": 822, "roles": [], "site_id": 1, "icon_url": null } }, { "user_id": 17201, "observation_count": 661, "species_count": 328, "user": { "id": 17201, "login": "matthewherron", "spam": false, "suspended": false, "created_at": "2013-05-29T02:13:48+00:00", "login_autocomplete": "matthewherron", "login_exact": "matthewherron", "name": "Matthew Herron", "name_autocomplete": "Matthew Herron", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/17201/thumb.jpeg?1475536451", "observations_count": 7694, "identifications_count": 1467, "journal_posts_count": 0, "activity_count": 9161, "species_count": 2195, "universal_search_rank": 7694, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/17201/medium.jpeg?1475536451" } }, { "user_id": 282998, "observation_count": 640, "species_count": 212, "user": { "id": 282998, "login": "dunhamkc", "spam": false, "suspended": false, "created_at": "2016-08-06T13:19:36+00:00", "login_autocomplete": "dunhamkc", "login_exact": "dunhamkc", "name": "Keely Dunham", "name_autocomplete": "Keely Dunham", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/282998/thumb.jpg?1526954269", "observations_count": 2418, "identifications_count": 725, "journal_posts_count": 0, "activity_count": 3143, "species_count": 796, "universal_search_rank": 2418, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/282998/medium.jpg?1526954269" } }, { "user_id": 843086, "observation_count": 562, "species_count": 235, "user": { "id": 843086, "login": "b_georgic", "spam": false, "suspended": false, "created_at": "2018-04-10T16:31:49+00:00", "login_autocomplete": "b_georgic", "login_exact": "b_georgic", "name": "", "name_autocomplete": "", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/843086/thumb.jpg?1606070123", "observations_count": 1151, "identifications_count": 0, "journal_posts_count": 0, "activity_count": 1151, "species_count": 653, "universal_search_rank": 1151, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/843086/medium.jpg?1606070123" } }, { "user_id": 574477, "observation_count": 442, "species_count": 171, "user": { "id": 574477, "login": "pinus_taeda", "spam": false, "suspended": false, "created_at": "2017-08-10T18:00:10+00:00", "login_autocomplete": "pinus_taeda", "login_exact": "pinus_taeda", "name": null, "name_autocomplete": null, "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/574477/thumb.jpg?1527608024", "observations_count": 1846, "identifications_count": 1141, "journal_posts_count": 0, "activity_count": 2987, "species_count": 551, "universal_search_rank": 1846, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/574477/medium.jpg?1527608024" } }, { "user_id": 2148023, "observation_count": 420, "species_count": 149, "user": { "id": 2148023, "login": "christopher514", "spam": false, "suspended": false, "created_at": "2019-08-19T02:14:52+00:00", "login_autocomplete": "christopher514", "login_exact": "christopher514", "name": "Christopher Gontarski", "name_autocomplete": "Christopher Gontarski", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/2148023/thumb.jpeg?1566180892", "observations_count": 567, "identifications_count": 0, "journal_posts_count": 0, "activity_count": 567, "species_count": 287, "universal_search_rank": 567, "roles": [], "site_id": null, "icon_url": "https://static.inaturalist.org/attachments/users/icons/2148023/medium.jpeg?1566180892" } }, { "user_id": 362446, "observation_count": 398, "species_count": 237, "user": { "id": 362446, "login": "pwdeacon", "spam": false, "suspended": false, "created_at": "2016-11-02T20:47:19+00:00", "login_autocomplete": "pwdeacon", "login_exact": "pwdeacon", "name": "Pat Deacon", "name_autocomplete": "Pat Deacon", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/362446/thumb.jpeg?1575167373", "observations_count": 12962, "identifications_count": 7883, "journal_posts_count": 0, "activity_count": 20845, "species_count": 3029, "universal_search_rank": 12962, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/362446/medium.jpeg?1575167373" } }, { "user_id": 93979, "observation_count": 373, "species_count": 23, "user": { "id": 93979, "login": "mcaterino", "spam": false, "suspended": false, "created_at": "2015-04-28T12:18:05+00:00", "login_autocomplete": "mcaterino", "login_exact": "mcaterino", "name": "Michael Caterino", "name_autocomplete": "Michael Caterino", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/93979/thumb.jpg?1568554017", "observations_count": 1708, "identifications_count": 153, "journal_posts_count": 0, "activity_count": 1861, "species_count": 174, "universal_search_rank": 1708, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/93979/medium.jpg?1568554017" } }, { "user_id": 17283, "observation_count": 334, "species_count": 252, "user": { "id": 17283, "login": "layla", "spam": false, "suspended": false, "created_at": "2013-05-30T20:06:01+00:00", "login_autocomplete": "layla", "login_exact": "layla", "name": "Layla Dishman", "name_autocomplete": "Layla Dishman", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/17283/thumb.jpg?1475536494", "observations_count": 2831, "identifications_count": 1414, "journal_posts_count": 0, "activity_count": 4245, "universal_search_rank": 2831, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/17283/medium.jpg?1475536494" } }, { "user_id": 2346515, "observation_count": 317, "species_count": 77, "user": { "id": 2346515, "login": "sarahroth", "spam": false, "suspended": false, "created_at": "2019-10-08T15:37:36+00:00", "login_autocomplete": "sarahroth", "login_exact": "sarahroth", "name": "Sarah Roth", "name_autocomplete": "Sarah Roth", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/2346515/thumb.png?1570549056", "observations_count": 473, "identifications_count": 0, "journal_posts_count": 0, "activity_count": 473, "species_count": 126, "universal_search_rank": 473, "roles": [], "site_id": null, "icon_url": "https://static.inaturalist.org/attachments/users/icons/2346515/medium.png?1570549056" } }, { "user_id": 159616, "observation_count": 314, "species_count": 149, "user": { "id": 159616, "login": "cdance", "spam": false, "suspended": false, "created_at": "2015-12-09T19:36:11+00:00", "login_autocomplete": "cdance", "login_exact": "cdance", "name": "CDance", "name_autocomplete": "CDance", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/159616/thumb.jpg?1566762916", "observations_count": 2900, "identifications_count": 264, "journal_posts_count": 3, "activity_count": 3167, "species_count": 1165, "universal_search_rank": 2900, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/159616/medium.jpg?1566762916" } }, { "user_id": 1359300, "observation_count": 310, "species_count": 148, "user": { "id": 1359300, "login": "spyingnaturalist", "spam": false, "suspended": false, "created_at": "2018-11-20T01:19:01+00:00", "login_autocomplete": "spyingnaturalist", "login_exact": "spyingnaturalist", "name": "", "name_autocomplete": "", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/1359300/thumb.jpg?1552909758", "observations_count": 8286, "identifications_count": 5371, "journal_posts_count": 0, "activity_count": 13657, "species_count": 2749, "universal_search_rank": 8286, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/1359300/medium.jpg?1552909758" } }, { "user_id": 899236, "observation_count": 292, "species_count": 177, "user": { "id": 899236, "login": "palustris314", "spam": false, "suspended": false, "created_at": "2018-04-25T17:22:45+00:00", "login_autocomplete": "palustris314", "login_exact": "palustris314", "name": "Greg J Schmidt", "name_autocomplete": "Greg J Schmidt", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/899236/thumb.jpg?1526651056", "observations_count": 1599, "identifications_count": 139, "journal_posts_count": 0, "activity_count": 1738, "species_count": 1013, "universal_search_rank": 1599, "roles": [], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/899236/medium.jpg?1526651056" } }, { "user_id": 187480, "observation_count": 252, "species_count": 172, "user": { "id": 187480, "login": "wdvanhem", "spam": false, "suspended": false, "created_at": "2016-03-03T13:54:17+00:00", "login_autocomplete": "wdvanhem", "login_exact": "wdvanhem", "name": "Will Van Hemessen", "name_autocomplete": "Will Van Hemessen", "orcid": null, "icon": "https://static.inaturalist.org/attachments/users/icons/187480/thumb.jpeg?1586740535", "observations_count": 8050, "identifications_count": 145345, "journal_posts_count": 1, "activity_count": 153396, "species_count": 2482, "universal_search_rank": 8050, "roles": [ "curator" ], "site_id": 1, "icon_url": "https://static.inaturalist.org/attachments/users/icons/187480/medium.jpeg?1586740535" } } ] }
- pyinaturalist.v1.observations.get_observation_popular_field_values(**params)#
Get controlled terms values and a monthly histogram of observations matching the search
Notes
API reference: GET /observations/popular_field_values
- Parameters:
q – Search observation properties
d1 – Must be observed on or after this date
d2 – Must be observed on or before this date
day – Must be observed within this day of the month
month – Must be observed within this month
year – Must be observed within this year
license – Observation must have this license
photo_license – Must have at least one photo with this license
out_of_range – Observations whose taxa are outside their known ranges
list_id – Taxon must be in the list with this ID
quality_grade – Must have this quality grade
id – Must have this observation ID
taxon_id – Only show observations of these taxa and their descendants
taxon_name – Taxon must have a scientific or common name matching this string
iconic_taxa – Taxon must by within this iconic taxon
updated_since – Must be updated since this time
acc – Whether or not positional accuracy / coordinate uncertainty has been specified
captive – Captive or cultivated observations
endemic – Observations whose taxa are endemic to their location
geo – Observations that are georeferenced
id_please – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified – Observations that have community identifications
introduced – Observations whose taxa are introduced in their location
mappable – Observations that show on map tiles
native – Observations whose taxa are native to their location
pcid – 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 – Observations with photos
popular – Observations that have been favorited by at least one user
sounds – Observations with sounds
taxon_is_active – Observations of active taxon concepts
threatened – Observations whose taxa are threatened in their location
verifiable – Observations with a
quality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id – Must not have this ID
place_id – Must be observed within the place with this ID
project_id – Must be added to the project this ID or slug
rank – Taxon must have this rank
site_id – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype – Must have an observation field value with this datatype
sound_license – Must have at least one sound with this license
without_taxon_id – Exclude observations of these taxa and their descendants
user_id – Observer must have this user ID or login
user_login – Observer must have this user login
ident_user_id – Identifier must have this user ID or login
term_id – Must have an annotation using this controlled term ID
term_value_id – Must have an annotation using this controlled value ID. Must be combined with the
term_id
parameterwithout_term_value_id – Exclude observations with annotations using this controlled value ID. Must be combined with the
term_id
parameteracc_above – Must have an positional accuracy above this value (meters)
acc_below – Must have an positional accuracy below this value (meters)
acc_below_or_unknown – Must have an positional accuracy below this value (meters) or unknown
created_d1 – Must be created at or after this time
created_d2 – Must be created at or before this time
created_on – Must be created on this date
observed_on – Must be observed on this date
unobserved_by_user_id – Must not be of a taxon previously observed by this user
apply_project_rules_for – Must match the rules of the project with this ID or slug
cs – Taxon must have this conservation status code. If the
place_id
parameter is also specified, this will only consider statuses specific to that placecsa – 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 placecsi – Taxon must have this IUCN conservation status. If the
place_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy – Must have this geoprivacy setting
taxon_geoprivacy – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank – Taxon must have this rank or lower
lrank – Taxon must have this rank or higher
id_above – Must have an ID above this value
id_below – Must have an ID below this value
identifications – Identifications must meet these criteria
lat – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)lng – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)radius – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project – Must not be in the project with this ID or slug
not_matching_project_rules_for – Must not match the rules of the project with this ID or slug
search_on – Properties to search on, when combined with q. Searches across all properties by default
viewer_id – See reviewed
reviewed – Observations have been reviewed by the user with ID equal to the value of the
viewer_id
parameterlocale – Locale preference for taxon common names
preferred_place_id – Place preference for regional taxon common names
ttl – Set the
Cache-Control
HTTP header with this value asmax-age
, in secondsnelat – NE latitude of bounding box
nelng – NE longitude of bounding box
swlat – SW latitude of bounding box
swlng – SW longitude of bounding box
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> response = get_observation_popular_field_values( ... species_name='Danaus plexippus', place_id=24, ... )
Example Response
{ 'total_results': 10, 'page': 1, 'per_page': 10, 'results': [ { 'count': 231, 'month_of_year': { 1: 0, 2: 0, 3: 0, 4: 1, 5: 21, 6: 38, 7: 33, 8: 47, 9: 62, 10: 29, 11: 0, 12: 0, }, 'controlled_attribute': { 'id': 1, 'ontology_uri': '', 'uri': '', 'is_value': False, 'multivalued': False, 'uuid': 'f895e9ce-fb2d-4a63-a486-ac424f497e02', 'values': [ { 'id': 2, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '48722062-360d-4b6e-b72c-129c7066b3fa', 'taxon_ids': [1], 'label': 'Adult', }, { 'id': 3, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': 'b3b6e6d0-cbce-4886-bb2b-55bd99d44586', 'taxon_ids': [47792, 50190], 'label': 'Teneral', }, { 'id': 4, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': 'c883d7b5-4eb5-4ad1-8cbc-56f5e2555869', 'taxon_ids': [ 47208, 48763, 49369, 47157, 47822, 47201, 62164, 47864, 83204, 83202, 47794, ], 'label': 'Pupa', }, { 'id': 5, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '0f0c03c2-4741-46db-a19a-7cac8a96d667', 'taxon_ids': [ 47793, 81769, 56834, 47744, 47792, 47651, 47504, 48011, 48112, 53795, 47198, 83187, 83201, 83200, ], 'label': 'Nymph', }, { 'id': 6, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '8ff477bd-0949-4a7a-9c67-64a8e3786876', 'taxon_ids': [ 20978, 47208, 47822, 47201, 47157, 49369, 47864, 48763, 47794, 83204, 83202, 62164, ], 'label': 'Larva', }, { 'id': 7, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': 'fe58aedb-4375-4096-a61f-1cd718cf319f', 'taxon_ids': [ 43233, 47120, 85497, 47178, 20978, 3, 49231, 47273, 60450, 49099, 26036, 47115, ], 'label': 'Egg', }, { 'id': 8, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '3245d167-ffff-44ce-a366-cfc8f711d73f', 'taxon_ids': [1], 'excepted_taxon_ids': [184884], 'label': 'Juvenile', }, { 'id': 16, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '6ff4f9f8-7bc0-4d50-bee5-7072d11a04ef', 'taxon_ids': [48011], 'label': 'Subimago', }, ], 'taxon_ids': [1], 'excepted_taxon_ids': [43583], 'label': 'Life Stage', }, 'controlled_value': { 'id': 2, 'ontology_uri': '', 'uri': '', 'is_value': True, 'blocking': False, 'taxon_ids': [1], 'label': 'Adult', 'values': [], }, }, { 'count': 150, 'month_of_year': { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0, 6: 59, 7: 27, 8: 40, 9: 24, 10: 0, 11: 0, 12: 0, }, 'controlled_attribute': { 'id': 1, 'ontology_uri': '', 'uri': '', 'is_value': False, 'multivalued': False, 'uuid': 'f895e9ce-fb2d-4a63-a486-ac424f497e02', 'values': [ { 'id': 2, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '48722062-360d-4b6e-b72c-129c7066b3fa', 'taxon_ids': [1], 'label': 'Adult', }, { 'id': 3, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': 'b3b6e6d0-cbce-4886-bb2b-55bd99d44586', 'taxon_ids': [47792, 50190], 'label': 'Teneral', }, { 'id': 4, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': 'c883d7b5-4eb5-4ad1-8cbc-56f5e2555869', 'taxon_ids': [ 47208, 48763, 49369, 47157, 47822, 47201, 62164, 47864, 83204, 83202, 47794, ], 'label': 'Pupa', }, { 'id': 5, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '0f0c03c2-4741-46db-a19a-7cac8a96d667', 'taxon_ids': [ 47793, 81769, 56834, 47744, 47792, 47651, 47504, 48011, 48112, 53795, 47198, 83187, 83201, 83200, ], 'label': 'Nymph', }, { 'id': 6, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '8ff477bd-0949-4a7a-9c67-64a8e3786876', 'taxon_ids': [ 20978, 47208, 47822, 47201, 47157, 49369, 47864, 48763, 47794, 83204, 83202, 62164, ], 'label': 'Larva', }, { 'id': 7, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': 'fe58aedb-4375-4096-a61f-1cd718cf319f', 'taxon_ids': [ 43233, 47120, 85497, 47178, 20978, 3, 49231, 47273, 60450, 49099, 26036, 47115, ], 'label': 'Egg', }, { 'id': 8, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '3245d167-ffff-44ce-a366-cfc8f711d73f', 'taxon_ids': [1], 'excepted_taxon_ids': [184884], 'label': 'Juvenile', }, { 'id': 16, 'ontology_uri': '', 'uri': '', 'blocking': False, 'uuid': '6ff4f9f8-7bc0-4d50-bee5-7072d11a04ef', 'taxon_ids': [48011], 'label': 'Subimago', }, ], 'taxon_ids': [1], 'excepted_taxon_ids': [43583], 'label': 'Life Stage', }, 'controlled_value': { 'id': 6, 'ontology_uri': '', 'uri': '', 'is_value': True, 'blocking': False, 'taxon_ids': [ 20978, 47208, 47822, 47201, 47157, 49369, 47864, 48763, 47794, 83204, 83202, 62164, ], 'label': 'Larva', 'values': [], }, }, ], }
- pyinaturalist.v1.observations.get_observation_species_counts(**params)#
Get all species (or other ‘leaf taxa’) associated with observations matching the search criteria, and the count of observations they are associated with. Leaf taxa are the leaves of the taxonomic tree, e.g., species, subspecies, variety, etc.
Notes
API reference: GET /observations/species_counts
- Parameters:
q – Search observation properties
d1 – Must be observed on or after this date
d2 – Must be observed on or before this date
day – Must be observed within this day of the month
month – Must be observed within this month
year – Must be observed within this year
license – Observation must have this license
photo_license – Must have at least one photo with this license
out_of_range – Observations whose taxa are outside their known ranges
list_id – Taxon must be in the list with this ID
quality_grade – Must have this quality grade
id – Must have this observation ID
taxon_id – Only show observations of these taxa and their descendants
taxon_name – Taxon must have a scientific or common name matching this string
iconic_taxa – Taxon must by within this iconic taxon
updated_since – Must be updated since this time
acc – Whether or not positional accuracy / coordinate uncertainty has been specified
captive – Captive or cultivated observations
endemic – Observations whose taxa are endemic to their location
geo – Observations that are georeferenced
id_please – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified – Observations that have community identifications
introduced – Observations whose taxa are introduced in their location
mappable – Observations that show on map tiles
native – Observations whose taxa are native to their location
pcid – 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 – Observations with photos
popular – Observations that have been favorited by at least one user
sounds – Observations with sounds
taxon_is_active – Observations of active taxon concepts
threatened – Observations whose taxa are threatened in their location
verifiable – Observations with a
quality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id – Must not have this ID
place_id – Must be observed within the place with this ID
project_id – Must be added to the project this ID or slug
rank – Taxon must have this rank
site_id – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype – Must have an observation field value with this datatype
sound_license – Must have at least one sound with this license
without_taxon_id – Exclude observations of these taxa and their descendants
user_id – Observer must have this user ID or login
user_login – Observer must have this user login
ident_user_id – Identifier must have this user ID or login
term_id – Must have an annotation using this controlled term ID
term_value_id – Must have an annotation using this controlled value ID. Must be combined with the
term_id
parameterwithout_term_value_id – Exclude observations with annotations using this controlled value ID. Must be combined with the
term_id
parameteracc_above – Must have an positional accuracy above this value (meters)
acc_below – Must have an positional accuracy below this value (meters)
acc_below_or_unknown – Must have an positional accuracy below this value (meters) or unknown
created_d1 – Must be created at or after this time
created_d2 – Must be created at or before this time
created_on – Must be created on this date
observed_on – Must be observed on this date
unobserved_by_user_id – Must not be of a taxon previously observed by this user
apply_project_rules_for – Must match the rules of the project with this ID or slug
cs – Taxon must have this conservation status code. If the
place_id
parameter is also specified, this will only consider statuses specific to that placecsa – 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 placecsi – Taxon must have this IUCN conservation status. If the
place_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy – Must have this geoprivacy setting
taxon_geoprivacy – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank – Taxon must have this rank or lower
lrank – Taxon must have this rank or higher
id_above – Must have an ID above this value
id_below – Must have an ID below this value
identifications – Identifications must meet these criteria
lat – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)lng – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)radius – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project – Must not be in the project with this ID or slug
not_matching_project_rules_for – Must not match the rules of the project with this ID or slug
search_on – Properties to search on, when combined with q. Searches across all properties by default
viewer_id – See reviewed
reviewed – Observations have been reviewed by the user with ID equal to the value of the
viewer_id
parameterlocale – Locale preference for taxon common names
preferred_place_id – Place preference for regional taxon common names
ttl – Set the
Cache-Control
HTTP header with this value asmax-age
, in secondsnelat – NE latitude of bounding box
nelng – NE longitude of bounding box
swlat – SW latitude of bounding box
swlng – SW longitude of bounding box
page – Page number of results to return
per_page – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order – Sort order
order_by – Field to sort on
count_only – Only return a count of results; alias for
per_page=0
reverse – Reverse the order of results; alias for
order='descending'
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> response = get_observation_species_counts(user_login='my_username', quality_grade='research') >>> pprint(response) [62060] Species: Palomena prasina (Green Shield Bug): 10 [84804] Species: Graphosoma italicum (European Striped Shield Bug): 8 [55727] Species: Cymbalaria muralis (Ivy-leaved toadflax): 3 ...
Example Response
{ 'total_results': 243, 'page': 1, 'per_page': 500, 'results': [ { 'count': 31, 'taxon': { 'observations_count': 81696, 'taxon_schemes_count': 2, 'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/471714/48486/333790/333796/48487', 'is_active': True, 'flag_counts': {'unresolved': 0, 'resolved': 3}, 'wikipedia_url': 'http://en.wikipedia.org/wiki/Harmonia_axyridis', 'current_synonymous_taxon_ids': None, 'iconic_taxon_id': 47158, 'rank_level': 10, 'taxon_changes_count': 1, 'atlas_id': 1241, 'complete_species_count': None, 'parent_id': 48487, 'name': 'Harmonia axyridis', 'rank': 'species', 'extinct': False, 'id': 48484, 'default_photo': { 'square_url': 'https://static.inaturalist.org/photos/30978499/square.jpg?1549228178', 'attribution': '(c) Paolo Mazzei, all rights reserved', 'flags': [], 'medium_url': 'https://static.inaturalist.org/photos/30978499/medium.jpg?1549228178', 'id': 30978499, 'license_code': None, 'original_dimensions': {'width': 800, 'height': 600}, 'url': 'https://static.inaturalist.org/photos/30978499/square.jpg?1549228178', }, 'ancestor_ids': [ 48460, 1, 47120, 372739, 47158, 184884, 47208, 71130, 372852, 471714, 48486, 333790, 333796, 48487, 48484, ], 'iconic_taxon_name': 'Insecta', 'preferred_common_name': 'Asian Lady Beetle', }, }, { 'count': 19, 'taxon': { 'observations_count': 43187, 'taxon_schemes_count': 3, 'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/471714/48486/333790/333796/51703', 'is_active': True, 'flag_counts': {'unresolved': 0, 'resolved': 1}, 'wikipedia_url': 'http://en.wikipedia.org/wiki/Coccinella_septempunctata', 'current_synonymous_taxon_ids': None, 'iconic_taxon_id': 47158, 'rank_level': 10, 'taxon_changes_count': 1, 'atlas_id': None, 'complete_species_count': None, 'parent_id': 51703, 'name': 'Coccinella septempunctata', 'rank': 'species', 'extinct': False, 'id': 51702, 'default_photo': { 'square_url': 'https://static.inaturalist.org/photos/5669923/square.jpg?1480658715', 'attribution': '(c) Katja Schulz, some rights reserved (CC BY)', 'flags': [], 'medium_url': 'https://static.inaturalist.org/photos/5669923/medium.jpg?1480658715', 'id': 5669923, 'license_code': 'cc-by', 'original_dimensions': {'width': 2048, 'height': 1536}, 'url': 'https://static.inaturalist.org/photos/5669923/square.jpg?1480658715', }, 'ancestor_ids': [ 48460, 1, 47120, 372739, 47158, 184884, 47208, 71130, 372852, 471714, 48486, 333790, 333796, 51703, 51702, ], 'iconic_taxon_name': 'Insecta', 'preferred_common_name': 'Seven-spotted Lady Beetle', }, }, ], }
- pyinaturalist.v1.observations.get_observation_taxon_summary(observation_id, **params)#
Get information about an observation’s taxon, within the context of the observation’s location
Notes
API reference: GET /observations/{id}/taxon_summary
- Parameters:
observation_id (
int
) – Observation ID to get taxon summary fordry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> response = get_observation_taxon_summary(7849808)
Example Response
from datetime import datetime from dateutil.tz import tzutc { 'conservation_status': None, 'listed_taxon': { 'id': 46798449, 'taxon_id': 47219, 'list_id': 2684267, 'last_observation_id': 89579306, 'created_at': datetime(2019, 11, 20, 16, 26, 47, 604000, tzinfo=tzutc()), 'updated_at': datetime(2021, 8, 2, 3, 6, 51, 275000, tzinfo=tzutc()), 'place_id': 144952, 'description': None, 'comments_count': 0, 'user_id': None, 'updater_id': None, 'occurrence_status_level': None, 'establishment_means': 'introduced', 'first_observation_id': 7849808, 'observations_count': 20, 'taxon_range_id': None, 'source_id': None, 'manually_added': False, 'primary_listing': True, 'establishment_means_label': 'Introduced', 'establishment_means_description': 'arrived in the region via anthropogenic means', 'place': { 'id': 144952, 'display_name': 'HRM District 13 Hammonds Plains-St Margarets, NS, CA', 'place_type_name': 'Constituency', }, }, 'wikipedia_summary': 'The <b>western honey bee</b> or <b>European honey bee</b> (<i>Apis mellifera</i>) is the most common of the 7–12 species of honey bee worldwide. The genus name <i>Apis</i> is Latin for "bee", and <i>mellifera</i> is the Latin for "honey-bearing", referring to the species\' production of honey for the winter.', }
- pyinaturalist.v1.observations.get_observation_taxonomy(user_id=None, **params)#
Get observation counts for all taxa in a full taxonomic tree. In the web UI, these are used for life lists.
Example
>>> response = get_observation_taxonomy(user_id='my_username')
Example Response
{ "count_without_taxon": 4, "size": 9, "results": [ { "id": 1, "count": 1, "name": "Animalia", "rank": "kingdom", "rank_level": 70, "is_active": true, "parent_id": 48460, "descendant_obs_count": 3023, "direct_obs_count": 1 }, { "id": 2, "name": "Chordata", "rank": "phylum", "rank_level": 60, "is_active": true, "parent_id": 1, "descendant_obs_count": 447, "direct_obs_count": 0 }, { "id": 3, "count": 4, "name": "Aves", "rank": "class", "rank_level": 50, "is_active": true, "parent_id": 355675, "descendant_obs_count": 340, "direct_obs_count": 4 }, { "id": 573, "name": "Galliformes", "rank": "order", "rank_level": 40, "is_active": true, "parent_id": 3, "descendant_obs_count": 4, "direct_obs_count": 0 }, { "id": 574, "name": "Phasianidae", "rank": "family", "rank_level": 30, "is_active": true, "parent_id": 573, "descendant_obs_count": 4, "direct_obs_count": 0 }, { "id": 889, "name": "Bonasa", "rank": "genus", "rank_level": 20, "is_active": true, "parent_id": 574, "descendant_obs_count": 2, "direct_obs_count": 0 }, { "id": 890, "count": 2, "name": "Bonasa umbellus", "rank": "species", "rank_level": 10, "is_active": true, "parent_id": 889, "descendant_obs_count": 2, "direct_obs_count": 2 }, { "id": 980, "name": "Phasianus", "rank": "genus", "rank_level": 20, "is_active": true, "parent_id": 574, "descendant_obs_count": 2, "direct_obs_count": 0 }, { "id": 981, "count": 2, "name": "Phasianus colchicus", "rank": "species", "rank_level": 10, "is_active": true, "parent_id": 980, "descendant_obs_count": 2, "direct_obs_count": 2 } ] }
- pyinaturalist.v1.observations.get_observations(**params)#
Search observations
Notes
Optional authentication (For private/obscured coordinates)
API reference: GET /observations
- Parameters:
q – Search observation properties
d1 – Must be observed on or after this date
d2 – Must be observed on or before this date
day – Must be observed within this day of the month
month – Must be observed within this month
year – Must be observed within this year
license – Observation must have this license
photo_license – Must have at least one photo with this license
out_of_range – Observations whose taxa are outside their known ranges
list_id – Taxon must be in the list with this ID
quality_grade – Must have this quality grade
id – Must have this observation ID
taxon_id – Only show observations of these taxa and their descendants
taxon_name – Taxon must have a scientific or common name matching this string
iconic_taxa – Taxon must by within this iconic taxon
updated_since – Must be updated since this time
acc – Whether or not positional accuracy / coordinate uncertainty has been specified
captive – Captive or cultivated observations
endemic – Observations whose taxa are endemic to their location
geo – Observations that are georeferenced
id_please – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified – Observations that have community identifications
introduced – Observations whose taxa are introduced in their location
mappable – Observations that show on map tiles
native – Observations whose taxa are native to their location
pcid – 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 – Observations with photos
popular – Observations that have been favorited by at least one user
sounds – Observations with sounds
taxon_is_active – Observations of active taxon concepts
threatened – Observations whose taxa are threatened in their location
verifiable – Observations with a
quality_grade
of eitherneeds_id
orresearch
. Equivalent toquality_grade=needs_id,research
not_id – Must not have this ID
place_id – Must be observed within the place with this ID
project_id – Must be added to the project this ID or slug
rank – Taxon must have this rank
site_id – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype – Must have an observation field value with this datatype
sound_license – Must have at least one sound with this license
without_taxon_id – Exclude observations of these taxa and their descendants
user_id – Observer must have this user ID or login
user_login – Observer must have this user login
ident_user_id – Identifier must have this user ID or login
term_id – Must have an annotation using this controlled term ID
term_value_id – Must have an annotation using this controlled value ID. Must be combined with the
term_id
parameterwithout_term_value_id – Exclude observations with annotations using this controlled value ID. Must be combined with the
term_id
parameteracc_above – Must have an positional accuracy above this value (meters)
acc_below – Must have an positional accuracy below this value (meters)
acc_below_or_unknown – Must have an positional accuracy below this value (meters) or unknown
created_d1 – Must be created at or after this time
created_d2 – Must be created at or before this time
created_on – Must be created on this date
observed_on – Must be observed on this date
unobserved_by_user_id – Must not be of a taxon previously observed by this user
apply_project_rules_for – Must match the rules of the project with this ID or slug
cs – Taxon must have this conservation status code. If the
place_id
parameter is also specified, this will only consider statuses specific to that placecsa – 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 placecsi – Taxon must have this IUCN conservation status. If the
place_id
parameter is also specified, this will only consider statuses specific to that placegeoprivacy – Must have this geoprivacy setting
taxon_geoprivacy – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank – Taxon must have this rank or lower
lrank – Taxon must have this rank or higher
id_above – Must have an ID above this value
id_below – Must have an ID below this value
identifications – Identifications must meet these criteria
lat – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)lng – Must be within a
radius
kilometer circle around this lat/lng (lat, lng, radius)radius – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project – Must not be in the project with this ID or slug
not_matching_project_rules_for – Must not match the rules of the project with this ID or slug
search_on – Properties to search on, when combined with q. Searches across all properties by default
viewer_id – See reviewed
reviewed – Observations have been reviewed by the user with ID equal to the value of the
viewer_id
parameterlocale – Locale preference for taxon common names
preferred_place_id – Place preference for regional taxon common names
ttl – Set the
Cache-Control
HTTP header with this value asmax-age
, in secondsnelat – NE latitude of bounding box
nelng – NE longitude of bounding box
swlat – SW latitude of bounding box
swlng – SW longitude of bounding box
page – Page number of results to return
per_page – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order – Sort order
order_by – Field to sort on
count_only – Only return a count of results; alias for
per_page=0
reverse – Reverse the order of results; alias for
order='descending'
only_id – Return only the record IDs
access_token – An access token for user authentication, as returned by
get_access_token()
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
- Return type:
- Returns:
Response dict containing observation records
Examples
Get observations of Monarch butterflies with photos + public location info, on a specific date in the provice of Saskatchewan, CA (place ID 7953):
>>> response = get_observations( >>> taxon_name='Danaus plexippus', >>> created_on='2020-08-27', >>> photos=True, >>> geo=True, >>> geoprivacy='open', >>> place_id=7953, >>> )
Get basic info for observations in response:
>>> pprint(response) '[57754375] Species: Danaus plexippus (Monarch) observed by samroom on 2020-08-27 at Railway Ave, Wilcox, SK' '[57707611] Species: Danaus plexippus (Monarch) observed by ingridt3 on 2020-08-26 at Michener Dr, Regina, SK'
Example Response
from datetime import datetime from dateutil.tz import tzoffset, tzutc { 'total_results': 2, 'page': 1, 'per_page': 30, 'results': [ { 'quality_grade': 'research', 'time_observed_at': '2020-08-27T08:57:22+00:00', 'taxon_geoprivacy': 'open', 'annotations': [], 'uuid': 'c44b91f3-534d-48c4-933d-a8b4e1d8f87b', 'id': 57754375, 'cached_votes_total': 0, 'identifications_most_agree': True, 'species_guess': 'Monarch', 'identifications_most_disagree': False, 'tags': [], 'positional_accuracy': None, 'comments_count': 2, 'site_id': 5, 'license_code': 'cc-by-nc', 'quality_metrics': [], 'public_positional_accuracy': None, 'reviewed_by': [115129, 2852555], 'oauth_application_id': 3, 'flags': [], 'created_at': datetime(2020, 8, 27, 18, 0, 51, tzinfo=tzutc()), 'description': None, 'project_ids_with_curator_id': [], 'updated_at': datetime(2020, 8, 28, 12, 4, 18, tzinfo=tzutc()), 'sounds': [], 'place_ids': [ 6712, 7953, 9853, 49224, 59613, 64422, 64423, 66741, 78395, 82256, 97394, 145030, 155145, 164401, ], 'captive': False, 'taxon': { 'is_active': True, 'ancestry': '48460/1/47120/372739/47158/184884/47157/47224/47922/61244/134169/522900/48663', 'min_species_ancestry': '48460,1,47120,372739,47158,184884,47157,47224,47922,61244,134169,522900,48663,48662', 'endemic': False, 'iconic_taxon_id': 47158, 'min_species_taxon_id': 48662, 'threatened': True, 'rank_level': 10, 'introduced': False, 'native': True, 'parent_id': 48663, 'name': 'Danaus plexippus', 'rank': 'species', 'extinct': False, 'id': 48662, 'ancestor_ids': [ 48460, 1, 47120, 372739, 47158, 184884, 47157, 47224, 47922, 61244, 134169, 522900, 48663, 48662, ], 'photos_locked': False, 'taxon_schemes_count': 6, 'wikipedia_url': 'http://en.wikipedia.org/wiki/Monarch_butterfly', 'current_synonymous_taxon_ids': None, 'created_at': '2008-10-26T20:24:33+00:00', 'taxon_changes_count': 1, 'complete_species_count': None, 'universal_search_rank': 131627, 'observations_count': 131627, 'flag_counts': {'unresolved': 1, 'resolved': 7}, 'atlas_id': 1231, 'default_photo': { 'square_url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684', 'attribution': '(c) fam-esquivel, some rights reserved (CC BY-NC)', 'flags': [], 'medium_url': 'https://static.inaturalist.org/photos/13824507/medium.jpg?1545715684', 'id': 13824507, 'license_code': 'cc-by-nc', 'original_dimensions': {'width': 2048, 'height': 1361}, 'url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684', }, 'iconic_taxon_name': 'Insecta', 'preferred_common_name': 'Monarch', 'conservation_status': { 'user_id': None, 'status_name': 'imperiled', 'iucn': 40, 'authority': 'NatureServe', 'geoprivacy': None, 'source_id': 8, 'place_id': 7953, 'status': 's2b', }, }, 'ident_taxon_ids': [ 48460, 1, 47120, 372739, 47158, 184884, 47157, 47224, 47922, 61244, 134169, 522900, 48663, 48662, ], 'outlinks': [{'source': 'GBIF', 'url': 'http://www.gbif.org/occurrence/2856816457'}], 'faves_count': 0, 'ofvs': [], 'num_identification_agreements': 1, 'preferences': {'prefers_community_taxon': None}, 'comments': [ { 'moderator_actions': [], 'hidden': False, 'flags': [], 'created_at': '2020-08-28T12:04:18.407Z', 'id': 5326888, 'created_at_details': { 'date': '2020-08-28', 'week': 35, 'month': 8, 'hour': 12, 'year': 2020, 'day': 28, }, 'body': 'Thankyou ', 'uuid': 'b4d00be4-132d-4e51-bfdd-8515a00f161c', 'user': { 'created_at': '2020-04-26T15:26:56+00:00', 'id': 2852555, 'login': 'samroom', 'spam': False, 'suspended': False, 'login_autocomplete': 'samroom', 'login_exact': 'samroom', 'name': None, 'name_autocomplete': None, 'orcid': None, 'icon': None, 'observations_count': 59, 'identifications_count': 0, 'journal_posts_count': 0, 'activity_count': 59, 'species_count': 52, 'universal_search_rank': 59, 'roles': [], 'site_id': 5, 'icon_url': None, }, }, { 'moderator_actions': [], 'hidden': False, 'flags': [], 'created_at': '2020-08-28T04:54:19.020Z', 'id': 5325706, 'created_at_details': { 'date': '2020-08-28', 'week': 35, 'month': 8, 'hour': 4, 'year': 2020, 'day': 28, }, 'body': 'Neat photo! ', 'uuid': '25ac67d5-ba09-47a8-91e3-b6e3590a0b72', 'user': { 'created_at': '2018-03-18T01:34:25+00:00', 'id': 792847, 'login': 'ingridt3', 'spam': False, 'suspended': False, 'login_autocomplete': 'ingridt3', 'login_exact': 'ingridt3', 'name': None, 'name_autocomplete': None, 'orcid': None, 'icon': None, 'observations_count': 51, 'identifications_count': 29, 'journal_posts_count': 0, 'activity_count': 80, 'species_count': 30, 'universal_search_rank': 51, 'roles': [], 'site_id': 5, 'icon_url': None, }, }, ], 'map_scale': None, 'uri': 'https://www.inaturalist.org/observations/57754375', 'project_ids': [], 'community_taxon_id': 48662, 'geojson': {'coordinates': [-104.71929167, 50.0949055], 'type': 'Point'}, 'owners_identification_from_vision': True, 'identifications_count': 1, 'obscured': False, 'num_identification_disagreements': 0, 'geoprivacy': None, 'location': [50.0949055, -104.71929167], 'votes': [], 'spam': False, 'user': { 'site_id': 5, 'created_at': '2020-04-26T15:26:56+00:00', 'id': 2852555, 'login': 'samroom', 'spam': False, 'suspended': False, 'preferences': {}, 'login_autocomplete': 'samroom', 'login_exact': 'samroom', 'name': None, 'name_autocomplete': None, 'orcid': None, 'icon': None, 'observations_count': 59, 'identifications_count': 0, 'journal_posts_count': 0, 'activity_count': 59, 'species_count': 52, 'universal_search_rank': 59, 'roles': [], 'icon_url': None, }, 'mappable': True, 'identifications_some_agree': True, 'project_ids_without_curator_id': [], 'place_guess': 'Railway Ave, Wilcox, SK, CA', 'identifications': 'TRUNCATED', 'project_observations': [], 'photos': [ { 'id': 92152429, 'license_code': 'cc-by-nc', 'url': 'https://static.inaturalist.org/photos/92152429/square.jpg?1598551272', 'attribution': '(c) samroom, some rights reserved (CC BY-NC)', 'original_dimensions': {'width': 1188, 'height': 1188}, 'flags': [], } ], 'observation_photos': [ { 'id': 85887066, 'position': 0, 'uuid': '6f73a9f2-019f-4566-a393-2c2242a3198d', 'photo': { 'id': 92152429, 'license_code': 'cc-by-nc', 'url': 'https://static.inaturalist.org/photos/92152429/square.jpg?1598551272', 'attribution': '(c) samroom, some rights reserved (CC BY-NC)', 'original_dimensions': {'width': 1188, 'height': 1188}, 'flags': [], }, } ], 'faves': [], 'non_owner_ids': 'TRUNCATED', 'observed_on': datetime(2020, 8, 27, 8, 57, 22, tzinfo=tzoffset('Etc/UTC', 0)), }, { 'quality_grade': 'research', 'time_observed_at': '2020-08-26T22:46:10+00:00', 'taxon_geoprivacy': 'open', 'annotations': [], 'uuid': '588c9ad4-c747-497c-a52f-bf856c30d2ff', 'id': 57707611, 'cached_votes_total': 0, 'identifications_most_agree': True, 'species_guess': 'Monarch', 'identifications_most_disagree': False, 'tags': [], 'positional_accuracy': 374, 'comments_count': 0, 'site_id': 5, 'license_code': None, 'quality_metrics': [], 'public_positional_accuracy': 374, 'reviewed_by': [35013, 115129, 217571, 412189, 792847, 2173064], 'oauth_application_id': 3, 'flags': [], 'created_at': datetime(2020, 8, 27, 4, 50, 17, tzinfo=tzutc()), 'description': 'Only one today and likely the last one to eclose from the batch of caterpillars from 10-14 days ago. ', 'project_ids_with_curator_id': [6905], 'updated_at': datetime(2020, 11, 2, 19, 26, 40, tzinfo=tzutc()), 'sounds': [], 'place_ids': [ 6712, 7953, 9853, 49224, 59613, 64422, 64423, 66741, 78395, 82256, 97394, 113642, 120614, 120671, 145030, 155145, 164401, ], 'captive': False, 'taxon': { 'is_active': True, 'ancestry': '48460/1/47120/372739/47158/184884/47157/47224/47922/61244/134169/522900/48663', 'min_species_ancestry': '48460,1,47120,372739,47158,184884,47157,47224,47922,61244,134169,522900,48663,48662', 'endemic': False, 'iconic_taxon_id': 47158, 'min_species_taxon_id': 48662, 'threatened': True, 'rank_level': 10, 'introduced': False, 'native': True, 'parent_id': 48663, 'name': 'Danaus plexippus', 'rank': 'species', 'extinct': False, 'id': 48662, 'ancestor_ids': [ 48460, 1, 47120, 372739, 47158, 184884, 47157, 47224, 47922, 61244, 134169, 522900, 48663, 48662, ], 'photos_locked': False, 'taxon_schemes_count': 6, 'wikipedia_url': 'http://en.wikipedia.org/wiki/Monarch_butterfly', 'current_synonymous_taxon_ids': None, 'created_at': '2008-10-26T20:24:33+00:00', 'taxon_changes_count': 1, 'complete_species_count': None, 'universal_search_rank': 131627, 'observations_count': 131627, 'flag_counts': {'unresolved': 1, 'resolved': 7}, 'atlas_id': 1231, 'default_photo': { 'square_url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684', 'attribution': '(c) fam-esquivel, some rights reserved (CC BY-NC)', 'flags': [], 'medium_url': 'https://static.inaturalist.org/photos/13824507/medium.jpg?1545715684', 'id': 13824507, 'license_code': 'cc-by-nc', 'original_dimensions': {'width': 2048, 'height': 1361}, 'url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684', }, 'iconic_taxon_name': 'Insecta', 'preferred_common_name': 'Monarch', 'conservation_status': { 'user_id': None, 'status_name': 'imperiled', 'iucn': 40, 'authority': 'NatureServe', 'geoprivacy': None, 'source_id': 8, 'place_id': 7953, 'status': 's2b', }, }, 'ident_taxon_ids': [ 48460, 1, 47120, 372739, 47158, 184884, 47157, 47224, 47922, 61244, 134169, 522900, 48663, 48662, ], 'outlinks': [], 'faves_count': 0, 'ofvs': [], 'num_identification_agreements': 5, 'preferences': {'prefers_community_taxon': None}, 'comments': [], 'map_scale': None, 'uri': 'https://www.inaturalist.org/observations/57707611', 'project_ids': [6905], 'community_taxon_id': 48662, 'geojson': {'coordinates': [-104.5628221383, 50.433418274], 'type': 'Point'}, 'owners_identification_from_vision': True, 'identifications_count': 5, 'obscured': False, 'num_identification_disagreements': 0, 'geoprivacy': None, 'location': [50.433418274, -104.5628221383], 'votes': [], 'spam': False, 'user': { 'site_id': 5, 'created_at': '2018-03-18T01:34:25+00:00', 'id': 792847, 'login': 'ingridt3', 'spam': False, 'suspended': False, 'preferences': {}, 'login_autocomplete': 'ingridt3', 'login_exact': 'ingridt3', 'name': None, 'name_autocomplete': None, 'orcid': None, 'icon': None, 'observations_count': 51, 'identifications_count': 29, 'journal_posts_count': 0, 'activity_count': 80, 'species_count': 30, 'universal_search_rank': 51, 'roles': [], 'icon_url': None, }, 'mappable': True, 'identifications_some_agree': True, 'project_ids_without_curator_id': [], 'place_guess': 'Michener Dr, Regina, SK, CA', 'identifications': 'TRUNCATED', 'project_observations': [ { 'id': 45561247, 'uuid': '912138ca-651d-4d5f-99c1-d89e9c023bb5', 'project': {'id': 6905}, 'user_id': 35013, 'preferences': {'allows_curator_coordinate_access': True}, 'user': { 'id': 35013, 'login': 'a_b', 'spam': False, 'suspended': False, 'created_at': '2014-04-09T03:27:04+00:00', 'login_autocomplete': 'a_b', 'login_exact': 'a_b', 'name': 'Andrea Benville', 'name_autocomplete': 'Andrea Benville', 'orcid': None, 'icon': 'https://static.inaturalist.org/attachments/users/icons/35013/thumb.jpg?1505750038', 'observations_count': 787, 'identifications_count': 533, 'journal_posts_count': 0, 'activity_count': 1320, 'species_count': 432, 'universal_search_rank': 787, 'roles': [], 'site_id': 5, 'icon_url': 'https://static.inaturalist.org/attachments/users/icons/35013/medium.jpg?1505750038', }, } ], 'photos': [ { 'id': 92075215, 'license_code': None, 'url': 'https://static.inaturalist.org/photos/92075215/square.jpg?1598503820', 'attribution': '(c) ingridt3, all rights reserved', 'original_dimensions': {'width': 1183, 'height': 842}, 'flags': [], } ], 'observation_photos': [ { 'id': 85814399, 'position': 0, 'uuid': '98dd67ae-79b4-49c6-934b-6a814ea6d6ab', 'photo': { 'id': 92075215, 'license_code': None, 'url': 'https://static.inaturalist.org/photos/92075215/square.jpg?1598503820', 'attribution': '(c) ingridt3, all rights reserved', 'original_dimensions': {'width': 1183, 'height': 842}, 'flags': [], }, } ], 'faves': [], 'non_owner_ids': 'TRUNCATED', 'observed_on': datetime(2020, 8, 26, 22, 46, 10, tzinfo=tzoffset('Etc/UTC', 0)), }, ], }
- pyinaturalist.v1.observations.get_observations_by_id(observation_id, access_token=None, **params)#
Get one or more observations by ID
Notes
Optional authentication (For private/obscured coordinates)
API reference: GET /observations/{id}
This endpoint returns more complete annotation details compared to
get_observations()
. SeeAnnotation
for details.
- Parameters:
observation_id (
Union
[int
,Iterable
[int
]]) – Get an observation with this ID. Multiple IDs are allowed.access_token (
Optional
[str
]) – An access token, as returned byget_access_token()
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> response = get_observations_by_id(16227955) >>> response = get_observations_by_id([16227955, 16227956])
Example Response
from datetime import datetime from dateutil.tz import tzoffset { "total_results": 1, "page": 1, "per_page": 1, "results": [ { 'id': 16227955, 'annotations': [ { 'concatenated_attr_val': '1|2', 'controlled_attribute_id': 1, 'controlled_value_id': 2, 'user': { 'activity_count': 1184, 'created_at': '2018-04-23T17:11:14+00:00', 'icon': 'https://static.inaturalist.org/attachments/users/icons/886482/thumb.jpg?1529671435', 'icon_url': 'https://static.inaturalist.org/attachments/users/icons/886482/medium.jpg?1529671435', 'id': 886482, 'identifications_count': 120, 'journal_posts_count': 0, 'login': 'niconoe', 'login_autocomplete': 'niconoe', 'login_exact': 'niconoe', 'name': 'Nicolas Noé', 'name_autocomplete': 'Nicolas Noé', 'observations_count': 1064, 'orcid': 'https://orcid.org/0000-0002-9503-4750', 'roles': [], 'site_id': 1, 'spam': False, 'species_count': 471, 'suspended': False, 'universal_search_rank': 1064, }, 'user_id': 886482, 'uuid': '14bbd34f-73f8-4b99-b591-8517913788a1', 'vote_score': 0, 'votes': [], } ], 'cached_votes_total': 0, 'captive': False, 'comments': [ { 'body': 'suspect L. bardanae - but sits on Solanum (non-host)', 'created_at': '2018-09-05T14:08:09+00:00', 'created_at_details': { 'date': '2018-09-05', 'day': 5, 'hour': 14, 'month': 9, 'week': 36, 'year': 2018, }, 'flags': [], 'hidden': False, 'id': 2071611, 'moderator_actions': [], 'user': { 'activity_count': 503804, 'created_at': '2016-02-18T10:19:19+00:00', 'icon': None, 'icon_url': None, 'id': 180811, 'identifications_count': 503804, 'journal_posts_count': 0, 'login': 'borisb', 'login_autocomplete': 'borisb', 'login_exact': 'borisb', 'name': '', 'name_autocomplete': '', 'observations_count': 0, 'orcid': None, 'roles': ['curator'], 'site_id': 1, 'spam': False, 'species_count': 0, 'suspended': False, 'universal_search_rank': 0, }, 'uuid': 'e6fc62ea-e22b-4427-bb65-1ba3bc591c77', }, { 'body': 'I now see: Bonus species on observation! You may make ' 'a duplicate . . . \n' '(Flea beetle Epitrix pubescens on Solanum bud) \n', 'created_at': '2018-09-05T16:03:40+00:00', 'created_at_details': { 'date': '2018-09-05', 'day': 5, 'hour': 16, 'month': 9, 'week': 36, 'year': 2018, }, 'flags': [], 'hidden': False, 'id': 2071896, 'moderator_actions': [], 'user': { 'activity_count': 503804, 'created_at': '2016-02-18T10:19:19+00:00', 'icon': None, 'icon_url': None, 'id': 180811, 'identifications_count': 503804, 'journal_posts_count': 0, 'login': 'borisb', 'login_autocomplete': 'borisb', 'login_exact': 'borisb', 'name': '', 'name_autocomplete': '', 'observations_count': 0, 'orcid': None, 'roles': ['curator'], 'site_id': 1, 'spam': False, 'species_count': 0, 'suspended': False, 'universal_search_rank': 0, }, 'uuid': '4d401d20-1b08-464a-8287-351f5b57443e', }, ], 'comments_count': 2, 'community_taxon_id': 493595, 'created_at': datetime(2018, 9, 5, 14, 31, 8, tzinfo=tzoffset(None, 7200)), 'created_at_details': { 'date': '2018-09-05', 'day': 5, 'hour': 14, 'month': 9, 'week': 36, 'year': 2018, }, 'created_time_zone': 'Europe/Paris', 'description': '', 'faves': [], 'faves_count': 0, 'flags': [], 'geojson': {'coordinates': [4.360086, 50.646894], 'type': 'Point'}, 'geoprivacy': None, 'ident_taxon_ids': [ 48460, 1, 47120, 372739, 47158, 184884, 47208, 71130, 372852, 60473, 48736, 272543, 507383, 71157, 1101667, 493595, ], 'identifications': 'TRUNCATED', 'identifications_count': 2, 'identifications_most_agree': True, 'identifications_most_disagree': False, 'identifications_some_agree': True, 'license_code': 'cc0', 'location': [50.646894, 4.360086], 'map_scale': 17, 'mappable': True, 'non_owner_ids': 'TRUNCATED', 'num_identification_agreements': 2, 'num_identification_disagreements': 0, 'oauth_application_id': None, 'obscured': False, 'observation_photos': [ { 'id': 22080796, 'photo': { 'attribution': '(c) Nicolas Noé, some ' 'rights reserved (CC BY)', 'flags': [], 'id': 24355315, 'license_code': 'cc-by', 'original_dimensions': {'height': 1057, 'width': 1445}, 'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/24355315/square.jpeg', }, 'position': 0, 'uuid': '76b54495-3497-4e96-b07c-7ad346939a02', }, { 'id': 22080797, 'photo': { 'attribution': '(c) Nicolas Noé, some ' 'rights reserved (CC BY)', 'flags': [], 'id': 24355313, 'license_code': 'cc-by', 'original_dimensions': {'height': 1364, 'width': 2048}, 'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/24355313/square.jpeg', }, 'position': 1, 'uuid': '06b90a88-d98d-4447-b14c-5d354d2d68d1', }, ], 'observed_on': datetime(2018, 9, 5, 14, 6, tzinfo=tzoffset(None, 7200)), 'observed_on_details': { 'date': '2018-09-05', 'day': 5, 'hour': 14, 'month': 9, 'week': 36, 'year': 2018, }, 'observed_on_string': '2018/09/05 2:06 PM CEST', 'observed_time_zone': 'Europe/Paris', 'ofvs': [], 'outlinks': [{'source': 'GBIF', 'url': 'http://www.gbif.org/occurrence/1914197587'}], 'owners_identification_from_vision': True, 'photos': [ { 'attribution': '(c) Nicolas Noé, some rights reserved (CC BY)', 'flags': [], 'id': 24355315, 'license_code': 'cc-by', 'original_dimensions': {'height': 1057, 'width': 1445}, 'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/24355315/square.jpeg', }, { 'attribution': '(c) Nicolas Noé, some rights reserved (CC BY)', 'flags': [], 'id': 24355313, 'license_code': 'cc-by', 'original_dimensions': {'height': 1364, 'width': 2048}, 'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/24355313/square.jpeg', }, ], 'place_guess': '54 rue des Badauds', 'place_ids': [ 7008, 8657, 14999, 59614, 67952, 80627, 81490, 96372, 96794, 97391, 97582, 108692, ], 'positional_accuracy': 23, 'preferences': {'prefers_community_taxon': None}, 'project_ids': [], 'project_ids_with_curator_id': [], 'project_ids_without_curator_id': [], 'project_observations': [], 'public_positional_accuracy': 23, 'quality_grade': 'research', 'quality_metrics': [], 'reviewed_by': [180811, 886482, 1226913], 'site_id': 1, 'sounds': [], 'spam': False, 'species_guess': 'Lixus bardanae', 'tags': [], 'taxon': { 'ancestor_ids': [ 48460, 1, 47120, 372739, 47158, 184884, 47208, 71130, 372852, 60473, 48736, 272543, 507383, 71157, 1101667, 493595, ], 'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/60473/48736/272543/507383/71157/1101667', 'atlas_id': None, 'complete_species_count': None, 'created_at': '2016-04-25T22:35:20+00:00', 'current_synonymous_taxon_ids': None, 'default_photo': { 'attribution': '(c) Andy Van de Velde, all rights ' 'reserved, uploaded by Andy Van de ' 'Velde', 'flags': [], 'id': 69087254, 'license_code': None, 'medium_url': 'https://static.inaturalist.org/photos/69087254/medium.jpg', 'original_dimensions': {'height': 1638, 'width': 2048}, 'square_url': 'https://static.inaturalist.org/photos/69087254/square.jpg', 'url': 'https://static.inaturalist.org/photos/69087254/square.jpg', }, 'endemic': False, 'extinct': False, 'flag_counts': {'resolved': 0, 'unresolved': 0}, 'iconic_taxon_id': 47158, 'iconic_taxon_name': 'Insecta', 'id': 493595, 'introduced': False, 'is_active': True, 'min_species_ancestry': '48460,1,47120,372739,47158,184884,47208,71130,372852,60473,48736,272543,507383,71157,1101667,493595', 'min_species_taxon_id': 493595, 'name': 'Lixus bardanae', 'native': False, 'observations_count': 86, 'parent_id': 1101667, 'photos_locked': False, 'rank': 'species', 'rank_level': 10, 'taxon_changes_count': 0, 'taxon_schemes_count': 1, 'threatened': False, 'universal_search_rank': 86, 'wikipedia_url': None, }, 'taxon_geoprivacy': None, 'time_zone_offset': '+01:00', 'updated_at': datetime(2018, 9, 22, 19, 19, 27, tzinfo=tzoffset(None, 7200)), 'uri': 'https://www.inaturalist.org/observations/16227955', 'user': { 'activity_count': 1184, 'created_at': '2018-04-23T17:11:14+00:00', 'icon': 'https://static.inaturalist.org/attachments/users/icons/886482/thumb.jpg?1529671435', 'icon_url': 'https://static.inaturalist.org/attachments/users/icons/886482/medium.jpg?1529671435', 'id': 886482, 'identifications_count': 120, 'journal_posts_count': 0, 'login': 'niconoe', 'login_autocomplete': 'niconoe', 'login_exact': 'niconoe', 'name': 'Nicolas Noé', 'name_autocomplete': 'Nicolas Noé', 'observations_count': 1064, 'orcid': 'https://orcid.org/0000-0002-9503-4750', 'preferences': {}, 'roles': [], 'site_id': 1, 'spam': False, 'species_count': 471, 'suspended': False, 'universal_search_rank': 1064, }, 'uuid': '6448d03a-7f9a-4099-86aa-ca09a7740b00', 'votes': [], }, ], }
- pyinaturalist.v1.observations.update_observation(observation_id, **params)#
Update a single observation
Notes
API reference: PUT /observations
- Parameters:
observation_id (
int
) – iNaturalist observation IDaccess_token – An access token for user authentication, as returned by
get_access_token()
species_guess – Equivalent to the ‘What did you see?’ field on the observation form. iNat will try to choose a single taxon based on this, but it may fail if it’s ambuguous
taxon_id – ID of the taxon to associate with this observation
observed_on – Alias for
observed_on_string
; acceptsdatetime
objects.observed_on_string – Date/time of the observation. Time zone will default to the user’s time zone if not specified.
time_zone – Time zone the observation was made in
description – Observation description
tag_list – Comma-separated list of tags
place_guess – Name of the place where the observation was recorded. Note: iNat will not try to automatically look up coordinates based on this string
latitude – Latitude of the observation; presumed datum is WGS84
longitude – Longitude of the observation; presumed datum is WGS84
map_scale – Google Maps zoom level (from 0 to 19) at which to show this observation’s map marker.
positional_accuracy – Positional accuracy of the observation coordinates, in meters
geoprivacy – Geoprivacy for the observation
observation_fields – Dict of observation fields in the format
{id: value}
. Alias forobservation_field_values_attributes
.flickr_photos – 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 – 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 – 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 – One or more image files, file-like objects, file paths, or URLs
sounds – One or more sound files, file-like objects, file paths, or URLs
photo_ids – One or more IDs of previously uploaded photos to attach to the observation
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> token = get_access_token() >>> update_observation( >>> 17932425, >>> access_token=token, >>> description='updated description!', >>> )
Example Response
[ { "id": 17932425, "observed_on": "2018-10-29", "description": "updated description v2 !", "latitude": "50.4898053873", "longitude": "5.1035889611", "map_scale": null, "timeframe": null, "species_guess": null, "user_id": 1263313, "taxon_id": 54327, "created_at": "2018-10-29T14:37:32.176+01:00", "updated_at": "2018-10-30T14:30:11.667+01:00", "place_guess": "Namur, Wallonie, BE", "id_please": false, "observed_on_string": "2018-10-28T23:00:00+00:00", "iconic_taxon_id": 47158, "num_identification_agreements": 0, "num_identification_disagreements": 0, "time_observed_at": "2018-10-29T00:00:00.000+01:00", "time_zone": "Brussels", "location_is_exact": false, "delta": false, "positional_accuracy": null, "private_latitude": null, "private_longitude": null, "private_positional_accuracy": null, "geoprivacy": null, "quality_grade": "casual", "positioning_method": null, "positioning_device": null, "out_of_range": null, "license": "CC-BY-NC", "uri": "https://www.inaturalist.org/observations/17932425", "observation_photos_count": 0, "comments_count": 0, "zic_time_zone": "Europe/Brussels", "oauth_application_id": 278, "observation_sounds_count": 0, "identifications_count": 1, "captive": false, "community_taxon_id": null, "site_id": 1, "old_uuid": null, "public_positional_accuracy": null, "mappable": true, "cached_votes_total": 0, "last_indexed_at": "2018-10-30T06:36:06.027-07:00", "private_place_guess": null, "uuid": "03d9e7a4-d96e-4de0-a9ec-d1dacc14be44", "user_login": "vespawatch", "iconic_taxon_name": "Insecta", "created_at_utc": "2018-10-29T13:37:32.176Z", "updated_at_utc": "2018-10-30T13:30:11.667Z", "time_observed_at_utc": "2018-10-28T23:00:00.000Z", "faves_count": 0, "owners_identification_from_vision": false } ]
- pyinaturalist.v1.observations.upload(observation_id, photos=None, sounds=None, photo_ids=None, **params)#
Upload one or more local photo and/or sound files, and add them to an existing observation.
You may also attach a previously uploaded photo by photo ID, e.g. if your photo contains multiple organisms and you want to create a separate observation for each one.
Notes
API reference: POST /observation_photos
- Parameters:
observation_id (
int
) – the ID of the observationphotos (
Union
[BinaryIO
,str
,Iterable
[Union
[BinaryIO
,str
]],None
]) – One or more image files, file-like objects, file paths, or URLssounds (
Union
[BinaryIO
,str
,Iterable
[Union
[BinaryIO
,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()
dry_run – Just log the request instead of sending a real request
session –
An existing Session object to use instead of creating a new one
Example
>>> token = get_access_token() >>> upload( ... 1234, ... photos=['~/observations/2020_09_01_140031.jpg', '~/observations/2020_09_01_140042.jpg'], ... sounds='~/observations/2020_09_01_140031.mp3', ... photo_ids=[1234, 5678], ... access_token=token, ... )
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": [] } } ]