# pyinaturalist
[](https://github.com/pyinat/pyinaturalist/actions)
[](https://codecov.io/gh/pyinat/pyinaturalist)
[](https://pyinaturalist.readthedocs.io)
[](https://pypi.org/project/pyinaturalist)
[](https://anaconda.org/conda-forge/pyinaturalist)
[](https://pypi.org/project/pyinaturalist)
[](https://mybinder.org/v2/gh/pyinat/pyinaturalist/main?urlpath=lab/tree/examples)
[](https://open.vscode.dev/pyinat/pyinaturalist)
<br/>
[](https://pyinaturalist.readthedocs.io)
# Introduction
[**iNaturalist**](https://www.inaturalist.org) 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](https://api.inaturalist.org/v1) that makes
these data easily accessible in the python programming language.
- [Features](#features)
- [Quickstart](#quickstart)
- [Next Steps](#next-steps)
- [Feedback](#feedback)
- [Related Projects](#related-projects)
## 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](https://www.inaturalist.org/pages/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:
```bash
pip install pyinaturalist
```
Then, import the main API functions:
```python
from pyinaturalist import *
```
### Search observations
Let's start by searching for all your own observations. There are
[numerous fields you can search on](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.create_observation), but we'll just use `user_id` for now:
```python
>>> 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:
```python
>>> 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](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.get_observation_species_counts).
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:
```python
>>> 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](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.get_observation_histogram),
which shows the number of observations over a given interval. The default is `month_of_year`:
```python
>>> 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](https://www.inaturalist.org/oauth/applications/new),
which will be used to get an access token.
```python
token = get_access_token(
username='my_username',
password='my_password',
app_id='my_app_id',
app_secret='my_app_secret',
)
```
See [Authentication](https://pyinaturalist.readthedocs.io/en/stable/user_guide.html#authentication)
for more options including environment variables, keyrings, and password managers.
Now we can [create a new observation](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.create_observation):
```python
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](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.update_observation) information, photos, or sounds:
```python
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](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.taxa.html#pyinaturalist.v1.taxa.get_taxa)
can be used to search by name, rank, and several other criteria
```python
>>> 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:
```python
>>> 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](https://pyinaturalist.readthedocs.io/en/stable/user_guide.html):
introduction and general features that apply to most endpoints
* [Endpoint Summary](https://pyinaturalist.readthedocs.io/en/stable/endpoints.html):
a complete list of endpoints wrapped by pyinaturalist
* [Examples](https://pyinaturalist.readthedocs.io/en/stable/examples.html):
data visualizations and other examples of things to do with iNaturalist data
* [Reference](https://pyinaturalist.readthedocs.io/en/stable/reference.html): Detailed API documentation
* [Contributing Guide](https://pyinaturalist.readthedocs.io/en/stable/contributing.html):
development details for anyone interested in contributing to pyinaturalist
* [History](https://github.com/pyinat/pyinaturalist/blob/dev/HISTORY.md):
details on past and current releases
* [Issues](https://github.com/pyinat/pyinaturalist/issues): planned & proposed features
## Feedback
If you have any problems, suggestions, or questions about pyinaturalist, you are welcome to [create an issue](https://github.com/pyinat/pyinaturalist/issues/new/choose) or [discussion](https://github.com/orgs/pyinat/discussions). 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](https://forum.inaturalist.org/) is the best place to start.
## Related Projects
Other python projects related to iNaturalist:
* [naturtag](https://github.com/pyinat/naturtag): A desktop application for tagging image files with iNaturalist taxonomy & observation metadata
* [pyinaturalist-convert](https://github.com/pyinat/pyinaturalist-convert): Tools to convert observation data to and from a variety of useful formats
* [pyinaturalist-notebook](https://github.com/pyinat/pyinaturalist-notebook): Jupyter notebook Docker image for pyinaturalist
* [dronefly](https://github.com/dronefly-garden/dronefly): A Discord bot with iNaturalist integration, used by the iNaturalist Discord server.
Raw data
{
"_id": null,
"home_page": "https://github.com/pyinat/pyinaturalist",
"name": "pyinaturalist",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "inaturalist,biodiversity,conservation,citizen-science,community-science,api,api-client,data-model,requests",
"author": "Jordan Cook",
"author_email": "jordan.cook.git@proton.me",
"download_url": "https://files.pythonhosted.org/packages/c9/15/8e314f41bb474f685771b2d6cecc8988719a17e30a81123a69e3d49b0419/pyinaturalist-0.19.0.tar.gz",
"platform": null,
"description": "# pyinaturalist\n\n[](https://github.com/pyinat/pyinaturalist/actions)\n[](https://codecov.io/gh/pyinat/pyinaturalist)\n[](https://pyinaturalist.readthedocs.io)\n\n[](https://pypi.org/project/pyinaturalist)\n[](https://anaconda.org/conda-forge/pyinaturalist)\n[](https://pypi.org/project/pyinaturalist)\n\n[](https://mybinder.org/v2/gh/pyinat/pyinaturalist/main?urlpath=lab/tree/examples)\n[](https://open.vscode.dev/pyinat/pyinaturalist)\n\n<br/>\n\n[](https://pyinaturalist.readthedocs.io)\n\n# Introduction\n[**iNaturalist**](https://www.inaturalist.org) is a community science platform that helps people\nget involved in the natural world by observing and identifying the living things around them.\nCollectively, the community produces a rich source of global biodiversity data that can be valuable\nto anyone from hobbyists to scientists.\n\n**pyinaturalist** is a client for the [iNaturalist API](https://api.inaturalist.org/v1) that makes\nthese data easily accessible in the python programming language.\n\n- [Features](#features)\n- [Quickstart](#quickstart)\n- [Next Steps](#next-steps)\n- [Feedback](#feedback)\n- [Related Projects](#related-projects)\n\n## Features\n* \u27a1\ufe0f **Easier requests:** Simplified request formats, easy pagination, and complete request\n parameter type annotations for better IDE integration\n* \u2b05\ufe0f **Convenient responses:** Type conversions to the things you would expect in python, and an\n optional object-oriented interface for response data\n* \ud83d\udd12 **Security:** Keyring integration for secure credential storage\n* \ud83d\udcd7 **Docs:** Example requests, responses, scripts, and Jupyter notebooks to help get you started\n* \ud83d\udc9a **Responsible use:** Follows the\n [API Recommended Practices](https://www.inaturalist.org/pages/api+recommended+practices)\n by default, so you can be nice to the iNaturalist servers and not worry about rate-limiting errors\n* \ud83e\uddea **Testing:** A dry-run testing mode to preview your requests before potentially modifying data\n\n### Supported Endpoints\nMany of the most relevant API endpoints are supported, including:\n* \ud83d\udcdd Annotations and observation fields\n* \ud83c\udd94 Identifications\n* \ud83d\udcac Messages\n* \ud83d\udc40 Observations (multiple formats)\n* \ud83d\udcf7 Observation photos + sounds\n* \ud83d\udcca Observation histograms, observers, identifiers, life lists, and species counts\n* \ud83d\udccd Places\n* \ud83d\udc65 Projects\n* \ud83d\udc26 Species\n* \ud83d\udc64 Users\n\n## Quickstart\nHere are usage examples for some of the most commonly used features.\n\nFirst, install with pip:\n```bash\npip install pyinaturalist\n```\n\nThen, import the main API functions:\n```python\nfrom pyinaturalist import *\n```\n\n### Search observations\nLet's start by searching for all your own observations. There are\n[numerous fields you can search on](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.create_observation), but we'll just use `user_id` for now:\n```python\n>>> observations = get_observations(user_id='my_username')\n```\n\nThe full response will be in JSON format, but we can use `pyinaturalist.pprint()` to print out a summary:\n```python\n>>> for obs in observations['results']:\n>>> pprint(obs)\nID Taxon Observed on User Location\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n117585709 Genus: Hyoscyamus (henbanes) May 18, 2022 niconoe Calvi, France\n117464920 Genus: Omophlus May 17, 2022 niconoe Gal\u00e9ria, France\n117464393 Genus: Briza (Rattlesnake Grasses) May 17, 2022 niconoe Gal\u00e9ria, France\n...\n```\n\nYou can also get\n[observation counts by species](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.get_observation_species_counts).\nOn iNaturalist.org, this information can be found on the 'Species' tab of search results.\nFor example, to get species counts of all your own research-grade observations:\n```python\n>>> counts = get_observation_species_counts(user_id='my_username', quality_grade='research')\n>>> pprint(counts)\n ID Rank Scientific name Common name Count\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n47934 species \ud83d\udc1b Libellula luctuosa Widow Skimmer 7\n48627 species \ud83c\udf3b Echinacea purpurea Purple Coneflower 6\n504060 species \ud83c\udf44 Pleurotus citrinopileatus Golden Oyster Mushroom 6\n...\n```\n\nAnother useful format is the\n[observation histogram](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.get_observation_histogram),\nwhich shows the number of observations over a given interval. The default is `month_of_year`:\n```python\n>>> histogram = get_observation_histogram(user_id='my_username')\n>>> print(histogram)\n{\n 1: 8, # January\n 2: 1, # February\n 3: 19, # March\n ..., # etc.\n}\n```\n\n### Create and update observations\nTo create or modify observations, you will first need to log in.\nThis requires creating an [iNaturalist app](https://www.inaturalist.org/oauth/applications/new),\nwhich will be used to get an access token.\n```python\ntoken = get_access_token(\n username='my_username',\n password='my_password',\n app_id='my_app_id',\n app_secret='my_app_secret',\n)\n```\nSee [Authentication](https://pyinaturalist.readthedocs.io/en/stable/user_guide.html#authentication)\nfor more options including environment variables, keyrings, and password managers.\n\nNow we can [create a new observation](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.create_observation):\n```python\nfrom datetime import datetime\n\nresponse = create_observation(\n taxon_id=54327, # Vespa Crabro\n observed_on_string=datetime.now(),\n time_zone='Brussels',\n description='This is a free text comment for the observation',\n tag_list='wasp, Belgium',\n latitude=50.647143,\n longitude=4.360216,\n positional_accuracy=50, # GPS accuracy in meters\n access_token=token,\n photos=['~/observations/wasp1.jpg', '~/observations/wasp2.jpg'],\n)\n\n# Save the new observation ID\nnew_observation_id = response[0]['id']\n```\n\nWe can then [update the observation](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.update_observation) information, photos, or sounds:\n```python\nupdate_observation(\n new_observation_id,\n access_token=token,\n description='updated description !',\n photos='~/observations/wasp_nest.jpg',\n sounds='~/observations/wasp_nest.mp3',\n)\n```\n\n### Search species\nLet's say you partially remember either a genus or family name that started with **'vespi'**-something.\nThe [taxa endpoint](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.taxa.html#pyinaturalist.v1.taxa.get_taxa)\ncan be used to search by name, rank, and several other criteria\n```python\n>>> response = get_taxa(q='vespi', rank=['genus', 'family'])\n```\n\nAs with observations, there is a lot of information in the response, but we'll print just a few basic details:\n```python\n>>> pprint(response)\n[52747] Family: Vespidae (Hornets, Paper Wasps, Potter Wasps, and Allies)\n[92786] Genus: Vespicula\n[84737] Genus: Vespina\n...\n```\n\n## Next Steps\nFor more information, see:\n\n* [User Guide](https://pyinaturalist.readthedocs.io/en/stable/user_guide.html):\n introduction and general features that apply to most endpoints\n* [Endpoint Summary](https://pyinaturalist.readthedocs.io/en/stable/endpoints.html):\n a complete list of endpoints wrapped by pyinaturalist\n* [Examples](https://pyinaturalist.readthedocs.io/en/stable/examples.html):\n data visualizations and other examples of things to do with iNaturalist data\n* [Reference](https://pyinaturalist.readthedocs.io/en/stable/reference.html): Detailed API documentation\n* [Contributing Guide](https://pyinaturalist.readthedocs.io/en/stable/contributing.html):\n development details for anyone interested in contributing to pyinaturalist\n* [History](https://github.com/pyinat/pyinaturalist/blob/dev/HISTORY.md):\n details on past and current releases\n* [Issues](https://github.com/pyinat/pyinaturalist/issues): planned & proposed features\n\n## Feedback\nIf you have any problems, suggestions, or questions about pyinaturalist, you are welcome to [create an issue](https://github.com/pyinat/pyinaturalist/issues/new/choose) or [discussion](https://github.com/orgs/pyinat/discussions). Also, **PRs are welcome!**\n\n**Note:** pyinaturalist is developed by members of the iNaturalist community, and is not endorsed by\niNaturalist.org or the California Academy of Sciences. If you have non-python-specific questions\nabout the iNaturalist API or iNaturalist in general, the\n[iNaturalist Community Forum](https://forum.inaturalist.org/) is the best place to start.\n\n## Related Projects\nOther python projects related to iNaturalist:\n\n* [naturtag](https://github.com/pyinat/naturtag): A desktop application for tagging image files with iNaturalist taxonomy & observation metadata\n* [pyinaturalist-convert](https://github.com/pyinat/pyinaturalist-convert): Tools to convert observation data to and from a variety of useful formats\n* [pyinaturalist-notebook](https://github.com/pyinat/pyinaturalist-notebook): Jupyter notebook Docker image for pyinaturalist\n* [dronefly](https://github.com/dronefly-garden/dronefly): A Discord bot with iNaturalist integration, used by the iNaturalist Discord server.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "iNaturalist API client for python",
"version": "0.19.0",
"project_urls": {
"Documentation": "https://pyinaturalist.readthedocs.io",
"Homepage": "https://github.com/pyinat/pyinaturalist",
"Repository": "https://github.com/pyinat/pyinaturalist"
},
"split_keywords": [
"inaturalist",
"biodiversity",
"conservation",
"citizen-science",
"community-science",
"api",
"api-client",
"data-model",
"requests"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b30659ddade0e4c6af4af7975c77d363b0d21c00b0198dc98fbbe96d0dca5fa",
"md5": "bcc12ba2e0545b2bec12b4e49503a7d1",
"sha256": "8062f91f777b0f1b539404a3a6d2531cfe83911c939a9dc0d4666b8b58430e52"
},
"downloads": -1,
"filename": "pyinaturalist-0.19.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bcc12ba2e0545b2bec12b4e49503a7d1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 143674,
"upload_time": "2023-12-12T06:38:19",
"upload_time_iso_8601": "2023-12-12T06:38:19.705803Z",
"url": "https://files.pythonhosted.org/packages/1b/30/659ddade0e4c6af4af7975c77d363b0d21c00b0198dc98fbbe96d0dca5fa/pyinaturalist-0.19.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c9158e314f41bb474f685771b2d6cecc8988719a17e30a81123a69e3d49b0419",
"md5": "14ba1fc30da61d3ac3b8f2cd0f44ace6",
"sha256": "cfe90a8ad579339f9d527e09f630f1ed0f1a43d9c5429f58f970ee294f053f73"
},
"downloads": -1,
"filename": "pyinaturalist-0.19.0.tar.gz",
"has_sig": false,
"md5_digest": "14ba1fc30da61d3ac3b8f2cd0f44ace6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 11096196,
"upload_time": "2023-12-12T06:38:23",
"upload_time_iso_8601": "2023-12-12T06:38:23.479329Z",
"url": "https://files.pythonhosted.org/packages/c9/15/8e314f41bb474f685771b2d6cecc8988719a17e30a81123a69e3d49b0419/pyinaturalist-0.19.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-12 06:38:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyinat",
"github_project": "pyinaturalist",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyinaturalist"
}
JSON
