rgbif introduction

Seach and retrieve data from the Global Biodiverity Information Facilty (GBIF)

About the package

rgbif is an R package to search and retrieve data from the Global Biodiverity Information Facilty (GBIF). rgbif wraps R code around the GBIF API to allow you to talk to GBIF from R.

Get rgbif

Install from CRAN

install.packages("rgbif")

Or install the development version from GitHub

devtools::install_github("ropensci/rgbif")

Load rgbif

library("rgbif")

Number of occurrences

Search by type of record, all observational in this case

occ_count(basisOfRecord='OBSERVATION')
#> [1] 96716255

Records for Puma concolor with lat/long data (georeferened) only. Note that hasCoordinate in occ_search() is the same as georeferenced in occ_count().

occ_count(taxonKey=2435099, georeferenced=TRUE)
#> [1] 2737

All georeferenced records in GBIF

occ_count(georeferenced=TRUE)
#> [1] 559796294

Records from Denmark

denmark_code <- isocodes[grep("Denmark", isocodes$name), "code"]
occ_count(country=denmark_code)
#> [1] 9640425

Number of records in a particular dataset

occ_count(datasetKey='9e7ea106-0bf8-4087-bb61-dfe4f29e0f17')
#> [1] 4591

All records from 2012

occ_count(year=2012)
#> [1] 39241894

Records for a particular dataset, and only for preserved specimens

occ_count(datasetKey='e707e6da-e143-445d-b41d-529c4a777e8b', basisOfRecord='OBSERVATION')
#> [1] 2120907

Search for taxon names

Get possible values to be used in taxonomic rank arguments in functions

taxrank()
#> [1] "kingdom"       "phylum"        "class"         "order"        
#> [5] "family"        "genus"         "species"       "infraspecific"

name_lookup() does full text search of name usages covering the scientific and vernacular name, the species description, distribution and the entire classification across all name usages of all or some checklists. Results are ordered by relevance as this search usually returns a lot of results.

By default name_lookup() returns five slots of information: meta, data, facets, hierarchies, and names. hierarchies and names elements are named by their matching GBIF key in the data.frame in the data slot.

