Access iNaturalist data through APIs

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)

## [1] "Triplex Cutworm Moth"    "Sphaeropthalma unicolor"
## [3] "Butterflies and Moths"   "Butterflies and Moths"  
## [5] "Synchlora faseolaria"    "Butterflies and Moths"

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)

## 178  records

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

## 178  records

## 0-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] 62480011
## 
## $observed_on
## [1] "2020-10-13"
## 
## $description
## NULL
## 
## $latitude
## [1] "32.5574184929"
## 
## $longitude
## [1] "-97.0614818484"
## 
## $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).

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

##               scientific_name                datetime         description
## 1            Danaus plexippus 2020-10-13 08:31:44 UTC                    
## 2        Sceloporus olivaceus 2020-10-12 13:42:17 UTC Texas spiney lizard
## 3             Helenium amarum 2020-10-12 13:35:05 UTC                    
## 4       Gleditsia triacanthos 2020-10-12 13:33:46 UTC                    
## 5         Prosopis glandulosa 2020-10-12 13:32:09 UTC                    
## 6 Parthenocissus quinquefolia 2020-10-12 13:27:19 UTC         Poison oak?
##               place_guess latitude
## 1 4606 Morning Glory Lane 32.55742
## 2      Mansfield, TX, USA 32.58743
## 3      Mansfield, TX, USA 32.58797
## 4      Mansfield, TX, USA 32.58798
## 5      Mansfield, TX, USA 32.58809
## 6      Mansfield, TX, USA 32.58756

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

## [1] 24389

### Top 5 species
counts$species_counts

##   count taxon.id           taxon.name taxon.rank taxon.rank_level
## 1   317    52821 Achillea millefolium    species               10
## 2   307    56057 Leucanthemum vulgare    species               10
## 3   306    48484    Harmonia axyridis    species               10
## 4   302    51875   Trifolium pratense    species               10
## 5   297    55745     Trifolium repens    species               10
##   taxon.default_name.id taxon.default_name.name taxon.default_name.is_valid
## 1                942097           common yarrow                        TRUE
## 2                924783             oxeye daisy                        TRUE
## 3                 89147       Asian Lady Beetle                        TRUE
## 4                942055              red clover                        TRUE
## 5                943715            white clover                        TRUE
##   taxon.default_name.lexicon taxon.default_name.taxon_id
## 1                    English                       52821
## 2                    English                       56057
## 3                    English                       48484
## 4                    English                       51875
## 5                    English                       55745
##   taxon.default_name.created_at taxon.default_name.updated_at
## 1      2017-08-07T02:40:53.003Z      2019-09-17T18:12:58.008Z
## 2      2017-06-08T19:00:12.460Z      2018-01-10T00:03:27.724Z
## 3      2010-02-17T12:47:07.000Z      2020-04-19T20:53:55.647Z
## 4      2017-08-07T01:27:15.421Z      2018-01-02T15:59:53.501Z
## 5      2017-08-13T16:25:49.758Z      2019-12-25T11:01:09.924Z
##   taxon.default_name.creator_id taxon.default_name.position
## 1                        516268                           0
## 2                        498994                          17
## 3                           357                           0
## 4                        516268                           0
## 5                        516268                           0
##   taxon.default_name.parameterized_lexicon
## 1                                  english
## 2                                  english
## 3                                  english
## 4                                  english
## 5                                  english
##                                                                                                                  taxon.image_url
## 1                                                               https://static.inaturalist.org/photos/4902/square.jpg?1545379591
## 2                                                           https://static.inaturalist.org/photos/71002344/square.jpg?1588538022
## 3                                                           https://static.inaturalist.org/photos/30978499/square.jpg?1549228178
## 4 https://upload.wikimedia.org/wikipedia/commons/thumb/a/ae/Trifolium_pratense_-_Keila2.jpg/75px-Trifolium_pratense_-_Keila2.jpg
## 5                                                                https://live.staticflickr.com/5604/30763110446_8a33878c19_s.jpg
##   taxon.iconic_taxon_name taxon.conservation_status_name
## 1                 Plantae                           <NA>
## 2                 Plantae                           <NA>
## 3                 Insecta                           <NA>
## 4                 Plantae                  least_concern
## 5                 Plantae                           <NA>

