pyinaturalist.client

Summary

Module Contents

class pyinaturalist.client.iNatClient(creds=None, default_params=None, dry_run=False, session=None, user_agent='pyinaturalist/0.15.0', **kwargs)

Bases: object

WIP/Experimental

API client class that provides a higher-level interface that is easier to configure, and returns model objects instead of JSON. See Controller classes for request details.

Examples

Basic usage

>>> from pyinaturalist import iNatClient
>>> client = iNatClient()
>>> observations = client.observations.search(taxon_name='Danaus plexippus')

Authentication

Add credentials needed for authenticated requests: Note: Passing credentials via environment variables or keyring is preferred

>>> creds = {
...     'username': 'my_inaturalist_username',
...     'password': 'my_inaturalist_password',
...     'app_id': '33f27dc63bdf27f4ca6cd95dd9dcd5df',
...     'app_secret': 'bbce628be722bfe2abd5fc566ba83de4',
... }
>>> client = iNatClient(creds=creds)

Default request parameters:

Add default locale and preferred_place_id request params to pass to any requests that use them:

>>> default_params={'locale': 'en', 'preferred_place_id': 1}
>>> client = iNatClient(default_params=default_params)

Caching, Rate-limiting, and Retries

See ClientSession and the User Guide for details on these settings. iNatClient will accept any arguments for ClientSession, for example:

>>> client = iNatClient(per_second=50, expire_after=3600, retries=3)

Or you can provide your own custom session object:

>>> session = MyCustomSession(encabulation_factor=47.2)
>>> client = iNatClient(session=session)

Updating settings

All settings can also be modified after creating the client:

>>> client.session = ClientSession()
>>> client.creds['username'] = 'my_inaturalist_username'
>>> client.default_params['locale'] = 'es'
>>> client.dry_run = True
>>> client.user_agent = 'My custom user agent'
Parameters

  • creds (Optional[Dict[str, str]]) – Optional arguments for get_access_token(), used to get and refresh access tokens as needed.

  • default_params (Optional[Dict[str, Any]]) – Default request parameters to pass to any applicable API requests

  • dry_run (bool) – Just log all requests instead of sending real requests

  • session (Optional[Session]) – Session object to use instead of creating a new one

  • user_agent (str) – User-Agent string to pass to API requests

  • kwargs – Keyword arguments for ClientSession

property access_token

Reuse an existing access token, if it’s not expired; otherwise, get a new one

observations

Interface for observation requests

projects

Interface for project requests

request(request_function, *args, auth=False, **params)

Apply any applicable client settings to request parameters before sending a request. Explicit keyword arguments will override any client settings.

Parameters

  • request_function (Callable) – The API request function to call, which should return a JSON response

  • args – Any positional arguments to pass to the request function

  • auth (bool) – Indicates that the request requires authentication

  • params – Original request parameters

Return type

Dict[str, Any]

taxa

Interface for taxon requests