out <- name_lookup(query='mammalia')
names(out)
#> [1] "meta"        "data"        "facets"      "hierarchies" "names"
out$meta
#>   offset limit endOfRecords count
#> 1      0   100        FALSE 98345
head(out$data)
#>         key                 scientificName
#> 1 101961729 Mammalia (awaiting allocation)
#> 2 100375341                       Mammalia
#> 3 101961726 Mammalia (awaiting allocation)
#> 4 113391223        Mammalia Linnaeus, 1758
#> 5       359        Mammalia Linnaeus, 1758
#> 6 100348839         Mammalia Linnaeus 1758
#>                             datasetKey parentKey   parent  kingdom
#> 1 714c64e3-2dc1-4bb7-91e4-54be5af4da12 101961726 Mammalia Animalia
#> 2 16c3f9cb-4b19-4553-ac8e-ebb90003aa02        NA     <NA>     <NA>
#> 3 714c64e3-2dc1-4bb7-91e4-54be5af4da12 101959399 Mammalia Animalia
#> 4 cbb6498e-8927-405a-916b-576d00a6289b 113301736 Chordata Animalia
#> 5 d7dddbf4-2cf0-4f39-9b2a-bb099caae36c        44 Chordata Animalia
#> 6 16c3f9cb-4b19-4553-ac8e-ebb90003aa02 100347572 Chordata     <NA>
#>     phylum    order   family kingdomKey phylumKey  classKey  orderKey
#> 1 Chordata Mammalia Mammalia  101859873 101946562 101959399 101961726
#> 2     <NA>     <NA>     <NA>         NA        NA 100375341        NA
#> 3 Chordata Mammalia     <NA>  101859873 101946562 101959399 101961726
#> 4 Chordata     <NA>     <NA>  112707351 113301736 113391223        NA
#> 5 Chordata     <NA>     <NA>          1        44       359        NA
#> 6 Chordata     <NA>     <NA>         NA 100347572 100348839        NA
#>   familyKey canonicalName     authorship   nameType taxonomicStatus   rank
#> 1 101961729      Mammalia                   NO_NAME        ACCEPTED FAMILY
#> 2        NA      Mammalia                SCIENTIFIC            <NA>  CLASS
#> 3        NA      Mammalia                   NO_NAME        ACCEPTED  ORDER
#> 4        NA      Mammalia Linnaeus, 1758 SCIENTIFIC            <NA>  CLASS
#> 5        NA      Mammalia Linnaeus, 1758 SCIENTIFIC        ACCEPTED  CLASS
#> 6        NA      Mammalia Linnaeus, 1758 SCIENTIFIC            <NA>  CLASS
#>   numDescendants numOccurrences habitats nomenclaturalStatus
#> 1            138              0     <NA>                <NA>
#> 2              0              0     <NA>                <NA>
#> 3            139              0     <NA>                <NA>
#> 4           3477              0     <NA>                <NA>
#> 5          30001              0   MARINE                <NA>
#> 6              0              0     <NA>                <NA>
#>   threatStatuses synonym    class nubKey   taxonID extinct
#> 1             NA   FALSE Mammalia     NA      <NA>      NA
#> 2             NA   FALSE Mammalia    359   2621711    TRUE
#> 3             NA   FALSE Mammalia     NA      <NA>      NA
#> 4             NA   FALSE Mammalia    359     18838      NA
#> 5             NA   FALSE Mammalia    359 119459549   FALSE
#> 6             NA   FALSE Mammalia    359      7907      NA
#>                                                                                                                                                                                                                      publishedIn
#> 1                                                                                                                                                                                                                           <NA>
#> 2                                                                                                                                                                                                                           <NA>
#> 3                                                                                                                                                                                                                           <NA>
#> 4                                                                                                                                                                                                                           <NA>
#> 5 Linnaeus, C. (1758). Systema Naturae per regna tria naturae, secundum classes, ordines, genera, species, cum characteribus, differentiis, synonymis, locis. Editio decima, reformata. Laurentius Salvius: Holmiae. ii, 824 pp.
#> 6                                                                                                                                                                                                                           <NA>
#>                               accordingTo species speciesKey acceptedKey
#> 1                                    <NA>    <NA>         NA          NA
#> 2                                    <NA>    <NA>         NA          NA
#> 3                                    <NA>    <NA>         NA          NA
#> 4                                    <NA>    <NA>         NA          NA
#> 5 The Catalogue of Life, 3rd January 2011    <NA>         NA          NA
#> 6                                    <NA>    <NA>         NA          NA
#>   accepted genus genusKey
#> 1     <NA>  <NA>       NA
#> 2     <NA>  <NA>       NA
#> 3     <NA>  <NA>       NA
#> 4     <NA>  <NA>       NA
#> 5     <NA>  <NA>       NA
#> 6     <NA>  <NA>       NA
out$facets
#> NULL
out$hierarchies[1:2]
#> $`101961729`
#>     rankkey     name
#> 1 101859873 Animalia
#> 2 101946562 Chordata
#> 3 101959399 Mammalia
#> 4 101961726 Mammalia
#> 
#> $`101961726`
#>     rankkey     name
#> 1 101859873 Animalia
#> 2 101946562 Chordata
#> 3 101959399 Mammalia
out$names[2]
#> $`113391223`
#>   vernacularName language
#> 1        Mammals      eng

Search for a genus

