Reference¶

iNaturalist actually provides two APIs:

The original, Rails-based REST API that they also use internally: it is very complete and provides read/write access, but is rather slow and sometimes inconsistent.
The Node-based API allows read-only access to most iNaturalist resources, is faster and provides more consistent behavior than the REST API, but with fewer features.

Pyinaturalist provides functions to use both of those APIs. Main API usage information can be found in node_api and rest_api. Docs for additional supporting modules can also be found below.

Module Documentation

Note

While not mandatory, it is considered good practice in the iNaturalist community to set a custom user-agent header to your API calls. That allows iNaturalist to identify “who’s doing what” with their APIs, and maybe contact you back in case they want to start a discussion about how you use them.

It is recommended to set this user-agent field to either something that identifies the project (MyCoolAndroidApp/2.0) or its contact person (Jane Doe, iNat user XXXXXX, jane@doe.net).

Pyinaturalist therefore provides a couple of features to make that easy:

import pyinaturalist
from pyinaturalist.node_api import get_observation

pyinaturalist.user_agent = "MyCoolAndroidApp/2.0 (using Pyinaturalist)"

# From now on, all API calls will use this user-agent.

t = get_access_token('username', 'password', 'app_id', 'app_secret')
do_something_else()
get_observation(observation_id=1234)
...

In the rare cases where you want to use multiple user agents in your script, you can configure it per call:

get_observation(observation_id=16227955, user_agent='AnotherUserAgent')

(All functions that communicate with the API accept the user_agent optional parameter).

If you don’t configure the user agent, Pyinaturalist/<VERSION> will be used.