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

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

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)
## 180  records
## Now get all the observations for that project
vt_crows_obs <- get_inat_obs_project(vt_crows$id, type = "observations")
## 180  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] 65519796
## 
## $observed_on
## [1] "2020-11-22"
## 
## $description
## [1] ""
## 
## $latitude
## [1] "35.1297595725"
## 
## $longitude
## [1] "-120.6323335986"
## 
## $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              Larus 2020-11-21 03:36:02 UTC            
## 2              Larus 2020-11-22 01:51:03 UTC            
## 3     Ardea herodias 2020-11-22 00:44:37 UTC            
## 4 Sayornis nigricans 2020-11-22 02:20:34 UTC            
## 5     Ardea herodias 2020-11-22 01:51:26 UTC            
## 6              Larus 2020-11-22 03:49:13 UTC            
##                     place_guess latitude
## 1         Arroyo Grande, CA, US 35.03365
## 2  Morro Bay, Morro Bay, CA, US 35.36754
## 3  Morro Bay, Morro Bay, CA, US 35.36950
## 4  Morro Bay, Morro Bay, CA, US 35.34652
## 5 Morro Rock, Morro Bay, CA, US 35.36843
## 6              Los Osos, CA, US 35.27388

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] 24566
### Top 5 species
counts$species_counts
##   count taxon.id           taxon.name taxon.rank taxon.rank_level
## 1   319    52821 Achillea millefolium    species               10
## 2   311    56057 Leucanthemum vulgare    species               10
## 3   307    48484    Harmonia axyridis    species               10
## 4   302    51875   Trifolium pratense    species               10
## 5   299    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://static.inaturalist.org/photos/81184045/square.jpg?1593273974
## 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] 17944
## 
## $genus
## [1] 3632
## 
## $subspecies
## [1] 675
## 
## $family
## [1] 620
## 
## $subfamily
## [1] 343
## 
## $tribe
## [1] 335
## 
## $variety
## [1] 202
## 
## $order
## [1] 137
## 
## $subgenus
## [1] 118
## 
## $superfamily
## [1] 87
## 
## $hybrid
## [1] 78
## 
## $subtribe
## [1] 77
## 
## $section
## [1] 50
## 
## $complex
## [1] 45
## 
## $class
## [1] 42
## 
## $suborder
## [1] 33
## 
## $infraorder
## [1] 26
## 
## $phylum
## [1] 24
## 
## $subclass
## [1] 15
## 
## $form
## [1] 11
## 
## $subphylum
## [1] 6
## 
## $subsection
## [1] 6
## 
## $infraclass
## [1] 5
## 
## $kingdom
## [1] 5
## 
## $genushybrid
## [1] 3
## 
## $superorder
## [1] 3
## 
## $zoosection
## [1] 3
## 
## $epifamily
## [1] 2
## 
## $subterclass
## [1] 2
## 
## $zoosubsection
## [1] 2

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] 247
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    15  800658      mangoverde           William Hull
##                                                                     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/800658/thumb.jpg?1523371975
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)
## 180  records
place_counts <- get_inat_user_stats(place = vt_crows$place_id)
place_counts$total
## [1] 12095
place_counts$most_observations[1:10,]
##    count user.id    user.login      user.name
## 1  60365   12158 erikamitchell Erika Mitchell
## 2  36947    2179       charlie   Charlie Hohn
## 3  17908   12610  susanelliott  Susan Elliott
## 4  10577   12045      larry522 Larry Clarfeld
## 5   8907   12036       zaccota       Zac Cota
## 6   8534  108365     judywelna               
## 7   8215    6624   joannerusso               
## 8   8145     317   kpmcfarland Kent McFarland
## 9   7932   13355        beeboy  Spencer Hardy
## 10  7565   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   2959   12158       erikamitchell      Erika Mitchell
## 2   2294   12610        susanelliott       Susan Elliott
## 3   2260   12045            larry522      Larry Clarfeld
## 4   1858    2179             charlie        Charlie Hohn
## 5   1719    6624         joannerusso                    
## 6   1576   13355              beeboy       Spencer Hardy
## 7   1496   11792           kylejones          Kyle Jones
## 8   1480 1088797 montpelierbioblitz1 Montpelier BioBlitz
## 9   1425     317         kpmcfarland      Kent McFarland
## 10  1419 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()