head(name_lookup(query='Cnaemidophorus', rank="genus", return="data"))
#>         key                  scientificName
#> 1 113100610 Cnaemidophorus Wallengren, 1862
#> 2   1858636 Cnaemidophorus Wallengren, 1862
#> 3 100555508 Cnaemidophorus Wallengren, 1862
#> 4 110531263                  Cnaemidophorus
#> 5 100555497                  Cnaemidophorus
#> 6 113212699                  Cnaemidophorus
#>                             datasetKey  nubKey parentKey        parent
#> 1 cbb6498e-8927-405a-916b-576d00a6289b 1858636 113099670 Pterophoridae
#> 2 d7dddbf4-2cf0-4f39-9b2a-bb099caae36c 1858636      8863 Pterophoridae
#> 3 16c3f9cb-4b19-4553-ac8e-ebb90003aa02 1858636 100555506 Pterophoridae
#> 4 7ddf754f-d193-4cc9-b351-99906754a03b 1858636 110531096 Pterophoridae
#> 5 16c3f9cb-4b19-4553-ac8e-ebb90003aa02 1858636 100555496 Pterophoridae
#> 6 cbb6498e-8927-405a-916b-576d00a6289b 1858636 113212683 Pterophoridae
#>    kingdom     phylum       order        family          genus kingdomKey
#> 1 Animalia Arthropoda Lepidoptera Pterophoridae Cnaemidophorus  112707351
#> 2 Animalia Arthropoda Lepidoptera Pterophoridae Cnaemidophorus          1
#> 3     <NA>       <NA> Lepidoptera Pterophoridae Cnaemidophorus         NA
#> 4 Animalia Arthropoda Lepidoptera Pterophoridae Cnaemidophorus  109354902
#> 5     <NA>       <NA> Lepidoptera Pterophoridae Cnaemidophorus         NA
#> 6 Animalia Arthropoda Lepidoptera Pterophoridae Cnaemidophorus  112707351
#>   phylumKey  classKey  orderKey familyKey  genusKey  canonicalName
#> 1 112710199 112780522 112876893 113099670 113100610 Cnaemidophorus
#> 2        54       216       797      8863   1858636 Cnaemidophorus
#> 3        NA        NA 100555505 100555506 100555508 Cnaemidophorus
#> 4 109380340 109498964 110368094 110531096 110531263 Cnaemidophorus
#> 5        NA        NA 100555495 100555496 100555497 Cnaemidophorus
#> 6 113188372 113191312 113197877 113212683 113212699 Cnaemidophorus
#>         authorship   nameType  rank numDescendants numOccurrences
#> 1 Wallengren, 1862 SCIENTIFIC GENUS              2              0
#> 2 Wallengren, 1862 SCIENTIFIC GENUS              4              0
#> 3 Wallengren, 1862 SCIENTIFIC GENUS              0              0
#> 4                  SCIENTIFIC GENUS              2              0
#> 5                  SCIENTIFIC GENUS              1              0
#> 6                  SCIENTIFIC GENUS              1              0
#>     taxonID habitats nomenclaturalStatus threatStatuses synonym   class
#> 1  29079847       NA                  NA             NA   FALSE Insecta
#> 2 115123697       NA                  NA             NA   FALSE Insecta
#> 3   3502919       NA                  NA             NA   FALSE    <NA>
#> 4  22715482       NA                  NA             NA   FALSE Insecta
#> 5      <NA>       NA                  NA             NA   FALSE    <NA>
#> 6      <NA>       NA                  NA             NA   FALSE Insecta
#>                                               publishedIn    accordingTo
#> 1                                                    <NA>           <NA>
#> 2 K. svenska VetenskAkad. Handl. , (N. F. ) 3, no. 7, 10. Fauna Europaea
#> 3                                                    <NA>           <NA>
#> 4                                                    <NA>           <NA>
#> 5                                                    <NA>           <NA>
#> 6                                                    <NA>           <NA>
#>   taxonomicStatus extinct acceptedKey accepted
#> 1            <NA>      NA          NA     <NA>
#> 2        ACCEPTED   FALSE          NA     <NA>
#> 3            <NA>      NA          NA     <NA>
#> 4            <NA>      NA          NA     <NA>
#> 5        ACCEPTED      NA          NA     <NA>
#> 6        ACCEPTED      NA          NA     <NA>

Search for the class mammalia

head(name_lookup(query='mammalia', return = 'data'))
#>         key                 scientificName
#> 1 101961729 Mammalia (awaiting allocation)
#> 2 100375341                       Mammalia
#> 3 101961726 Mammalia (awaiting allocation)
#> 4 113391223        Mammalia Linnaeus, 1758
#> 5       359        Mammalia Linnaeus, 1758
#> 6 100348839         Mammalia Linnaeus 1758
#>                             datasetKey parentKey   parent  kingdom
#> 1 714c64e3-2dc1-4bb7-91e4-54be5af4da12 101961726 Mammalia Animalia
#> 2 16c3f9cb-4b19-4553-ac8e-ebb90003aa02        NA     <NA>     <NA>
#> 3 714c64e3-2dc1-4bb7-91e4-54be5af4da12 101959399 Mammalia Animalia
#> 4 cbb6498e-8927-405a-916b-576d00a6289b 113301736 Chordata Animalia
#> 5 d7dddbf4-2cf0-4f39-9b2a-bb099caae36c        44 Chordata Animalia
#> 6 16c3f9cb-4b19-4553-ac8e-ebb90003aa02 100347572 Chordata     <NA>
#>     phylum    order   family kingdomKey phylumKey  classKey  orderKey
#> 1 Chordata Mammalia Mammalia  101859873 101946562 101959399 101961726
#> 2     <NA>     <NA>     <NA>         NA        NA 100375341        NA
#> 3 Chordata Mammalia     <NA>  101859873 101946562 101959399 101961726
#> 4 Chordata     <NA>     <NA>  112707351 113301736 113391223        NA
#> 5 Chordata     <NA>     <NA>          1        44       359        NA
#> 6 Chordata     <NA>     <NA>         NA 100347572 100348839        NA
#>   familyKey canonicalName     authorship   nameType taxonomicStatus   rank
#> 1 101961729      Mammalia                   NO_NAME        ACCEPTED FAMILY
#> 2        NA      Mammalia                SCIENTIFIC            <NA>  CLASS
#> 3        NA      Mammalia                   NO_NAME        ACCEPTED  ORDER
#> 4        NA      Mammalia Linnaeus, 1758 SCIENTIFIC            <NA>  CLASS
#> 5        NA      Mammalia Linnaeus, 1758 SCIENTIFIC        ACCEPTED  CLASS
#> 6        NA      Mammalia Linnaeus, 1758 SCIENTIFIC            <NA>  CLASS
#>   numDescendants numOccurrences habitats nomenclaturalStatus
#> 1            138              0     <NA>                <NA>
#> 2              0              0     <NA>                <NA>
#> 3            139              0     <NA>                <NA>
#> 4           3477              0     <NA>                <NA>
#> 5          30001              0   MARINE                <NA>
#> 6              0              0     <NA>                <NA>
#>   threatStatuses synonym    class nubKey   taxonID extinct
#> 1             NA   FALSE Mammalia     NA      <NA>      NA
#> 2             NA   FALSE Mammalia    359   2621711    TRUE
#> 3             NA   FALSE Mammalia     NA      <NA>      NA
#> 4             NA   FALSE Mammalia    359     18838      NA
#> 5             NA   FALSE Mammalia    359 119459549   FALSE
#> 6             NA   FALSE Mammalia    359      7907      NA
#>                                                                                                                                                                                                                      publishedIn
#> 1                                                                                                                                                                                                                           <NA>
#> 2                                                                                                                                                                                                                           <NA>
#> 3                                                                                                                                                                                                                           <NA>
#> 4                                                                                                                                                                                                                           <NA>
#> 5 Linnaeus, C. (1758). Systema Naturae per regna tria naturae, secundum classes, ordines, genera, species, cum characteribus, differentiis, synonymis, locis. Editio decima, reformata. Laurentius Salvius: Holmiae. ii, 824 pp.
#> 6                                                                                                                                                                                                                           <NA>
#>                               accordingTo species speciesKey acceptedKey
#> 1                                    <NA>    <NA>         NA          NA
#> 2                                    <NA>    <NA>         NA          NA
#> 3                                    <NA>    <NA>         NA          NA
#> 4                                    <NA>    <NA>         NA          NA
#> 5 The Catalogue of Life, 3rd January 2011    <NA>         NA          NA
#> 6                                    <NA>    <NA>         NA          NA
#>   accepted genus genusKey
#> 1     <NA>  <NA>       NA
#> 2     <NA>  <NA>       NA
#> 3     <NA>  <NA>       NA
#> 4     <NA>  <NA>       NA
#> 5     <NA>  <NA>       NA
#> 6     <NA>  <NA>       NA

Look up the species Helianthus annuus

head(name_lookup(query = 'Helianthus annuus', rank="species", return = 'data'))
#>         key                             scientificName
#> 1 113584542                       Helianthus annuus L.
#> 2   3119195                       Helianthus annuus L.
#> 3 100336353                       Helianthus annuus L.
#> 4 103340289                          Helianthus annuus
#> 5 102912762 'Helianthus annuus' fasciation phytoplasma
#> 6 103628852                       Helianthus annuus L.
#>                             datasetKey  nubKey parentKey
#> 1 cbb6498e-8927-405a-916b-576d00a6289b 3119195 113584540
#> 2 d7dddbf4-2cf0-4f39-9b2a-bb099caae36c 3119195   3119134
#> 3 16c3f9cb-4b19-4553-ac8e-ebb90003aa02 3119195 100336352
#> 4 fab88965-e69d-4491-a04d-e3198b626e52 3119195 103340270
#> 5 fab88965-e69d-4491-a04d-e3198b626e52 3119195 102912523
#> 6 046bbc50-cae2-47ff-aa43-729fbf53f7c5 3119195 103504882
#>                      parent       kingdom             order
#> 1                Helianthus       Plantae         Asterales
#> 2                Helianthus       Plantae         Asterales
#> 3                Helianthus       Plantae         Asterales
#> 4                Helianthus Viridiplantae         Asterales
#> 5 unclassified phytoplasmas          <NA> Acholeplasmatales
#> 6                Asteraceae       Plantae              <NA>
#>               family      genus           species kingdomKey  orderKey
#> 1         Asteraceae Helianthus Helianthus annuus  113551056 113580333
#> 2         Asteraceae Helianthus Helianthus annuus          6       414
#> 3         Asteraceae Helianthus Helianthus annuus  100325740 100336278
#> 4         Asteraceae Helianthus Helianthus annuus  102974832 103311652
#> 5 Acholeplasmataceae Candidatus Helianthus annuus         NA 102911070
#> 6         Asteraceae       <NA> Helianthus annuus  103198669        NA
#>   familyKey  genusKey speciesKey     canonicalName authorship   nameType
#> 1 113580355 113584540  113584542 Helianthus annuus         L. SCIENTIFIC
#> 2      3065   3119134    3119195 Helianthus annuus         L. SCIENTIFIC
#> 3 100336349 100336352  100336353 Helianthus annuus         L. SCIENTIFIC
#> 4 103311763 103340270  103340289 Helianthus annuus            SCIENTIFIC
#> 5 102911072 102911169  102912762 Helianthus annuus            SCIENTIFIC
#> 6 103504882        NA  103628852 Helianthus annuus         L. SCIENTIFIC
#>      rank numDescendants numOccurrences                         taxonID
#> 1 SPECIES              0              0                           57622
#> 2 SPECIES             36              0                       107290518
#> 3 SPECIES              0              0                          112763
#> 4 SPECIES              2              0                            4232
#> 5 SPECIES              0              0                         1301613
#> 6 SPECIES              0              0 urn:lsid:ipni.org:names:90623-3
#>      habitats nomenclaturalStatus threatStatuses synonym basionymKey
#> 1        <NA>                <NA>             NA   FALSE          NA
#> 2 TERRESTRIAL                <NA>             NA   FALSE     3119205
#> 3        <NA>                <NA>             NA   FALSE          NA
#> 4        <NA>                <NA>             NA   FALSE          NA
#> 5        <NA>                <NA>             NA   FALSE          NA
#> 6        <NA>                <NA>             NA   FALSE          NA
#>                                    basionym        phylum phylumKey
#> 1                                      <NA>          <NA>        NA
#> 2 Helianthus lenticularis Douglas ex Lindl. Magnoliophyta        49
#> 3                                      <NA>          <NA>        NA
#> 4                                      <NA>  Streptophyta 102986054
#> 5                                      <NA>   Tenericutes 102911063
#> 6                                      <NA>          <NA>        NA
#>    classKey         publishedIn                             accordingTo
#> 1        NA                <NA>                                    <NA>
#> 2       220 Sp. pl. 2:904. 1753 Integrated Taxonomic Information System
#> 3 100328106                <NA>                                    <NA>
#> 4        NA                <NA>                                    <NA>
#> 5 102911065                <NA>                                    <NA>
#> 6        NA                <NA>                                    <NA>
#>   taxonomicStatus extinct         class acceptedKey accepted
#> 1            <NA>      NA          <NA>          NA     <NA>
#> 2        ACCEPTED   FALSE Magnoliopsida          NA     <NA>
#> 3            <NA>      NA Magnoliopsida          NA     <NA>
#> 4            <NA>      NA          <NA>          NA     <NA>
#> 5            <NA>      NA    Mollicutes          NA     <NA>
#> 6            <NA>      NA          <NA>          NA     <NA>

The function name_usage() works with lots of different name endpoints in GBIF, listed at http://www.gbif.org/developer/species#nameUsages.

library("plyr")
out <- name_usage(key=3119195, language="FRENCH", data='vernacularNames')
head(out$data)
#>     vernacularName language sourceTaxonKey preferred source
#> 1      Sonnenblume      deu      101321447        NA   <NA>
#> 2          alizeti      swa      101321447        NA   <NA>
#> 3 annual sunflower      eng      102234356        NA   <NA>
#> 4 common sunflower               103340289        NA   <NA>
#> 5 common sunflower      eng      102234356        NA   <NA>
#> 6          girasol      spa      101321447        NA   <NA>

The function name_backbone() is used to search against the GBIF backbone taxonomy

name_backbone(name='Helianthus', rank='genus', kingdom='plants')
#> $usageKey
#> [1] 3119134
#> 
#> $scientificName
#> [1] "Helianthus L."
#> 
#> $canonicalName
#> [1] "Helianthus"
#> 
#> $rank
#> [1] "GENUS"
#> 
#> $status
#> [1] "ACCEPTED"
#> 
#> $confidence
#> [1] 97
#> 
#> $matchType
#> [1] "EXACT"
#> 
#> $kingdom
#> [1] "Plantae"
#> 
#> $phylum
#> [1] "Magnoliophyta"
#> 
#> $order
#> [1] "Asterales"
#> 
#> $family
#> [1] "Asteraceae"
#> 
#> $genus
#> [1] "Helianthus"
#> 
#> $kingdomKey
#> [1] 6
#> 
#> $phylumKey
#> [1] 49
#> 
#> $classKey
#> [1] 220
#> 
#> $orderKey
#> [1] 414
#> 
#> $familyKey
#> [1] 3065
#> 
#> $genusKey
#> [1] 3119134
#> 
#> $synonym
#> [1] FALSE
#> 
#> $class
#> [1] "Magnoliopsida"

The function name_suggest() is optimized for speed, and gives back suggested names based on query parameters.

head( name_suggest(q='Puma concolor') )
#>       key              canonicalName       rank
#> 1 2435099              Puma concolor    SPECIES
#> 2 6164591  Puma concolor kaibabensis SUBSPECIES
#> 3 6164600        Puma concolor coryi SUBSPECIES
#> 4 6164603 Puma concolor missoulensis SUBSPECIES
#> 5 6164604   Puma concolor stanleyana SUBSPECIES
#> 6 6164620       Puma concolor cougar SUBSPECIES

Single occurrence records

Get data for a single occurrence. Note that data is returned as a list, with slots for metadata and data, or as a hierarchy, or just data.

Just data

occ_get(key=766766824, return='data')
#>              name       key decimalLatitude decimalLongitude        issues
#> 1 Corvus monedula 766766824         59.4568          17.9054 depunl,gass84

Just taxonomic hierarchy

occ_get(key=766766824, return='hier')
#>              name     key    rank
#> 1        Animalia       1 kingdom
#> 2        Chordata      44  phylum
#> 3            Aves     212   class
#> 4   Passeriformes     729   order
#> 5        Corvidae    5235  family
#> 6          Corvus 2482468   genus
#> 7 Corvus monedula 2482473 species

All data, or leave return parameter blank

occ_get(key=766766824, return='all')
#> $hierarchy
#>              name     key    rank
#> 1        Animalia       1 kingdom
#> 2        Chordata      44  phylum
#> 3            Aves     212   class
#> 4   Passeriformes     729   order
#> 5        Corvidae    5235  family
#> 6          Corvus 2482468   genus
#> 7 Corvus monedula 2482473 species
#> 
#> $media
#> list()
#> 
#> $data
#>              name       key decimalLatitude decimalLongitude        issues
#> 1 Corvus monedula 766766824         59.4568          17.9054 depunl,gass84

Get many occurrences. occ_get is vectorized

occ_get(key=c(766766824, 101010, 240713150, 855998194), return='data')
#>                  name       key decimalLatitude decimalLongitude
#> 1     Corvus monedula 766766824         59.4568          17.9054
#> 2 Platydoras costatus    101010         -4.3500         -70.0667
#> 3            Pelosina 240713150        -77.5667         163.5830
#> 4    Sciurus vulgaris 855998194         58.4068          12.0438
#>           issues
#> 1  depunl,gass84
#> 2 cucdmis,gass84
#> 3 cdround,gass84
#> 4  depunl,gass84

Search for occurrences

By default occ_search() returns a dplyr like output summary in which the data printed expands based on how much data is returned, and the size of your window. You can search by scientific name:

