Client

Summary

Module Contents

class pyinaturalist.client.iNatClient(creds=None, default_params=None, dry_run=False, session=None, **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
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

  • 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

paginate(request_function, model, auth=False, **kwargs)

Create a paginator for a request, with client settings applied

Parameters

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

  • model (TypeVar(T, bound= BaseModel)) – Model class used for the response

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

  • params – Original request parameters

Return type

Paginator[TypeVar(T, bound= BaseModel)]

projects

Interface for project requests

request(request_function, auth=False, **kwargs)

Send a request, with client settings applied

Parameters

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

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

  • params – Original request parameters

Return type

Dict[str, Any]

taxa

Interface for taxon requests

users

Interface for user requests