### Most common taxon ranks
counts$rank_counts

## $species
## [1] 17802
## 
## $genus
## [1] 3626
## 
## $subspecies
## [1] 665
## 
## $family
## [1] 619
## 
## $subfamily
## [1] 345
## 
## $tribe
## [1] 337
## 
## $variety
## [1] 199
## 
## $order
## [1] 138
## 
## $subgenus
## [1] 114
## 
## $superfamily
## [1] 87
## 
## $hybrid
## [1] 77
## 
## $subtribe
## [1] 73
## 
## $section
## [1] 49
## 
## $complex
## [1] 45
## 
## $class
## [1] 41
## 
## $suborder
## [1] 33
## 
## $infraorder
## [1] 26
## 
## $phylum
## [1] 25
## 
## $subclass
## [1] 14
## 
## $form
## [1] 11
## 
## $subphylum
## [1] 7
## 
## $subsection
## [1] 6
## 
## $infraclass
## [1] 5
## 
## $kingdom
## [1] 5
## 
## $genushybrid
## [1] 3
## 
## $superorder
## [1] 3
## 
## $zoosection
## [1] 3
## 
## $epifamily
## [1] 2
## 
## $zoosubsection
## [1] 2
## 
## $stateofmatter
## [1] 1

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

## [1] 241

counts$most_observations[1:10,]

##    count user.id      user.login              user.name
## 1    129  245282  hughmcguinness        Hugh McGuinness
## 2     53  811118     sandbankspp                       
## 3     34  541847      billhubick            Bill Hubick
## 4     25   46945             abe           T. Abe Lloyd
## 5     25  761669 kathleenfspicer                   <NA>
## 6     21    2616     alice_abela            Alice Abela
## 7     21  495266        maxa11an    Max Allan Niklasson
## 8     20  922078        hakai470 ES470: Hakai Institute
## 9     19 1588724         jrcagle                       
## 10    12  357375     richardling           Richard Ling
##                                                                     user.user_icon_url
## 1   https://static.inaturalist.org/attachments/users/icons/245282/thumb.jpg?1475532481
## 2  https://static.inaturalist.org/attachments/users/icons/811118/thumb.jpeg?1535236899
## 3   https://static.inaturalist.org/attachments/users/icons/541847/thumb.jpg?1582771190
## 4    https://static.inaturalist.org/attachments/users/icons/46945/thumb.jpg?1475588685
## 5                                                                                 <NA>
## 6     https://static.inaturalist.org/attachments/users/icons/2616/thumb.jpg?1475528533
## 7  https://static.inaturalist.org/attachments/users/icons/495266/thumb.jpeg?1579782546
## 8                                                                                 <NA>
## 9  https://static.inaturalist.org/attachments/users/icons/1588724/thumb.jpg?1566852095
## 10  https://static.inaturalist.org/attachments/users/icons/357375/thumb.jpg?1484462740

counts$most_species[1:10,]

##    count user.id      user.login              user.name
## 1     89  245282  hughmcguinness        Hugh McGuinness
## 2     47  811118     sandbankspp                       
## 3     24  761669 kathleenfspicer                   <NA>
## 4     20   46945             abe           T. Abe Lloyd
## 5     17    2616     alice_abela            Alice Abela
## 6     17  495266        maxa11an    Max Allan Niklasson
## 7     17  541847      billhubick            Bill Hubick
## 8     14  922078        hakai470 ES470: Hakai Institute
## 9     14 1588724         jrcagle                       
## 10    10    9706      greglasley            Greg Lasley
##                                                                     user.user_icon_url
## 1   https://static.inaturalist.org/attachments/users/icons/245282/thumb.jpg?1475532481
## 2  https://static.inaturalist.org/attachments/users/icons/811118/thumb.jpeg?1535236899
## 3                                                                                 <NA>
## 4    https://static.inaturalist.org/attachments/users/icons/46945/thumb.jpg?1475588685
## 5     https://static.inaturalist.org/attachments/users/icons/2616/thumb.jpg?1475528533
## 6  https://static.inaturalist.org/attachments/users/icons/495266/thumb.jpeg?1579782546
## 7   https://static.inaturalist.org/attachments/users/icons/541847/thumb.jpg?1582771190
## 8                                                                                 <NA>
## 9  https://static.inaturalist.org/attachments/users/icons/1588724/thumb.jpg?1566852095
## 10    https://static.inaturalist.org/attachments/users/icons/9706/thumb.jpg?1533329961

