Access iNaturalist data through APIs

Edmund Hart

2017-03-09

Quickstart guide

About

R wrapper for iNaturalist APIs for accessing the observations. The Detailed documentation of API is available on iNaturlaist website and is part of our larger species occurence searching packages SPOCC

Get observations

Searching

Fuzzy search

You can search for observations by either common or latin name. It will search the entire iNaturalist entry, 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)
## [1] "Yellow Birch"      "Western Spadefoot" "Western Spadefoot"
## [4] "Western Spadefoot" "Western Spadefoot" "Western Spadefoot"

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

## Return just observations in the family Plecoptera
stone_flies <- get_inat_obs(taxon_name  = "Plecoptera", year = 2010)

## Return just Monarch Butterfly records
just_butterflies <- 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)

Other functions

Get information and observations by project

You can get all the observations for a project if you know it’s ID or name as an intaturalist slug

## Just get info about a project
vt_crows <- get_inat_obs_project("crows-in-vermont", type = "info", raw = FALSE)
## 137  Records
## 0
## Now get all the observations for that project
vt_crows_obs <- get_inat_obs_project(vt_crows$id, type = "observations")
## 137  Records
## 0-100-200

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]))
## $id
## [1] 5264173
## 
## $observed_on
## [1] "2017-02-27"
## 
## $description
## [1] "chrysalis "
## 
## $latitude
## [1] "25.0593008014"
## 
## $longitude
## [1] "-77.4612933324"
## 
## $map_scale
## NULL

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)

m_obs <- get_inat_obs(query = "Monarch Butterfly")
head(get_inat_obs_user(as.character(m_obs$user_login[1]), maxresults = 20))[,1:5]
##       scientific_name                  datetime
## 1    Leptotes cassius 2017-02-27 15:14:00 -0500
## 2   Anartia jatrophae 2017-02-27 15:05:00 -0500
## 3    Danaus plexippus 2017-02-27 16:05:00 -0500
## 4      Crotophaga ani 2017-02-26 17:12:00 -0500
## 5 Nyctanassa violacea 2017-02-26 17:11:00 -0500
## 6   Mimus polyglottos 2017-02-26 17:10:00 -0500
##                                 description place_guess latitude
## 1 Cassius Blue butterfly (Leptotes cassius)     Bahamas 25.19087
## 2                                               Bahamas 25.01657
## 3                                chrysalis      Bahamas 25.05930
## 4                                               Bahamas 25.15073
## 5                                               Bahamas 25.12753
## 6                                               Bahamas 25.13950

Stats by taxa

Basic statistics are available for taxa counts by date, date range, place ID (numeric ID), or user ID (string)

## By date
counts <- get_inat_taxon_stats(date = "2010-06-14")
print(counts$total)
## [1] 120
print(counts$species_counts[1:5,])
##   count taxon.id            taxon.name taxon.rank taxon.rank_level
## 1     5    57495       Melitaea cinxia    species               10
## 2     2    17008       Sayornis phoebe    species               10
## 3     2    52589 Coenonympha pamphilus    species               10
## 4     2    55908         Lepus timidus    species               10
## 5     2    56057  Leucanthemum vulgare    species               10
##   taxon.default_name.id taxon.default_name.name
## 1                 91278    Glanville Fritillary
## 2                 20369          Eastern Phoebe
## 3                114753             Small Heath
## 4                 88688           Mountain Hare
## 5                 89055            Ox-eye Daisy
##   taxon.default_name.is_valid taxon.default_name.lexicon
## 1                        TRUE                    English
## 2                        TRUE                    English
## 3                        TRUE                    English
## 4                        TRUE                    English
## 5                        TRUE                    English
##   taxon.default_name.taxon_id taxon.default_name.created_at
## 1                       57495 2010-03-17T02:57:02.000-04:00
## 2                       17008 2008-03-12T23:33:20.000-04:00
## 3                       52589 2011-05-05T15:50:31.000-04:00
## 4                       55908 2010-02-11T11:05:42.000-05:00
## 5                       56057 2010-02-16T16:05:51.000-05:00
##   taxon.default_name.updated_at taxon.default_name.position
## 1 2010-03-17T02:57:02.000-04:00                           0
## 2 2008-03-12T23:33:20.000-04:00                           0
## 3 2011-05-05T15:50:31.000-04:00                           0
## 4 2010-02-11T11:05:42.000-05:00                           0
## 5 2017-01-04T18:57:29.655-05:00                           0
##                                                     taxon.image_url
## 1   https://farm6.staticflickr.com/5206/5309980832_01c907d2f9_s.jpg
## 2   https://farm6.staticflickr.com/5009/5346970195_d0eac9966b_s.jpg
## 3   https://farm5.staticflickr.com/4005/4624300321_d1a46ff97e_s.jpg
## 4  https://farm6.staticflickr.com/5483/11718223795_b05531bbf6_s.jpg
## 5 https://static.inaturalist.org/photos/10419/square.jpg?1444278709
##   taxon.iconic_taxon_name taxon.conservation_status_name
## 1                 Insecta                           <NA>
## 2                    Aves                  least_concern
## 3                 Insecta                           <NA>
## 4                Mammalia                  least_concern
## 5                 Plantae                           <NA>
print(counts$rank_counts)
## $species
## [1] 101
## 
## $genus
## [1] 8
## 
## $subspecies
## [1] 5
## 
## $family
## [1] 2
## 
## $variety
## [1] 2
## 
## $order
## [1] 1
## 
## $phylum
## [1] 1

