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.
Many of the most relevant API endpoints are supported, including:
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 *
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.
}
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',
)
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
...
For more information, see:
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.
Other python projects related to iNaturalist:
FAQs
iNaturalist API client for python
We found that pyinaturalist demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.