## By place_ID
vt_crows <- get_inat_obs_project("crows-in-vermont", type = "info", raw = FALSE)

## 178  records

place_counts <- get_inat_user_stats(place = vt_crows$place_id)
place_counts$total

## [1] 11853

place_counts$most_observations[1:10,]

##    count user.id    user.login      user.name
## 1  55497   12158 erikamitchell Erika Mitchell
## 2  36590    2179       charlie   Charlie Hohn
## 3  17732   12610  susanelliott  Susan Elliott
## 4  10497   12045      larry522 Larry Clarfeld
## 5   8875   12036       zaccota       Zac Cota
## 6   8529  108365     judywelna               
## 7   8143    6624   joannerusso               
## 8   8056     317   kpmcfarland Kent McFarland
## 9   7876   13355        beeboy  Spencer Hardy
## 10  7528   28921         rwp84    roy pilcher
##                                                                    user.user_icon_url
## 1   https://static.inaturalist.org/attachments/users/icons/12158/thumb.jpg?1586465563
## 2    https://static.inaturalist.org/attachments/users/icons/2179/thumb.jpg?1569109298
## 3   https://static.inaturalist.org/attachments/users/icons/12610/thumb.jpg?1475533475
## 4   https://static.inaturalist.org/attachments/users/icons/12045/thumb.jpg?1475533238
## 5   https://static.inaturalist.org/attachments/users/icons/12036/thumb.jpg?1475533232
## 6  https://static.inaturalist.org/attachments/users/icons/108365/thumb.jpg?1475547470
## 7   https://static.inaturalist.org/attachments/users/icons/6624/thumb.jpeg?1562532360
## 8     https://static.inaturalist.org/attachments/users/icons/317/thumb.jpg?1475527502
## 9   https://static.inaturalist.org/attachments/users/icons/13355/thumb.jpg?1475533838
## 10  https://static.inaturalist.org/attachments/users/icons/28921/thumb.jpg?1588726887

place_counts$most_species[1:10,]

##    count user.id          user.login           user.name
## 1   2886   12158       erikamitchell      Erika Mitchell
## 2   2290   12610        susanelliott       Susan Elliott
## 3   2242   12045            larry522      Larry Clarfeld
## 4   1839    2179             charlie        Charlie Hohn
## 5   1718    6624         joannerusso                    
## 6   1564   13355              beeboy       Spencer Hardy
## 7   1487   11792           kylejones          Kyle Jones
## 8   1481 1088797 montpelierbioblitz1 Montpelier BioBlitz
## 9   1423     317         kpmcfarland      Kent McFarland
## 10  1380 2860446            er-birds                    
##                                                                     user.user_icon_url
## 1    https://static.inaturalist.org/attachments/users/icons/12158/thumb.jpg?1586465563
## 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/2179/thumb.jpg?1569109298
## 5    https://static.inaturalist.org/attachments/users/icons/6624/thumb.jpeg?1562532360
## 6    https://static.inaturalist.org/attachments/users/icons/13355/thumb.jpg?1475533838
## 7    https://static.inaturalist.org/attachments/users/icons/11792/thumb.jpg?1475533125
## 8                                                                                 <NA>
## 9      https://static.inaturalist.org/attachments/users/icons/317/thumb.jpg?1475527502
## 10 https://static.inaturalist.org/attachments/users/icons/2860446/thumb.jpg?1588019864

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()