Tutorial 1: Observations#
This notebook will give a quick introduction to things you can do using data from your own iNaturalist observations.
[1]:
from datetime import datetime, timedelta
import ipyplot
from dateutil.relativedelta import relativedelta
from IPython.display import Image
from pyinaturalist import (
ICONIC_TAXA,
Observation,
TaxonCount,
UserCount,
enable_logging,
get_observation_histogram,
get_observation_identifiers,
get_observation_observers,
get_observation_species_counts,
get_observations,
pprint,
)
from rich import print
enable_logging()
Basic observation search#
We’ll start with the observation search page. get_observations() supports all the same search filters as the ones you see on iNaturalist.org:
Let’s start by searching for all of your own observations:
[2]:
# Replace with your own username
USERNAME = 'jkcook'
response = get_observations(user_id=USERNAME, page='all')
my_observations = Observation.from_json_list(response)
Observation data#
Take a look at one of the observations to see what information it contains:
[3]:
print(my_observations[0])
Observation( id=30688807, created_at=datetime.datetime(2019, 8, 12, 15, 22, 47, tzinfo=tzlocal()), captive=False, community_taxon_id=78444, description='Located in Green Meadows West Prairie\n\nSpecies IDs:\nhttps://sites.google.com/site/gmwprairie/gmw-prairie-flora', faves=[], geoprivacy=None, identifications_count=1, identifications_most_agree=True, identifications_most_disagree=False, identifications_some_agree=True, license_code='CC-BY-NC', location=(41.67206561, -93.72957587), mappable=True, num_identification_agreements=1, num_identification_disagreements=0, oauth_application_id=2, obscured=False, observed_on=datetime.datetime(2019, 8, 12, 10, 16, tzinfo=tzoffset('Etc/UTC', 0)), outlinks=[{'source': 'GBIF', 'url': 'http://www.gbif.org/occurrence/2429228652'}], out_of_range=None, owners_identification_from_vision=False, place_guess='Johnston, IA, USA', place_ids=[ 1, 24, 1582, 9853, 59613, 64422, 64423, 66741, 82256, 97394, 116535, 129109, 137509, 154492, 155074 ], positional_accuracy=12, preferences={'prefers_community_taxon': None}, project_ids=[48611], project_ids_with_curator_id=[], project_ids_without_curator_id=[48611], public_positional_accuracy=12, quality_grade='research', quality_metrics=[], reviewed_by=[1436999, 2115051], site_id=1, sounds=[], species_guess='Rocky Mountain bee plant', tags=[], updated_at=datetime.datetime(2019, 10, 16, 3, 43, 4, tzinfo=tzlocal()), uri='https://www.inaturalist.org/observations/30688807', uuid='aea799e1-4754-4eaf-adca-84720cdeaeb2', votes=[], annotations=[ [12] 12|13 (0 votes) ], comments=[], identifications=[ [66501609] 🌱 Species: Peritoma serrulata (Rocky Mountain beeplant) (improving) added on Aug 12, 2019 by jkcook, [74656703] 🌱 Species: Peritoma serrulata (Rocky Mountain beeplant) (supporting) added on Oct 16, 2019 by colincroft ], ofvs=[], photos=[ [47956314] https://inaturalist-open-data.s3.amazonaws.com/photos/47956314/original.jpeg?1565623377 (CC-BY-NC, 1365x2048) ], project_observations=[ ProjectObservation(id=33209242, preferences={'allows_curator_coordinate_access': True}, project={'id': 48611}, user_id=2115051, uuid='0ae36f62-59e8-4b90-affd-eb1ddb437262') ], taxon=[78444] 🌱 Species: Peritoma serrulata (Rocky Mountain beeplant), user=[2115051] jkcook (Jordan Cook) )
Observation data compared to the web UI#
Here is how some of those fields correspond to what you see on an observation page on iNaturalist.org: 
You’ll notice that there are many more fields available; see the Observation docs for a complete list.
Previewing data#
In many cases, you will want to quickly preview API results without looking through the full details for each result. pyinaturalist.pprint() can be used to show a condensed table of almost all response types. Here’s an example with just the first 30 results:
[4]:
pprint(my_observations[:30])
ID Taxon ID Taxon Observed on User Location ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 30688807 78444 🌱 Species: Peritom… Aug 12, 2019 jkcook Johnston, IA, USA serrulata (Rocky Mountain beeplant) 30688955 47912 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Asclepias tuberosa (butterfly milkweed) 30689111 60251 🌱 Species: Verbena Aug 12, 2019 jkcook Johnston, IA, USA hastata (blue vervain) 30689221 121968 🌽 Species: Aug 12, 2019 jkcook Johnston, IA, USA Andropogon gerardi (big bluestem) 30689306 121968 🌽 Species: Aug 12, 2019 jkcook Johnston, IA, USA Andropogon gerardi (big bluestem) 30689425 128701 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Desmanthus illinoensis (Illinois bundleflower) 30689463 121976 🌻 Species: Silphiu… Aug 12, 2019 jkcook Johnston, IA, USA laciniatum (compass plant) 30689506 136376 🌻 Species: Aug 12, 2019 jkcook Johnston, IA, USA Rudbeckia triloba (Brown-eyed Susan) 30689603 121976 🌻 Species: Silphiu… Aug 12, 2019 jkcook Johnston, IA, USA laciniatum (compass plant) 30689780 81594 🌾 Species: Elymus Aug 12, 2019 jkcook Johnston, IA, USA hystrix (bottlebrush grass) 30690105 127907 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Chamaecrista fasciculata (partridge pea) 30690175 141767 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Veronicastrum virginicum (Culver's root) 30690204 48678 🌼 Genus: Solidago Aug 12, 2019 jkcook Johnston, IA, USA (goldenrods) 30690327 128701 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Desmanthus illinoensis (Illinois bundleflower) 30726806 127186 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Securigera varia (purple crownvetch) 30727162 128695 🥕 Species: Eryngiu… Aug 12, 2019 jkcook Johnston, IA, USA yuccifolium (rattlesnake master) 30727377 136561 🌾 Form: Elymus Aug 12, 2019 jkcook Johnston, IA, USA canadensis glaucifolius 30727961 48662 🦋 Species: Danaus Aug 12, 2019 jkcook Green Meadows West plexippus (Monarch) Prairie 30728796 120215 🐝 Species: Bombus Aug 12, 2019 jkcook Green Meadows West griseocollis Prairie (Brown-belted Bumble Bee) 30728902 55556 🐛 Species: Aug 12, 2019 jkcook Green Meadows West Oncopeltus fasciatus Prairie (Large Milkweed Bug) 30729015 81599 🌻 Species: Silphiu… Aug 12, 2019 jkcook Green Meadows West perfoliatum (cup Prairie plant) 30729970 47911 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Asclepias syriaca (common milkweed) 30729981 130382 🌻 Species: Aug 12, 2019 jkcook Johnston, IA, USA Heliopsis helianthoides (false sunflower) 30730005 204330 🌱 Species: Iris Aug 12, 2019 jkcook Johnston, IA, USA domestica (Blackberry Lily) 30730009 128695 🥕 Species: Eryngiu… Aug 12, 2019 jkcook Johnston, IA, USA yuccifolium (rattlesnake master) 30730021 54781 🌳 Species: Quercus Aug 12, 2019 jkcook Johnston, IA, USA macrocarpa (bur oak) 30730033 127907 🌱 Species: Aug 12, 2019 jkcook Green Meadows West Chamaecrista Prairie fasciculata (partridge pea) 30730042 48627 🌻 Species: Aug 12, 2019 jkcook Johnston, IA, USA Echinacea purpurea (purple coneflower) 30730087 62741 🌻 Species: Aug 12, 2019 jkcook Johnston, IA, USA Rudbeckia hirta (black-eyed Susan) 30730133 56031 🌱 Genus: Calystegi… Aug 12, 2019 jkcook Green Meadows West (false bindweeds) Prairie
Observation species#
On iNaturalist.org, the next tab of the observation search page is Species. You can get this information with get_observation_species_counts().
For example, all the frogs and toads observed in Mexico: