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] "" "Tardigrades" "Ciliates" "Жизнь" "Diatoms"
## [6] "Diatoms"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)## 202 records## Now get all the observations for that project
vt_crows_obs <- get_inat_obs_project(vt_crows$id, type = "observations")## 202 records## Getting records 0-200## Getting records up to 400## Done.## Note: mismatch between number of observations reported and returned by the API.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] 70791423
##
## $observed_on
## [1] "2021-03-06"
##
## $description
## NULL
##
## $latitude
## [1] "36.9917141215"
##
## $longitude
## [1] "-121.9112986752"
##
## $map_scale
## NULLGet 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 2021-03-06 13:17:22 -1000
## 2 Salvia splendens 2021-03-06 13:53:53 -1000
## 3 Quercus 2021-02-28 11:17:17 -1000
## 4 Dudleya 2021-02-28 10:26:30 -1000
## 5 Arctostaphylos glauca 2021-02-28 11:16:59 -1000
## 6 Calystegia 2021-02-28 11:15:35 -1000
## place_guess latitude
## 1 California, US 36.99171
## 2 California, US 36.96060
## 3 San Jose, CA 95120, USA 37.15662
## 4 San Jose, CA 95120, USA 37.15975
## 5 San Jose, CA 95120, USA 37.15662
## 6 San Jose, CA 95120, USA 37.15666Stats 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] 25013### Top 5 species
counts$species_counts## count taxon.id taxon.name taxon.rank taxon.rank_level
## 1 323 52821 Achillea millefolium species 10
## 2 316 56057 Leucanthemum vulgare species 10
## 3 312 48484 Harmonia axyridis species 10
## 4 306 51875 Trifolium pratense species 10
## 5 303 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://inaturalist-open-data.s3.amazonaws.com/photos/4902/square.jpg?1545379591
## 2 https://inaturalist-open-data.s3.amazonaws.com/photos/71002344/square.jpg?1588538022
## 3 https://static.inaturalist.org/photos/30978499/square.jpg?1549228178
## 4 https://inaturalist-open-data.s3.amazonaws.com/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] 18303
##
## $genus
## [1] 3651
##
## $subspecies
## [1] 698
##
## $family
## [1] 623
##
## $subfamily
## [1] 361
##
## $tribe
## [1] 335
##
## $variety
## [1] 205
##
## $order
## [1] 133
##
## $subgenus
## [1] 130
##
## $superfamily
## [1] 87
##
## $hybrid
## [1] 80
##
## $subtribe
## [1] 76
##
## $section
## [1] 60
##
## $complex
## [1] 50
##
## $class
## [1] 40
##
## $suborder
## [1] 32
##
## $infraorder
## [1] 27
##
## $phylum
## [1] 23
##
## $subclass
## [1] 17
##
## $form
## [1] 12
##
## $subphylum
## [1] 7
##
## $subsection
## [1] 7
##
## $infraclass
## [1] 5
##
## $kingdom
## [1] 5
##
## $genushybrid
## [1] 3
##
## $subterclass
## [1] 3
##
## $superorder
## [1] 3
##
## $zoosection
## [1] 3
##
## $epifamily
## [1] 2
##
## $zoosubsection
## [1] 2Stats 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] 269counts$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 31 6930 tgosliner Terry Gosliner
## 5 26 280446 mtjones Mike Jones
## 6 25 46945 abe T. Abe Lloyd
## 7 25 761669 kathleenfspicer <NA>
## 8 21 2616 alice_abela Alice Abela
## 9 21 495266 maxa11an Max Allan Niklasson
## 10 20 922078 hakai470 ES470: Hakai Institute
## 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/6930/thumb.jpg?1475530872
## 5 https://static.inaturalist.org/attachments/users/icons/280446/thumb.jpg?1598408556
## 6 https://static.inaturalist.org/attachments/users/icons/46945/thumb.jpg?1475588685
## 7 <NA>
## 8 https://static.inaturalist.org/attachments/users/icons/2616/thumb.jpg?1475528533
## 9 https://static.inaturalist.org/attachments/users/icons/495266/thumb.jpeg?1579782546
## 10 <NA>counts$most_species[1:10,]## count user.id user.login user.name
## 1 89 245282 hughmcguinness Hugh McGuinness
## 2 47 811118 sandbankspp
## 3 25 6930 tgosliner Terry Gosliner
## 4 24 761669 kathleenfspicer <NA>
## 5 20 46945 abe T. Abe Lloyd
## 6 17 2616 alice_abela Alice Abela
## 7 17 495266 maxa11an Max Allan Niklasson
## 8 17 541847 billhubick Bill Hubick
## 9 15 280446 mtjones Mike Jones
## 10 15 1426686 taimyr Игорь Поспелов
## 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/6930/thumb.jpg?1475530872
## 4 <NA>
## 5 https://static.inaturalist.org/attachments/users/icons/46945/thumb.jpg?1475588685
## 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 https://static.inaturalist.org/attachments/users/icons/541847/thumb.jpg?1582771190
## 9 https://static.inaturalist.org/attachments/users/icons/280446/thumb.jpg?1598408556
## 10 https://static.inaturalist.org/attachments/users/icons/1426686/thumb.jpg?1560925189## By place_ID
vt_crows <- get_inat_obs_project("crows-in-vermont", type = "info", raw = FALSE)## 202 recordsplace_counts <- get_inat_user_stats(place = vt_crows$place_id)
place_counts$total## [1] 12454place_counts$most_observations[1:10,]## count user.id user.login user.name
## 1 65150 12158 erikamitchell Erika Mitchell
## 2 37009 2179 charlie Charlie Hohn
## 3 18115 12610 susanelliott Susan Elliott
## 4 10731 12045 larry522 Larry Clarfeld
## 5 8985 12036 zaccota Zac Cota
## 6 8554 108365 judywelna
## 7 8281 317 kpmcfarland Kent McFarland
## 8 8281 6624 joannerusso
## 9 7972 13355 beeboy Spencer Hardy
## 10 7614 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/317/thumb.jpg?1475527502
## 8 https://static.inaturalist.org/attachments/users/icons/6624/thumb.jpeg?1562532360
## 9 https://static.inaturalist.org/attachments/users/icons/13355/thumb.jpg?1475533838
## 10 https://static.inaturalist.org/attachments/users/icons/28921/thumb.jpg?1588726887place_counts$most_species[1:10,]## count user.id user.login user.name
## 1 3029 12158 erikamitchell Erika Mitchell
## 2 2303 12610 susanelliott Susan Elliott
## 3 2274 12045 larry522 Larry Clarfeld
## 4 1882 2179 charlie Charlie Hohn
## 5 1726 6624 joannerusso
## 6 1625 13355 beeboy Spencer Hardy
## 7 1507 11792 kylejones Kyle Jones
## 8 1472 1088797 montpelierbioblitz1 Montpelier BioBlitz
## 9 1438 317 kpmcfarland Kent McFarland
## 10 1425 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?1588019864Mapping
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()