pyinaturalist.rest_api module¶
Code used to access the (read/write, but slow) Rails based API of iNaturalist See: https://www.inaturalist.org/pages/api+reference
- pyinaturalist.rest_api.add_photo_to_observation(observation_id: int, file_object: BinaryIO, access_token: str, user_agent: Optional[str] = None)[source]¶
Upload a picture and assign it to an existing observation.
- Parameters
observation_id – the ID of the observation
file_object – a file-like object for the picture. Example: open(‘/Users/nicolasnoe/vespa.jpg’, ‘rb’)
access_token – the access token, as returned by
get_access_token()
user_agent – a user-agent string that will be passed to iNaturalist.
- pyinaturalist.rest_api.create_observations(params: Dict[str, Dict[str, Any]], access_token: str, user_agent: Optional[str] = None) → List[Dict[str, Any]][source]¶
Create a single or several (if passed an array) observations). For API reference, see: https://www.inaturalist.org/pages/api+reference#post-observations
Example
>>> params = {'observation': {'species_guess': 'Pieris rapae'}} >>> token = get_access_token('...') >>> create_observations(params=params, access_token=token)
- Parameters
params –
access_token – the access token, as returned by
get_access_token()
user_agent – a user-agent string that will be passed to iNaturalist.
- Returns
The newly created observation(s) in JSON format
- Raises
if it rejects the observation data (for example an observation date in the future or a latitude > 90. In –
that case the exception's response attribute give details about the errors. –
TODO investigate: according to the doc, we should be able to pass multiple observations (in an array, and in renaming observation to observations, but as far as I saw they are not created (while a status of 200 is returned)
- pyinaturalist.rest_api.delete_observation(observation_id: int, access_token: str, user_agent: Optional[str] = None) → List[Dict[str, Any]][source]¶
Delete an observation.
- Parameters
observation_id –
access_token –
user_agent – a user-agent string that will be passed to iNaturalist.
- Returns
iNaturalist’s JSON response, as a Python object
- Raises
- pyinaturalist.rest_api.get_access_token(username: str, password: str, app_id: str, app_secret: str, user_agent: Optional[str] = None) → str[source]¶
Get an access token using the user’s iNaturalist username and password. You still need an iNaturalist app to do this.
Example
>>> access_token = get_access_token('...') >>> headers = {"Authorization": f"Bearer {access_token}"}
- Parameters
username – iNaturalist username
password – iNaturalist password
app_id – iNaturalist application ID
app_secret – iNaturalist application secret
user_agent – a user-agent string that will be passed to iNaturalist.
- pyinaturalist.rest_api.get_all_observation_fields(search_query: str = '', user_agent: Optional[str] = None) → List[Dict[str, Any]][source]¶
Like get_observation_fields(), but handles pagination for you.
- Parameters
search_query – a string to search
user_agent – a user-agent string that will be passed to iNaturalist.
- pyinaturalist.rest_api.get_observation_fields(search_query: str = '', page: int = 1, user_agent: Optional[str] = None) → List[Dict[str, Any]][source]¶
Search the (globally available) observation
- Parameters
search_query –
page –
user_agent – a user-agent string that will be passed to iNaturalist.
- Returns
- pyinaturalist.rest_api.get_observations(response_format='json', user_agent: Optional[str] = None, **params) → Union[Dict, str][source]¶
Get observation data, optionally in an alternative format. Return type will be
dict
for thejson
response format, andstr
for all others. Also seeget_geojson_observations()
for GeoJSON format (not included here because it wraps a separate API endpoint).For API parameters, see: https://www.inaturalist.org/pages/api+reference#get-observations
Example:
get_observations(id=45414404, format="dwc")
- pyinaturalist.rest_api.put_observation_field_values(observation_id: int, observation_field_id: int, value: Any, access_token: str, user_agent: Optional[str] = None) → Dict[str, Any][source]¶
Sets an observation field (value) on an observation. Will fail if this observation_field is already set for this observation.
Example
>>> put_observation_field_values( >>> observation_id=7345179, observation_field_id=9613, value=250, access_token=token) {'id': 31, 'observation_id': 18166477, 'observation_field_id': 31, 'value': 'fouraging', 'created_at': '2012-09-29T11:05:44.935+02:00', 'updated_at': '2018-11-13T10:49:47.985+01:00', 'user_id': 1, 'updater_id': 1263313, 'uuid': 'b404b654-1bf0-4299-9288-52eeda7ac0db', 'created_at_utc': '2012-09-29T09:05:44.935Z', 'updated_at_utc': '2018-11-13T09:49:47.985Z'}
- Parameters
observation_id –
observation_field_id –
value –
access_token – access_token: the access token, as returned by
get_access_token()
user_agent – a user-agent string that will be passed to iNaturalist.
- Returns
The nwely updated field value record
- pyinaturalist.rest_api.update_observation(observation_id: int, params: Dict[str, Any], access_token: str, user_agent: Optional[str] = None) → List[Dict[str, Any]][source]¶
Update a single observation. See https://www.inaturalist.org/pages/api+reference#put-observations-id
- Parameters
observation_id – the ID of the observation to update
params – to be passed to iNaturalist API
access_token – the access token, as returned by
get_access_token()
user_agent – a user-agent string that will be passed to iNaturalist.
- Returns
iNaturalist’s JSON response, as a Python object
- Raises
requests.HTTPError – error 410 if the observation doesn’t exists or belongs to another user.