occ_search(scientificName = "Ursus americanus", limit = 20)
#> Records found [7337] 
#> Records returned [20] 
#> No. unique hierarchies [1] 
#> No. media records [19] 
#> Args [scientificName=Ursus americanus, limit=20, offset=0, fields=all] 
#> First 10 rows of data
#> 
#>                name        key decimalLatitude decimalLongitude
#> 1  Ursus americanus 1065590124        38.36662        -79.68283
#> 2  Ursus americanus 1065588899        35.73304        -82.42028
#> 3  Ursus americanus 1065611122        43.94883        -72.77432
#> 4  Ursus americanus 1098894889        23.66893        -99.09625
#> 5  Ursus americanus 1088908315        43.86464        -72.34617
#> 6  Ursus americanus 1088932238        32.65219       -108.53674
#> 7  Ursus americanus 1132403409        40.13240       -123.82900
#> 8  Ursus americanus 1088923534        36.93018        -78.25027
#> 9  Ursus americanus 1088932273        32.65237       -108.53691
#> 10 Ursus americanus 1088962169        43.72044        -72.59416
#> ..              ...        ...             ...              ...
#> Variables not shown: issues (chr), datasetKey (chr), publishingOrgKey
#>      (chr), publishingCountry (chr), protocol (chr), lastCrawled (chr),
#>      lastParsed (chr), extensions (chr), basisOfRecord (chr), taxonKey
#>      (int), kingdomKey (int), phylumKey (int), classKey (int), orderKey
#>      (int), familyKey (int), genusKey (int), speciesKey (int),
#>      scientificName (chr), kingdom (chr), phylum (chr), order (chr),
#>      family (chr), genus (chr), species (chr), genericName (chr),
#>      specificEpithet (chr), taxonRank (chr), dateIdentified (chr), year
#>      (int), month (int), day (int), eventDate (chr), modified (chr),
#>      lastInterpreted (chr), references (chr), identifiers (chr), facts
#>      (chr), relations (chr), geodeticDatum (chr), class (chr), countryCode
#>      (chr), country (chr), rightsHolder (chr), identifier (chr),
#>      verbatimEventDate (chr), datasetName (chr), gbifID (chr),
#>      collectionCode (chr), occurrenceID (chr), taxonID (chr), recordedBy
#>      (chr), catalogNumber (chr), http...unknown.org.occurrenceDetails
#>      (chr), institutionCode (chr), rights (chr), eventTime (chr),
#>      occurrenceRemarks (chr), identificationID (chr), verbatimLocality
#>      (chr), infraspecificEpithet (chr), informationWithheld (chr)

Or to be more precise, you can search for names first, make sure you have the right name, then pass the GBIF key to the occ_search() function:

key <- name_suggest(q='Helianthus annuus', rank='species')$key[1]
occ_search(taxonKey=key, limit=20)
#> Records found [21577] 
#> Records returned [20] 
#> No. unique hierarchies [1] 
#> No. media records [14] 
#> Args [taxonKey=3119195, limit=20, offset=0, fields=all] 
#> First 10 rows of data
#> 
#>                 name        key decimalLatitude decimalLongitude
#> 1  Helianthus annuus 1143516596        35.42767       -105.06884
#> 2  Helianthus annuus 1095851641         0.00000          0.00000
#> 3  Helianthus annuus 1088900309        33.95239       -117.32011
#> 4  Helianthus annuus 1088944416        26.20518        -98.26725
#> 5  Helianthus annuus 1135523136        33.96709       -117.99769
#> 6  Helianthus annuus 1135826959              NA               NA
#> 7  Helianthus annuus 1092889645         1.27617        103.79136
#> 8  Helianthus annuus 1092901911        30.22344        -97.95281
#> 9  Helianthus annuus 1135523412        33.96787       -118.00016
#> 10 Helianthus annuus 1090389390        59.96150         17.71060
#> ..               ...        ...             ...              ...
#> Variables not shown: issues (chr), datasetKey (chr), publishingOrgKey
#>      (chr), publishingCountry (chr), protocol (chr), lastCrawled (chr),
#>      lastParsed (chr), extensions (chr), basisOfRecord (chr), taxonKey
#>      (int), kingdomKey (int), phylumKey (int), classKey (int), orderKey
#>      (int), familyKey (int), genusKey (int), speciesKey (int),
#>      scientificName (chr), kingdom (chr), phylum (chr), order (chr),
#>      family (chr), genus (chr), species (chr), genericName (chr),
#>      specificEpithet (chr), taxonRank (chr), dateIdentified (chr), year
#>      (int), month (int), day (int), eventDate (chr), modified (chr),
#>      lastInterpreted (chr), references (chr), identifiers (chr), facts
#>      (chr), relations (chr), geodeticDatum (chr), class (chr), countryCode
#>      (chr), country (chr), rightsHolder (chr), identifier (chr),
#>      verbatimEventDate (chr), datasetName (chr), gbifID (chr),
#>      verbatimLocality (chr), collectionCode (chr), occurrenceID (chr),
#>      taxonID (chr), recordedBy (chr), catalogNumber (chr),
#>      http...unknown.org.occurrenceDetails (chr), institutionCode (chr),
#>      rights (chr), occurrenceRemarks (chr), identificationID (chr),
#>      elevation (dbl), elevationAccuracy (dbl), stateProvince (chr),
#>      recordNumber (chr), locality (chr), municipality (chr), language
#>      (chr), type (chr), ownerInstitutionCode (chr), identifiedBy (chr),
#>      eventTime (chr), informationWithheld (chr), coordinateAccuracy (dbl),
#>      depth (dbl), depthAccuracy (dbl), county (chr)

