Package: pyinaturalist
pyinaturalistIntroductioniNaturalistis 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.pyinaturalistis a client for theiNaturalist APIthat makes
these data easily accessible in the python programming language.FeaturesQuickstartNext StepsFeedbackRelated ProjectsFeatures➡️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 theAPI Recommended Practicesby 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 dataSupported EndpointsMany 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👤 UsersQuickstartHere are usage examples for some of the most commonly used features.First, install with pip:pipinstallpyinaturalistThen, import the main API functions:frompyinaturalistimport*Search observationsLet's start by searching for all your own observations. There arenumerous fields you can search on, but we'll just useuser_idfor now:>>>observations=get_observations(user_id='my_username')The full response will be in JSON format, but we can usepyinaturalist.pprint()to print out a summary:>>>forobsinobservations['results']:>>>pprint(obs)IDTaxonObservedonUserLocation━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━117585709Genus:Hyoscyamus(henbanes)May18,2022niconoeCalvi,France117464920Genus:OmophlusMay17,2022niconoeGaléria,France117464393Genus:Briza(RattlesnakeGrasses)May17,2022niconoeGaléria,France...You can also getobservation 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)IDRankScientificnameCommonnameCount━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━47934species🐛LibellulaluctuosaWidowSkimmer748627species🌻EchinaceapurpureaPurpleConeflower6504060species🍄PleurotuscitrinopileatusGoldenOysterMushroom6...Another useful format is theobservation histogram,
which shows the number of observations over a given interval. The default ismonth_of_year:>>>histogram=get_observation_histogram(user_id='my_username')>>>print(histogram){1:8,# January2:1,# February3:19,# March...,# etc.}Create and update observationsTo create or modify observations, you will first need to log in.
This requires creating aniNaturalist 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',)SeeAuthenticationfor more options including environment variables, keyrings, and password managers.Now we cancreate a new observation:fromdatetimeimportdatetimeresponse=create_observation(taxon_id=54327,# Vespa Crabroobserved_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 metersaccess_token=token,photos=['~/observations/wasp1.jpg','~/observations/wasp2.jpg'],)# Save the new observation IDnew_observation_id=response[0]['id']We can thenupdate the observationinformation, 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 speciesLet's say you partially remember either a genus or family name that started with'vespi'-something.
Thetaxa endpointcan 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,PaperWasps,PotterWasps,andAllies)[92786]Genus:Vespicula[84737]Genus:Vespina...Next StepsFor more information, see:User Guide:
introduction and general features that apply to most endpointsEndpoint Summary:
a complete list of endpoints wrapped by pyinaturalistExamples:
data visualizations and other examples of things to do with iNaturalist dataReference: Detailed API documentationContributing Guide:
development details for anyone interested in contributing to pyinaturalistHistory:
details on past and current releasesIssues: planned & proposed featuresFeedbackIf you have any problems, suggestions, or questions about pyinaturalist, you are welcome tocreate an issueordiscussion. 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, theiNaturalist Community Forumis the best place to start.Related ProjectsOther python projects related to iNaturalist:naturtag: A desktop application for tagging image files with iNaturalist taxonomy & observation metadatapyinaturalist-convert: Tools to convert observation data to and from a variety of useful formatspyinaturalist-notebook: Jupyter notebook Docker image for pyinaturalistdronefly: A Discord bot with iNaturalist integration, used by the iNaturalist Discord server.