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

  • requests.HTTPError –

  • 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 the json response format, and str for all others. Also see get_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.