Build Codecov Documentation

PyPI Conda PyPI - Python Versions

Run with Binder Open in VSCode


Introduction#

iNaturalist is a community science platform that helps people get involved in the natural world by observing and identifying the living things around them. Collectively, the community produces a rich source of global biodiversity data that can be valuable to anyone from hobbyists to scientists.

pyinaturalist is a client for the iNaturalist API that makes these data easily accessible in the python programming language.

Features#

  • ➑️ Easier requests: Simplified request formats, easy pagination, and complete request parameter type annotations for better IDE integration

  • ⬅️ Convenient responses: Type conversions to the things you would expect in python, and an optional object-oriented interface for response data

  • πŸ”’ Security: Keyring integration for secure credential storage

  • πŸ“— Docs: Example requests, responses, scripts, and Jupyter notebooks to help get you started

  • πŸ’š Responsible use: Follows the API Recommended Practices by default, so you can be nice to the iNaturalist servers and not worry about rate-limiting errors

  • πŸ§ͺ Testing: A dry-run testing mode to preview your requests before potentially modifying data

Supported Endpoints#

Many of the most relevant API endpoints are supported, including:

  • πŸ“ Annotations and observation fields

  • πŸ†” Identifications

  • πŸ’¬ Messages

  • πŸ‘€ Observations (multiple formats)

  • πŸ“· Observation photos + sounds

  • πŸ“Š Observation histograms, observers, identifiers, life lists, and species counts

  • πŸ“ Places

  • πŸ‘₯ Projects

  • 🐦 Species

  • πŸ‘€ Users

Quickstart#

Here are usage examples for some of the most commonly used features.

First, install with pip:

pip install pyinaturalist

Then, import the main API functions:

from pyinaturalist import *

Search observations#

Let’s start by searching for all your own observations. There are numerous fields you can search on, but we’ll just use user_id for now:

>>> observations = get_observations(user_id='my_username')

The full response will be in JSON format, but we can use pyinaturalist.pprint() to print out a summary:

>>> for obs in observations['results']:
>>>    pprint(obs)
ID         Taxon                               Observed on   User     Location
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
117585709  Genus: Hyoscyamus (henbanes)        May 18, 2022  niconoe  Calvi, France
117464920  Genus: Omophlus                     May 17, 2022  niconoe  GalΓ©ria, France
117464393  Genus: Briza (Rattlesnake Grasses)  May 17, 2022  niconoe  GalΓ©ria, France
...

You can also get observation counts by species. On iNaturalist.org, this information can be found on the β€˜Species’ tab of search results. For example, to get species counts of all your own research-grade observations:

>>> counts = get_observation_species_counts(user_id='my_username', quality_grade='research')
>>> pprint(counts)
 ID     Rank      Scientific name               Common name             Count
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
47934   species   πŸ› Libellula luctuosa         Widow Skimmer           7
48627   species   🌻 Echinacea purpurea         Purple Coneflower       6
504060  species   πŸ„ Pleurotus citrinopileatus  Golden Oyster Mushroom  6
...

Another useful format is the observation histogram, which shows the number of observations over a given interval. The default is month_of_year:

>>> histogram = get_observation_histogram(user_id='my_username')
>>> print(histogram)
{
    1: 8,  # January
    2: 1,  # February
    3: 19, # March
    ...,   # etc.
}

Create and update observations#

To create or modify observations, you will first need to log in. This requires creating an iNaturalist app, which will be used to get an access token.

token = get_access_token(
    username='my_username',
    password='my_password',
    app_id='my_app_id',
    app_secret='my_app_secret',
)

See Authentication for more options including environment variables, keyrings, and password managers.

Now we can create a new observation:

from datetime import datetime

response = create_observation(
    taxon_id=54327,  # Vespa Crabro
    observed_on_string=datetime.now(),
    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,  # GPS accuracy in meters
    access_token=token,
    photos=['~/observations/wasp1.jpg', '~/observations/wasp2.jpg'],
)

# Save the new observation ID
new_observation_id = response[0]['id']

We can then update the observation information, photos, or sounds:

update_observation(
    new_observation_id,
    access_token=token,
    description='updated description !',
    photos='~/observations/wasp_nest.jpg',
    sounds='~/observations/wasp_nest.mp3',
)

Search species#

Let’s say you partially remember either a genus or family name that started with β€˜vespi’-something. The taxa endpoint can be used to search by name, rank, and several other criteria

>>> response = get_taxa(q='vespi', rank=['genus', 'family'])

As with observations, there is a lot of information in the response, but we’ll print just a few basic details:

>>> pprint(response)
[52747] Family: Vespidae (Hornets, Paper Wasps, Potter Wasps, and Allies)
[92786] Genus: Vespicula
[84737] Genus: Vespina
...

Next Steps#

For more information, see:

  • User Guide: introduction and general features that apply to most endpoints

  • Endpoint Summary: a complete list of endpoints wrapped by pyinaturalist

  • Examples: data visualizations and other examples of things to do with iNaturalist data

  • Reference: Detailed API documentation

  • Contributing Guide: development details for anyone interested in contributing to pyinaturalist

  • History: details on past and current releases

  • Issues: planned & proposed features

Feedback#

If you have any problems, suggestions, or questions about pyinaturalist, you are welcome to create an issue or discussion. Also, PRs are welcome!

Note: pyinaturalist is developed by members of the iNaturalist community, and is not endorsed by iNaturalist.org or the California Academy of Sciences. If you have non-python-specific questions about the iNaturalist API or iNaturalist in general, the iNaturalist Community Forum is the best place to start.

Contents#