Quickstart guide

About

R wrapper for iNaturalist APIs for accessing the observations. The detailed documentation of API is available on iNaturalist 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.

Taxon query

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

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 iNaturalist slug.

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.

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

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] 383

print(counts$species_counts[1:5,])

##   count taxon.id           taxon.name taxon.rank taxon.rank_level
## 1     5    41708       Phoca vitulina    species               10
## 2     5    57495      Melitaea cinxia    species               10
## 3     3    48662     Danaus plexippus    species               10
## 4     3    52766 Megaphasma denticrus    species               10
## 5     3    56057 Leucanthemum vulgare    species               10
##   taxon.default_name.id taxon.default_name.name
## 1                 67153             Harbor Seal
## 2                 91278    Glanville Fritillary
## 3                586653                 Monarch
## 4                 83649      Giant Walkingstick
## 5                924783             oxeye 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                       41708      2008-03-19T00:35:25.000Z
## 2                       57495      2010-03-17T06:57:02.000Z
## 3                       48662      2014-09-11T06:50:44.683Z
## 4                       52766      2009-08-24T02:06:09.000Z
## 5                       56057      2017-06-08T19:00:12.460Z
##   taxon.default_name.updated_at taxon.default_name.creator_id
## 1      2019-03-25T06:53:47.770Z                            NA
## 2      2010-03-17T06:57:02.000Z                            NA
## 3      2015-07-22T12:00:15.313Z                            NA
## 4      2009-08-24T02:06:09.000Z                            NA
## 5      2018-01-10T00:03:27.724Z                        498994
##   taxon.default_name.position
## 1                           0
## 2                           0
## 3                           1
## 4                           0
## 5                          17
##                                                       taxon.image_url
## 1 https://static.inaturalist.org/photos/3238907/square.jpg?1459150554
## 2 https://static.inaturalist.org/photos/5403994/square.jpg?1545659971
## 3    https://static.inaturalist.org/photos/1477/square.jpg?1545368454
## 4  https://static.inaturalist.org/photos/333073/square.jpg?1444606035
## 5  https://static.inaturalist.org/photos/361971/square.jpg?1444643087
##   taxon.iconic_taxon_name taxon.conservation_status_name
## 1                Mammalia                  least_concern
## 2                 Insecta                           <NA>
## 3                 Insecta                           <NA>
## 4                 Insecta                           <NA>
## 5                 Plantae                           <NA>

print(counts$rank_counts)

## $species
## [1] 325
## 
## $genus
## [1] 19
## 
## $subspecies
## [1] 18
## 
## $family
## [1] 6
## 
## $order
## [1] 3
## 
## $variety
## [1] 3
## 
## $class
## [1] 2
## 
## $kingdom
## [1] 2
## 
## $phylum
## [1] 1
## 
## $subclass
## [1] 1
## 
## $subfamily
## [1] 1
## 
## $superfamily
## [1] 1
## 
## $tribe
## [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] 155

print(counts$most_observations[1:10,])

##    count user.id      user.login              user.name
## 1     53  811118     sandbankspp                       
## 2     24  761669 kathleenfspicer                   <NA>
## 3     20  922078        hakai470 ES470: Hakai Institute
## 4     12  357375     richardling           Richard Ling
## 5     12  522214      tdavenport        Tripp Davenport
## 6     10    9706      greglasley            Greg Lasley
## 7      9 1422334          adriao                   <NA>
## 8      8  109098    leannewallis          Leanne Wallis
## 9      8  362446        pwdeacon             Pat Deacon
## 10     8  677594          nakarb              Robin Bad
##                                                                     user.user_icon_url
## 1  https://static.inaturalist.org/attachments/users/icons/811118/thumb.jpeg?1535236899
## 2                                                                                 <NA>
## 3                                                                                 <NA>
## 4   https://static.inaturalist.org/attachments/users/icons/357375/thumb.jpg?1484462740
## 5   https://static.inaturalist.org/attachments/users/icons/522214/thumb.jpg?1558671195
## 6     https://static.inaturalist.org/attachments/users/icons/9706/thumb.jpg?1533329961
## 7                                                                                 <NA>
## 8   https://static.inaturalist.org/attachments/users/icons/109098/thumb.jpg?1475547611
## 9   https://static.inaturalist.org/attachments/users/icons/362446/thumb.jpg?1546674469
## 10                                                                                <NA>

print(counts$most_species[1:10,])