Stats by user

Similar statistics can be gotten for users. The same input parameters can be used, but results are the top five users by species count and observation count.

## By date
counts <- get_inat_user_stats(date = "2010-06-14")
print(counts$total)
## [1] 61
print(counts$most_observations[1:10,])
##    count user.id            user.login        user.name
## 1     12  357375           richardling     Richard Ling
## 2     10    9706            greglasley      Greg Lasley
## 3      8  109098 leannewallisbiologist                 
## 4      8  362446              pwdeacon                 
## 5      7  317332        mortenddhansen Morten DD Hansen
## 6      4     357             annetanne                 
## 7      4    3499               bryanto                 
## 8      4   10285               finatic        BJ Stacey
## 9      3     382               tsoleau                 
## 10     3     873              tapbirds        Scott Cox
##                                                                     user.user_icon_url
## 1   https://static.inaturalist.org/attachments/users/icons/357375/thumb.jpg?1484462740
## 2     https://static.inaturalist.org/attachments/users/icons/9706/thumb.jpg?1475532223
## 3   https://static.inaturalist.org/attachments/users/icons/109098/thumb.jpg?1475547611
## 4   https://static.inaturalist.org/attachments/users/icons/362446/thumb.jpg?1478142809
## 5  https://static.inaturalist.org/attachments/users/icons/317332/thumb.jpeg?1475532800
## 6      https://static.inaturalist.org/attachments/users/icons/357/thumb.jpg?1475527524
## 7     https://static.inaturalist.org/attachments/users/icons/3499/thumb.jpg?1475528879
## 8    https://static.inaturalist.org/attachments/users/icons/10285/thumb.jpg?1475532519
## 9      https://static.inaturalist.org/attachments/users/icons/382/thumb.jpg?1475527539
## 10     https://static.inaturalist.org/attachments/users/icons/873/thumb.jpg?1475527722
print(counts$most_species[1:10,])
##    count user.id            user.login    user.name
## 1     10    9706            greglasley  Greg Lasley
## 2     10  357375           richardling Richard Ling
## 3      8  362446              pwdeacon             
## 4      7  109098 leannewallisbiologist             
## 5      4   10285               finatic    BJ Stacey
## 6      3     382               tsoleau             
## 7      3    3403                davidr      David R
## 8      3    3499               bryanto             
## 9      3   18056              plantman         <NA>
## 10     3   38530           kevinhintsa             
##                                                                    user.user_icon_url
## 1    https://static.inaturalist.org/attachments/users/icons/9706/thumb.jpg?1475532223
## 2  https://static.inaturalist.org/attachments/users/icons/357375/thumb.jpg?1484462740
## 3  https://static.inaturalist.org/attachments/users/icons/362446/thumb.jpg?1478142809
## 4  https://static.inaturalist.org/attachments/users/icons/109098/thumb.jpg?1475547611
## 5   https://static.inaturalist.org/attachments/users/icons/10285/thumb.jpg?1475532519
## 6     https://static.inaturalist.org/attachments/users/icons/382/thumb.jpg?1475527539
## 7    https://static.inaturalist.org/attachments/users/icons/3403/thumb.jpg?1475528831
## 8    https://static.inaturalist.org/attachments/users/icons/3499/thumb.jpg?1475528879
## 9                                                                                <NA>
## 10  https://static.inaturalist.org/attachments/users/icons/38530/thumb.jpg?1475547495
## By place_ID
vt_crows <- get_inat_obs_project("crows-in-vermont", type = "info", raw = FALSE)
## 137  Records
## 0
place_counts <- get_inat_user_stats(place = vt_crows$place_id)
print(place_counts$total)
## [1] 1428
print(place_counts$most_observations[1:10,])
##    count user.id    user.login      user.name
## 1  18923   12158 erikamitchell Erika Mitchell
## 2  15800    2179       charlie   Charlie Hohn
## 3   8046   12610  susanelliott  Susan Elliott
## 4   5924   12036       zaccota       Zac Cota
## 5   4389   11792     kylejones     Kyle Jones
## 6   4338   12045      larry522 Larry Clarfeld
## 7   4311     317   kpmcfarland Kent McFarland
## 8   3840   28921         rwp84    roy pilcher
## 9   3065   18303   marvelliott   Marv Elliott
## 10  2764   12049 gaudettelaura Laura Gaudette
##                                                                    user.user_icon_url
## 1  https://static.inaturalist.org/attachments/users/icons/12158/thumb.jpeg?1475533280
## 2    https://static.inaturalist.org/attachments/users/icons/2179/thumb.jpg?1475528361
## 3   https://static.inaturalist.org/attachments/users/icons/12610/thumb.jpg?1475533475
## 4   https://static.inaturalist.org/attachments/users/icons/12036/thumb.jpg?1475533232
## 5   https://static.inaturalist.org/attachments/users/icons/11792/thumb.jpg?1475533125
## 6   https://static.inaturalist.org/attachments/users/icons/12045/thumb.jpg?1475533238
## 7     https://static.inaturalist.org/attachments/users/icons/317/thumb.jpg?1475527502
## 8   https://static.inaturalist.org/attachments/users/icons/28921/thumb.jpg?1475542431
## 9   https://static.inaturalist.org/attachments/users/icons/18303/thumb.jpg?1475537232
## 10  https://static.inaturalist.org/attachments/users/icons/12049/thumb.jpg?1475533241
print(place_counts$most_species[1:10,])
##    count user.id    user.login      user.name
## 1   1917   12158 erikamitchell Erika Mitchell
## 2   1833   12610  susanelliott  Susan Elliott
## 3   1677   12045      larry522 Larry Clarfeld
## 4   1350   11792     kylejones     Kyle Jones
## 5   1235    2179       charlie   Charlie Hohn
## 6   1110    6624   joannerusso               
## 7   1060     317   kpmcfarland Kent McFarland
## 8   1007   12049 gaudettelaura Laura Gaudette
## 9    833    3847        rpayne      Ron Payne
## 10   793   28921         rwp84    roy pilcher
##                                                                    user.user_icon_url
## 1  https://static.inaturalist.org/attachments/users/icons/12158/thumb.jpeg?1475533280
## 2   https://static.inaturalist.org/attachments/users/icons/12610/thumb.jpg?1475533475
## 3   https://static.inaturalist.org/attachments/users/icons/12045/thumb.jpg?1475533238
## 4   https://static.inaturalist.org/attachments/users/icons/11792/thumb.jpg?1475533125
## 5    https://static.inaturalist.org/attachments/users/icons/2179/thumb.jpg?1475528361
## 6    https://static.inaturalist.org/attachments/users/icons/6624/thumb.jpg?1475530731
## 7     https://static.inaturalist.org/attachments/users/icons/317/thumb.jpg?1475527502
## 8   https://static.inaturalist.org/attachments/users/icons/12049/thumb.jpg?1475533241
## 9    https://static.inaturalist.org/attachments/users/icons/3847/thumb.jpg?1475529084
## 10  https://static.inaturalist.org/attachments/users/icons/28921/thumb.jpg?1475542431

Mapping.

Basic maps can be created as well to quickly visualize search results. Maps can either be plotted automatically plot = TRUE 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 salamanders in the genuse Ambystoma
m_obs <- get_inat_obs(taxon_name = "Ambystoma maculatum")

salamander_map <- inat_map(m_obs, plot = FALSE)
### Now we can modify the returned map
salamander_map + borders("state") + theme_bw()
## Warning: Removed 2 rows containing missing values (geom_point).