Skip to main content

Python client for the iNaturalist APIs

Project description Documentation Status

Python client for the iNaturalist APIs.


Work in progress: features are implemented one by one, as time allows and as the authors needs them.

That being said, many things are already possible (searching observations, creating a new observation, …) and contributions are welcome!

Python 3 only.


Search all observations matching a criteria:

from pyinaturalist.node_api import get_all_observations

obs = get_all_observations(params={'user_id': 'niconoe'})

see available parameters.

For authenticated API calls, you first need to obtain a token for the user:

from pyinaturalist.rest_api import get_access_token

token = get_access_token(username='<your_inaturalist_username>', password='<your_inaturalist_password>',

Note: you’ll need to create an iNaturalist app.

Create a new observation:

from pyinaturalist.rest_api import create_observations

params = {'observation':
            {'taxon_id': 54327,  # Vespa Crabro
             'time_zone': 'Brussels',
             'description': 'This is a free text comment for the observation',
             'tag_list': 'wasp, Belgium',
             'latitude': 50.647143,
             'longitude': 4.360216,
             'positional_accuracy': 50, # meters,

             # sets vespawatch_id (an observation field whose ID is 9613) to the value '100'.
                [{'observation_field_id': 9613,'value': 100}],

r = create_observations(params=params, access_token=token)

new_observation_id = r[0]['id']

Upload a picture for this observation:

from pyinaturalist.rest_api import add_photo_to_observation

r = add_photo_to_observation(observation_id=new_observation_id,
                             file_object=open('/Users/nicolasnoe/vespa.jpg', 'rb'),

Update an existing observation of yours:

from pyinaturalist.rest_api import update_observation

p = {'ignore_photos': 1,  # Otherwise existing pictures will be deleted
     'observation': {'description': 'updated description !'}}
r = update_observation(observation_id=17932425, params=p, access_token=token)

Get a list of all (globally available) observation fields:

from pyinaturalist.rest_api import get_all_observation_fields

r = get_all_observation_fields(search_query="DNA")

Sets an observation field value to an existing observation:

from pyinaturalist.rest_api import put_observation_field_values



0.8.0 (2019-07-11)

  • all functions now take an optional user-agent parameter in order to identify yourself to iNaturalist. If not set, Pyinaturalist/<VERSION> will be used.

0.7.0 (2019-05-08)

  • rest_api.delete_observation() now raises ObservationNotFound if the observation doesn’t exists
  • minor dependencies update for security reasons

0.6.0 (2018-11-15)

  • New function: rest_api.delete_observation()

0.5.0 (2018-11-05)

  • New function: node_api.get_observation()

0.4.0 (2018-11-05)

  • create_observation() now raises exceptions in case of errors.

0.3.0 (2018-11-05)

  • update_observation() now raises exceptions in case of errors.

0.2.0 (2018-10-31)

  • Better infrastructure (type annotations, documentation, …)
  • Dropped support for Python 2.
  • New function: update_observation()
  • rest_api.AuthenticationError is now exceptions.AuthenticationError

0.1.0 (2018-10-10)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pyinaturalist, version 0.8.0
Filename, size File type Python version Upload date Hashes
Filename, size pyinaturalist-0.8.0-py2.py3-none-any.whl (10.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size pyinaturalist-0.8.0.tar.gz (12.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page