##    count user.id      user.login              user.name
## 1     47  811118     sandbankspp                       
## 2     22  761669 kathleenfspicer                   <NA>
## 3     14  922078        hakai470 ES470: Hakai Institute
## 4     10    9706      greglasley            Greg Lasley
## 5     10  357375     richardling           Richard Ling
## 6      9  522214      tdavenport        Tripp Davenport
## 7      9 1422334          adriao                   <NA>
## 8      8  362446        pwdeacon             Pat Deacon
## 9      8 1519122       steven307          Steven Joyner
## 10     7  109098    leannewallis          Leanne Wallis
##                                                                      user.user_icon_url
## 1   https://static.inaturalist.org/attachments/users/icons/811118/thumb.jpeg?1535236899
## 2                                                                                  <NA>
## 3                                                                                  <NA>
## 4      https://static.inaturalist.org/attachments/users/icons/9706/thumb.jpg?1533329961
## 5    https://static.inaturalist.org/attachments/users/icons/357375/thumb.jpg?1484462740
## 6    https://static.inaturalist.org/attachments/users/icons/522214/thumb.jpg?1558671195
## 7                                                                                  <NA>
## 8    https://static.inaturalist.org/attachments/users/icons/362446/thumb.jpg?1546674469
## 9  https://static.inaturalist.org/attachments/users/icons/1519122/thumb.jpeg?1555274551
## 10   https://static.inaturalist.org/attachments/users/icons/109098/thumb.jpg?1475547611

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

## 164  Records

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

## [1] 5536

print(place_counts$most_observations[1:10,])

##    count user.id    user.login      user.name
## 1  41694   12158 erikamitchell Erika Mitchell
## 2  28614    2179       charlie   Charlie Hohn
## 3  13096   12610  susanelliott  Susan Elliott
## 4   7887   12045      larry522 Larry Clarfeld
## 5   7680   12036       zaccota       Zac Cota
## 6   6440     317   kpmcfarland Kent McFarland
## 7   6165   28921         rwp84    roy pilcher
## 8   6144  108365     judywelna               
## 9   5268   11792     kylejones     Kyle Jones
## 10  5162    6624   joannerusso               
##                                                                    user.user_icon_url
## 1   https://static.inaturalist.org/attachments/users/icons/12158/thumb.jpg?1558486310
## 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/12045/thumb.jpg?1475533238
## 5   https://static.inaturalist.org/attachments/users/icons/12036/thumb.jpg?1475533232
## 6     https://static.inaturalist.org/attachments/users/icons/317/thumb.jpg?1475527502
## 7   https://static.inaturalist.org/attachments/users/icons/28921/thumb.jpg?1475542431
## 8  https://static.inaturalist.org/attachments/users/icons/108365/thumb.jpg?1475547470
## 9   https://static.inaturalist.org/attachments/users/icons/11792/thumb.jpg?1475533125
## 10  https://static.inaturalist.org/attachments/users/icons/6624/thumb.jpeg?1562532360

print(place_counts$most_species[1:10,])

##    count user.id          user.login           user.name
## 1   2444   12158       erikamitchell      Erika Mitchell
## 2   2054   12045            larry522      Larry Clarfeld
## 3   2051   12610        susanelliott       Susan Elliott
## 4   1703    2179             charlie        Charlie Hohn
## 5   1509    6624         joannerusso                    
## 6   1489 1088797 montpelierbioblitz1 Montpelier BioBlitz
## 7   1453   11792           kylejones          Kyle Jones
## 8   1289     317         kpmcfarland      Kent McFarland
## 9   1261  108365           judywelna                    
## 10  1086   12049       gaudettelaura      Laura Gaudette
##                                                                    user.user_icon_url
## 1   https://static.inaturalist.org/attachments/users/icons/12158/thumb.jpg?1558486310
## 2   https://static.inaturalist.org/attachments/users/icons/12045/thumb.jpg?1475533238
## 3   https://static.inaturalist.org/attachments/users/icons/12610/thumb.jpg?1475533475
## 4    https://static.inaturalist.org/attachments/users/icons/2179/thumb.jpg?1475528361
## 5   https://static.inaturalist.org/attachments/users/icons/6624/thumb.jpeg?1562532360
## 6                                                                                <NA>
## 7   https://static.inaturalist.org/attachments/users/icons/11792/thumb.jpg?1475533125
## 8     https://static.inaturalist.org/attachments/users/icons/317/thumb.jpg?1475527502
## 9  https://static.inaturalist.org/attachments/users/icons/108365/thumb.jpg?1475547470
## 10  https://static.inaturalist.org/attachments/users/icons/12049/thumb.jpg?1475533241

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.