Like many functions in rgbif, you can choose what to return with the return parameter, here, just returning the metadata:

occ_search(taxonKey=key, return='meta')
#>   offset limit endOfRecords count
#> 1    300   200        FALSE 21577

You can choose what fields to return. This isn't passed on to the API query to GBIF as they don't allow that, but we filter out the columns before we give the data back to you.

occ_search(scientificName = "Ursus americanus", fields=c('name','basisOfRecord','protocol'), limit = 20)
#> Records found [7337] 
#> Records returned [20] 
#> No. unique hierarchies [1] 
#> No. media records [19] 
#> Args [scientificName=Ursus americanus, limit=20, offset=0,
#>      fields=name,basisOfRecord,protocol] 
#> First 10 rows of data
#> 
#>                name    protocol     basisOfRecord
#> 1  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 2  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 3  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 4  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 5  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 6  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 7  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 8  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 9  Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> 10 Ursus americanus DWC_ARCHIVE HUMAN_OBSERVATION
#> ..              ...         ...               ...

Most parameters are vectorized, so you can pass in more than one value:

splist <- c('Cyanocitta stelleri', 'Junco hyemalis', 'Aix sponsa')
keys <- sapply(splist, function(x) name_suggest(x)$key[1], USE.NAMES=FALSE)
occ_search(taxonKey=keys, limit=5)
#> Occ. found [2482598 (455654), 2492010 (2469837), 2498387 (774491)] 
#> Occ. returned [2482598 (5), 2492010 (5), 2498387 (5)] 
#> No. unique hierarchies [2482598 (1), 2492010 (1), 2498387 (1)] 
#> No. media records [2482598 (5), 2492010 (5), 2498387 (3)] 
#> Args [taxonKey=2482598,2492010,2498387, limit=5, offset=0, fields=all] 
#> First 10 rows of data from 2482598
#> 
#>                  name        key decimalLatitude decimalLongitude
#> 1 Cyanocitta stelleri 1065588311        37.26200        -122.3271
#> 2 Cyanocitta stelleri 1052604494        37.76975        -122.4715
#> 3 Cyanocitta stelleri 1065590449        37.50713        -122.4818
#> 4 Cyanocitta stelleri 1065588252        36.54670        -105.1335
#> 5 Cyanocitta stelleri 1065597471        39.11136        -120.1687
#> Variables not shown: issues (chr), datasetKey (chr), publishingOrgKey
#>      (chr), publishingCountry (chr), protocol (chr), lastCrawled (chr),
#>      lastParsed (chr), extensions (chr), basisOfRecord (chr), taxonKey
#>      (int), kingdomKey (int), phylumKey (int), classKey (int), orderKey
#>      (int), familyKey (int), genusKey (int), speciesKey (int),
#>      scientificName (chr), kingdom (chr), phylum (chr), order (chr),
#>      family (chr), genus (chr), species (chr), genericName (chr),
#>      specificEpithet (chr), taxonRank (chr), dateIdentified (chr), year
#>      (int), month (int), day (int), eventDate (chr), modified (chr),
#>      lastInterpreted (chr), references (chr), identifiers (chr), facts
#>      (chr), relations (chr), geodeticDatum (chr), class (chr), countryCode
#>      (chr), country (chr), rightsHolder (chr), identifier (chr),
#>      verbatimEventDate (chr), datasetName (chr), gbifID (chr),
#>      verbatimLocality (chr), collectionCode (chr), occurrenceID (chr),
#>      taxonID (chr), recordedBy (chr), catalogNumber (chr),
#>      http...unknown.org.occurrenceDetails (chr), institutionCode (chr),
#>      rights (chr), eventTime (chr), identificationID (chr),
#>      occurrenceRemarks (chr)

Maps

Static map using the ggplot2 package. Make a map of Puma concolor occurrences.

key <- name_backbone(name='Puma concolor')$speciesKey
dat <- occ_search(taxonKey=key, return='data', limit=300)
gbifmap(dat)

plot of chunk gbifmap1