Access iNaturalist data through APIs

In rinat: Access 'iNaturalist' Data Through APIs

knitr::opts_chunk$set(echo = TRUE, warning = FALSE)

About

rinat is a wrapper for iNaturalist APIs for accessing the observations. The detailed documentation of the API is available on the iNaturalist website and is part of our larger species occurrence searching packages SPOCC.

Quickstart guide

Get observations

Fuzzy search

You can search for observations by either common or scientific name. It will search the entire iNaturalist database, so the search below will return all entries that mention Monarch butterflies, not just entries for Monarchs.

library(rinat)
butterflies <- get_inat_obs(query = "Monarch Butterfly")

Another use for a fuzzy search is searching for a common name or habitat, e.g. searching for all observations that might happen in a vernal pool. We can then see all the species names found.

vp_obs <- get_inat_obs(query = "vernal pool")
head(vp_obs$species_guess)

Taxon query

To return only records for a specific species or taxonomic group, use the taxon option.

## Return observations in the family Nymphalidae, for 2015 only
nymphalidae <- get_inat_obs(taxon_name  = "Nymphalidae", year = 2015)

## Return just Monarch Butterfly records, all years
monarchs <- get_inat_obs(taxon_name = "Danaus plexippus")

Bounding box search

You can also search within a bounding box by giving a simple set of coordinates.

## Search by area
bounds <- c(38.44047, -125, 40.86652, -121.837)
deer <- get_inat_obs(query = "Mule Deer", bounds = bounds)
plot(deer$longitude, deer$latitude)

Other functions

Get information and observations by project

You can get all the observations for a project if you know its ID or name as an iNaturalist slug.

## Just get info about a project
vt_crows <- get_inat_obs_project("crows-in-vermont", type = "info", raw = FALSE)

## Now get all the observations for that project
vt_crows_obs <- get_inat_obs_project(vt_crows$id, type = "observations")

Get observation details

Detailed information about a specific observation can be retrieved by observation ID. The easiest way to get the ID is from a more general search.

m_obs <- get_inat_obs(query = "Monarch Butterfly")
head(get_inat_obs_id(m_obs$id[1]))

Get all observations by user

If you just want all the observations by a user you can download all their observations by user ID. A word of warning though, this can be quite large (easily into the 1000's).

user_obs <- get_inat_obs_user(m_obs$user_login[1], maxresults = 20)
head(user_obs)[,1:5]

Stats by taxa

Basic statistics are available for taxa counts by date, date range, place ID (numeric ID), or user ID (string). Only the top 5 species are listed.

## By date
counts <- get_inat_taxon_stats(date = "2020-06-14")
counts$total
### Top 5 species
counts$species_counts
### Most common taxon ranks
counts$rank_counts

Stats by user

Similar statistics can be gotten for users. The same input parameters can be used.

## By date
counts <- get_inat_user_stats(date = "2010-06-14")
counts$total
counts$most_observations[1:10,]
counts$most_species[1:10,]

## By place_ID
vt_crows <- get_inat_obs_project("crows-in-vermont", type = "info", raw = FALSE)
place_counts <- get_inat_user_stats(place = vt_crows$place_id)
place_counts$total
place_counts$most_observations[1:10,]
place_counts$most_species[1:10,]

Mapping

Basic maps can be created as well to quickly visualize search results. Maps can either be plotted automatically with plot = TRUE (the default), or simply return a ggplot2 object with plot = FALSE. This works well with single species data, but more complicated plots are best made from scratch.

library(ggplot2)

## Map 100 spotted salamanders
a_mac <- get_inat_obs(taxon_name = "Ambystoma maculatum")
salamander_map <- inat_map(a_mac, plot = FALSE)

### Now we can modify the returned map
salamander_map + borders("state") + theme_bw()

## A more elaborate map of Colibri sp.
colibri <- get_inat_obs(taxon_name = "Colibri",
                        quality = "research",
                        maxresults = 500)
ggplot(data = colibri, aes(x = longitude,
                         y = latitude,
                         colour = scientific_name)) +
  geom_polygon(data = map_data("world"),
                   aes(x = long, y = lat, group = group),
                   fill = "grey95",
                   color = "gray40",
                   size = 0.1) +
  geom_point(size = 0.7, alpha = 0.5) +
  coord_fixed(xlim = range(colibri$longitude, na.rm = TRUE),
              ylim = range(colibri$latitude, na.rm = TRUE)) +
  theme_bw()

rinat documentation built on March 8, 2021, 5:06 p.m.