pyinaturalist 0.8.0

Python client for the iNaturalist APIs

Python client for the iNaturalist APIs.

Status

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.

Examples

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>',
                         app_id='<your_inaturalist_app_id>',
                         app_secret=<your_inaturalist_app_secret>)

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
             'observed_on_string': datetime.datetime.now().isoformat(),
             '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_values_attributes':
                [{'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'),
                             access_token=token)

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

put_observation_field_values(observation_id=7345179,
                             observation_field_id=9613,
                             value=250,
                             access_token=token)

History

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.