Learn R Programming
⚠️There's a newer version (3.8.1) of this package.Take me there.

rgbif

rgbif gives you access to data from GBIF via their REST API. GBIF versions their API - we are currently using v1 of their API. You can no longer use their old API in this package - see ?rgbif-defunct.

To get started, see:

  • rgbif vignette: an introduction to the package's main functionalities.
  • Function reference: an overview of all rgbif functions.
  • Articles: vignettes/tutorials on how to download data, clean data, and work with taxonomic names.
  • Occurrence manual: a book covering a suite of R packages used for working with biological occurrence data.

Check out the rgbif paper for more information on this package and the sister Python and Ruby clients.

Package API

The rgbif package API follows the GBIF API, which has the following sections:

contributing organizations, installations, networks, and nodes * rgbif functions: dataset_metrics(), dataset_search(), dataset_suggest(), datasets(), enumeration(), enumeration_country(), installations(), networks(), nodes(), organizations() * Registry also includes the GBIF OAI-PMH service, which includes GBIF registry data only. rgbif functions: gbif_oai_get_records(), gbif_oai_identify(), gbif_oai_list_identifiers(), gbif_oai_list_metadataformats(), gbif_oai_list_records(), gbif_oai_list_sets()

the search and download APIs * rgbif functions: occ_count(), occ_data(), occ_download(), occ_download_prep(), occ_download_queue(), occ_download_cancel(), occ_download_cancel_staged(), occ_download_get(), occ_download_import(), occ_download_list(), occ_download_meta(), occ_download_datasets(), occ_download_dataset_activity(), occ_get(), occ_issues(), occ_issues_lookup(), occ_metadata(), occ_search()

  • maps (https://www.gbif.org/developer/maps) - Map API
    • rgbif functions: map_fetch()
    • Note: we used to have a function gbifmap() that used ggplot2 to plot data from the
    occurrence API, but it's been removed - see package mapr

Installation

install.packages("rgbif")

Alternatively, install development version

install.packages("devtools")
devtools::install_github("ropensci/rgbif")
library("rgbif")

Note: Windows users have to first install Rtools to use devtools

Mac Users: (in case of errors)

Terminal:

Install gdal : https://github.com/edzer/sfr/blob/master/README.md#macos

brew install openssl

in R:

install.packages('openssl')
install.packages('rgeos')
install.packages('rgbif')

Search for occurrence data

occ_search(scientificName = "Ursus americanus", limit = 50)
#> Records found [12339] 
#> Records returned [50] 
#> No. unique hierarchies [1] 
#> No. media records [50] 
#> No. facets [0] 
#> Args [limit=50, offset=0, scientificName=Ursus americanus, fields=all] 
#> # A tibble: 50 x 74
#>    key   scientificName decimalLatitude decimalLongitude issues datasetKey
#>    <chr> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#>  1 1990… Ursus america…            44.9            -62.7 cdrou… 50c9509d-…
#>  2 1990… Ursus america…            40.9           -121.  gass84 50c9509d-…
#>  3 2006… Ursus america…            31.5           -110.  cdrou… 50c9509d-…
#>  4 1986… Ursus america…            30.1           -103.  cdrou… 50c9509d-…
#>  5 1990… Ursus america…            45.4            -93.2 cdrou… 50c9509d-…
#>  6 1990… Ursus america…            35.7            -76.6 cdrou… 50c9509d-…
#>  7 1990… Ursus america…            33.1            -91.9 cdrou… 50c9509d-…
#>  8 1990… Ursus america…            35.6            -82.9 cdrou… 50c9509d-…
#>  9 1990… Ursus america…            29.2            -81.8 cdrou… 50c9509d-…
#> 10 1990… Ursus america…            45.4            -93.1 cdrou… 50c9509d-…
#> # … with 40 more rows, and 68 more variables: publishingOrgKey <chr>,
#> #   networkKeys <chr>, installationKey <chr>, publishingCountry <chr>,
#> #   protocol <chr>, lastCrawled <chr>, lastParsed <chr>, crawlId <int>,
#> #   extensions <chr>, basisOfRecord <chr>, taxonKey <int>,
#> #   kingdomKey <int>, phylumKey <int>, classKey <int>, orderKey <int>,
#> #   familyKey <int>, genusKey <int>, speciesKey <int>,
#> #   acceptedTaxonKey <int>, acceptedScientificName <chr>, kingdom <chr>,
#> #   phylum <chr>, order <chr>, family <chr>, genus <chr>, species <chr>,
#> #   genericName <chr>, specificEpithet <chr>, taxonRank <chr>,
#> #   taxonomicStatus <chr>, dateIdentified <chr>,
#> #   coordinateUncertaintyInMeters <dbl>, stateProvince <chr>, year <int>,
#> #   month <int>, day <int>, eventDate <chr>, modified <chr>,
#> #   lastInterpreted <chr>, references <chr>, license <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>, name <chr>, infraspecificEpithet <chr>,
#> #   informationWithheld <chr>, occurrenceRemarks <chr>

Or you can get the taxon key first with name_backbone(). Here, we select to only return the occurrence data.

key <- name_backbone(name='Helianthus annuus', kingdom='plants')$speciesKey
occ_search(taxonKey=key, limit=20)
#> Records found [44157] 
#> Records returned [20] 
#> No. unique hierarchies [1] 
#> No. media records [18] 
#> No. facets [0] 
#> Args [limit=20, offset=0, taxonKey=9206251, fields=all] 
#> # A tibble: 20 x 86
#>    key   scientificName decimalLatitude decimalLongitude issues datasetKey
#>    <chr> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#>  1 1993… Helianthus an…            33.4          -118.   cdrou… 50c9509d-…
#>  2 1986… Helianthus an…            33.8          -118.   cdrou… 50c9509d-…
#>  3 1990… Helianthus an…            53.9            10.9  cdrou… 6ac3f774-…
#>  4 1990… Helianthus an…            52.6            10.1  cdrou… 6ac3f774-…
#>  5 2235… Helianthus an…            51.2             4.45 ""     7f5e4129-…
#>  6 1993… Helianthus an…            34.0          -117.   cdrou… 50c9509d-…
#>  7 2236… Helianthus an…            26.2           -98.2  cdrou… 50c9509d-…
#>  8 1986… Helianthus an…            27.7           -97.3  cdrou… 50c9509d-…
#>  9 1990… Helianthus an…            26.2           -98.2  cdrou… 50c9509d-…
#> 10 2006… Helianthus an…            27.7           -97.3  cdrou… 50c9509d-…
#> 11 2005… Helianthus an…            27.5           -99.5  cdrou… 50c9509d-…
#> 12 2013… Helianthus an…            25.5          -108.   cdrou… 50c9509d-…
#> 13 1993… Helianthus an…            29.8           -95.2  cdrou… 50c9509d-…
#> 14 2012… Helianthus an…            33.5          -118.   cdrou… 50c9509d-…
#> 15 2006… Helianthus an…            34.6            33.0  cdrou… 50c9509d-…
#> 16 2005… Helianthus an…            31.6          -106.   cdrou… 50c9509d-…
#> 17 2012… Helianthus an…            25.7          -100.   cdrou… 50c9509d-…
#> 18 2005… Helianthus an…            31.5           -97.1  cdrou… 50c9509d-…
#> 19 2012… Helianthus an…            49.3             8.55 gass84 50c9509d-…
#> 20 2013… Helianthus an…            28.6           -98.2  cdrou… 50c9509d-…
#> # … with 80 more variables: publishingOrgKey <chr>, networkKeys <chr>,
#> #   installationKey <chr>, publishingCountry <chr>, protocol <chr>,
#> #   lastCrawled <chr>, lastParsed <chr>, crawlId <int>, extensions <chr>,
#> #   basisOfRecord <chr>, taxonKey <int>, kingdomKey <int>,
#> #   phylumKey <int>, classKey <int>, orderKey <int>, familyKey <int>,
#> #   genusKey <int>, speciesKey <int>, acceptedTaxonKey <int>,
#> #   acceptedScientificName <chr>, kingdom <chr>, phylum <chr>,
#> #   order <chr>, family <chr>, genus <chr>, species <chr>,
#> #   genericName <chr>, specificEpithet <chr>, taxonRank <chr>,
#> #   taxonomicStatus <chr>, dateIdentified <chr>,
#> #   coordinateUncertaintyInMeters <dbl>, stateProvince <chr>, year <int>,
#> #   month <int>, day <int>, eventDate <chr>, modified <chr>,
#> #   lastInterpreted <chr>, references <chr>, license <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>,
#> #   occurrenceRemarks <chr>, identificationID <chr>, name <chr>,
#> #   locality <chr>, individualCount <int>, continent <chr>,
#> #   informationWithheld <chr>, nomenclaturalCode <chr>,
#> #   municipality <chr>, identificationVerificationStatus <chr>,
#> #   language <chr>, type <chr>, vernacularName <chr>,
#> #   samplingProtocol <chr>, datasetID <chr>, accessRights <chr>,
#> #   reproductiveCondition <chr>

Search for many species

Get the keys first with name_backbone(), then pass to occ_search()

splist <- c('Accipiter erythronemius', 'Junco hyemalis', 'Aix sponsa')
keys <- sapply(splist, function(x) name_backbone(name=x)$speciesKey, USE.NAMES=FALSE)
occ_search(taxonKey=keys, limit=5, hasCoordinate=TRUE)
#> Occ. found [2480598 (20), 9362842 (5522131), 2498387 (1823909)] 
#> Occ. returned [2480598 (5), 9362842 (5), 2498387 (5)] 
#> No. unique hierarchies [2480598 (1), 9362842 (1), 2498387 (1)] 
#> No. media records [2480598 (3), 9362842 (5), 2498387 (5)] 
#> No. facets [2480598 (0), 9362842 (0), 2498387 (0)] 
#> Args [hasCoordinate=TRUE, limit=5, offset=0,
#>      taxonKey=2480598,9362842,2498387, fields=all] 
#> 3 requests; First 10 rows of data from 2480598
#> 
#> # A tibble: 5 x 91
#>   key   scientificName decimalLatitude decimalLongitude issues datasetKey
#>   <chr> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#> 1 1978… Accipiter ery…          -22.4             -42.9 ""     b1047888-…
#> 2 1001… Accipiter ery…          -27.6             -58.7 cudc,… ad43e954-…
#> 3 1001… Accipiter ery…          -27.9             -59.1 cudc,… ad43e954-…
#> 4 1934… Accipiter ery…          -24.3             -48.4 cdrou… b1047888-…
#> 5 6862… Accipiter ery…            5.27            -60.7 cdrou… e635240a-…
#> # … with 85 more variables: publishingOrgKey <chr>, networkKeys <chr>,
#> #   installationKey <chr>, publishingCountry <chr>, protocol <chr>,
#> #   lastCrawled <chr>, lastParsed <chr>, crawlId <int>, extensions <chr>,
#> #   basisOfRecord <chr>, taxonKey <int>, kingdomKey <int>,
#> #   phylumKey <int>, classKey <int>, orderKey <int>, familyKey <int>,
#> #   genusKey <int>, speciesKey <int>, acceptedTaxonKey <int>,
#> #   acceptedScientificName <chr>, kingdom <chr>, phylum <chr>,
#> #   order <chr>, family <chr>, genus <chr>, species <chr>,
#> #   genericName <chr>, specificEpithet <chr>, taxonRank <chr>,
#> #   taxonomicStatus <chr>, year <int>, month <int>, day <int>,
#> #   eventDate <chr>, lastInterpreted <chr>, references <chr>,
#> #   license <chr>, identifiers <chr>, facts <chr>, relations <chr>,
#> #   geodeticDatum <chr>, class <chr>, countryCode <chr>, country <chr>,
#> #   rightsHolder <chr>, identifier <chr>, verbatimEventDate <chr>,
#> #   nomenclaturalCode <chr>, locality <chr>, gbifID <chr>,
#> #   collectionCode <chr>, occurrenceID <chr>, recordedBy <chr>,
#> #   catalogNumber <chr>, vernacularName <chr>, fieldNotes <chr>,
#> #   eventTime <chr>, verbatimElevation <chr>, behavior <chr>,
#> #   higherClassification <chr>, name <chr>, modified <chr>, created <chr>,
#> #   associatedSequences <chr>, taxonID <chr>, sex <chr>,
#> #   establishmentMeans <chr>, continent <chr>, institutionID <chr>,
#> #   dynamicProperties <chr>, fieldNumber <chr>, language <chr>,
#> #   type <chr>, preparations <chr>, occurrenceStatus <chr>,
#> #   institutionCode <chr>, higherGeography <chr>,
#> #   georeferenceVerificationStatus <chr>, endDayOfYear <chr>,
#> #   datasetName <chr>, verbatimLocality <chr>, otherCatalogNumbers <chr>,
#> #   startDayOfYear <chr>, accessRights <chr>, collectionID <chr>

Maps

We've removed gbifmap() which helped users plot data from functions occ_search()/occ_data() - instead we strongly recommend using our other package mapr.

As of rgibf v1, we have integration for GBIF's mapping API, which lets you get raster images of occurrences of taxa of interest. For example:

x <- map_fetch(taxonKey = 3118771, year = 2010)
x
#> class       : RasterLayer 
#> dimensions  : 512, 512, 262144  (nrow, ncol, ncell)
#> resolution  : 0.703125, 0.3515625  (x, y)
#> extent      : -180, 180, -90, 90  (xmin, xmax, ymin, ymax)
#> coord. ref. : +init=epsg:4326 +proj=longlat +datum=WGS84 +no_defs +ellps=WGS84 +towgs84=0,0,0 
#> data source : in memory
#> names       : layer 
#> values      : 0, 1  (min, max)
library(raster)
plot(x, axes = FALSE, box = FALSE)

Screencast

Contributors

Collected via GitHub Issues, this list honors all contributors in alphabetical order. Code contributors are in bold.

adamdsmith - AgustinCamacho - AlexPeap - andzandz11 - AugustT - benmarwick - cathynewman - cboettig - coyotree - damianooldoni - dandaman - djokester - dlebauer - dmcglinn - dnoesgaard - DupontCai - elgabbas - fxi - ghost - gkburada - hadley - JanLauGe - jarioksa - jhpoelen - jkmccarthy - johnbaums - jwhalennds - karthik - kgturner - Kim1801 - ljuliusson - luisDVA - martinpfannkuchen - MattBlissett - maxhenschell - Pakillo - peterdesmet - PhillRob - poldham - qgroom - raymondben - rossmounce - sacrevert - sckott - scottsfarley93 - SriramRamesh - stevenpbachman - stevensotelo - TomaszSuchan - vandit15 - vervis - vijaybarve - willgearty - zixuan75

Meta

  • Please report any issues or bugs.
  • License: MIT
  • Get citation information for rgbif in R doing citation(package = 'rgbif')
  • Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

This package is part of a richer suite called spocc - Species Occurrence Data, along with several other packages, that provide access to occurrence records from multiple databases.

Copy Link

Version

Install

install.packages('rgbif')

Monthly Downloads

8,524

Version

1.3.0

License

MIT + file LICENSE

Issues

33

Pull Requests

0

Stars

155

Forks

50

Maintainer

Scott Chamberlain

Last Published

May 8th, 2019

Functions in rgbif (1.3.0)

gbif_citation

Get citation for datasets used
occ_download_dataset_activity

Lists the downloads activity of a dataset
occ_download_datasets

List datasets for a download
downloads

Downloads interface
elevation

Get elevation for lat/long points from a data.frame or list of points.
gbifmap_list

Make a simple map to visualize GBIF point data.
get_credentials

Get Github credentials from use in console
parsenames

Parse taxon names using the GBIF name parser.
%>%

Pipe operator
datasets

Search for datasets and dataset metadata.
typestatus

Type status options for GBIF searching
gbif_issues

Table of GBIF issues, with codes used in data output, full issue name, and descriptions.
gbif_names

View highlighted terms in name results from GBIF.
wkt_parse

parse wkt into smaller bits
gbifmap

Get Github credentials from use in console
name_usage

Lookup details for specific names in all taxonomies in GBIF.
name_suggest

A quick and simple autocomplete service that returns up to 20 name usages by doing prefix matching against the scientific name. Results are ordered by relevance.
gbifmap_dens

Make a simple map to visualize GBIF data density data
occ_download

Spin up a download request for GBIF occurrence data.
gbif_oai

GBIF registry data via OAI-PMH
density_spplist

The density web service provides access to records showing the density of occurrence records from the GBIF Network by one-degree cell.
densitylist

The density web service provides access to records showing the density of occurrence records from the GBIF Network by one-degree cell.
gbif_photos

View photos from GBIF.
occ_metadata

Search for catalog numbers, collection codes, collector names, and institution codes.
isocodes

Table of country two character ISO codes, and GBIF names
occ_download_cancel

Cancel a download creation process.
occ_search

Search for GBIF occurrences
occurrencelist

Occurrencelist searches for taxon concept records matching a range of filters.
many-values

Many value inputs to some parameters
name_backbone

Lookup names in the GBIF backbone taxonomy.
map_fetch

Fetch aggregated density maps of GBIF occurrences
occurrencelist_all

Occurrencelist_all carries out an occurrencelist query for a single name and all its name variants according to GBIF's name matching.
suggestfields

Fields available in gbif_suggest function
occurrencedensity

Returns summary counts of occurrence records by one-degree cell for a single taxon, country, dataset, data publisher or data network.
taxoncount

Search by taxon to retrieve number of records in GBIF.
gist

Post a file as a Github gist
occurrenceget

Get individual records for a given occurrence record.
installations

Installations metadata.
occ_count

Get number of occurrence records.
rgb_country_codes

Look up 2 character ISO country codes
gbifdata

Get data.frame from occurrencelist, occurrencelist_many, or densitylist.
rgbif-defunct

Defunct functions in rgbif
enumeration

Enumerations.
gbif_bbox2wkt

Convert a bounding box to a Well Known Text polygon, and a WKT to a bounding box
taxrank

Get the possible values to be used for (taxonomic) rank arguments in GBIF API methods.
togeojson

Convert spatial data files to GeoJSON from various formats.
networks

Networks metadata.
nodes

Nodes metadata.
occ_data

Search for GBIF occurrences - simplified for speed
occ_download_get

Get a download from GBIF.
name_issues

Table of GBIF name usage issues, with codes used in data output, full issue name, and descriptions.
occ_download_list

Lists the downloads created by a user.
occ_download_meta

Retrieves the occurrence download metadata by its unique key.
occ_download_import

Import a downloaded file from GBIF.
occ_issues

Parse and examine further GBIF issues on a dataset
occ_issues_lookup

Lookup occurrence issue definitions and short codes
occ_spellcheck

Spell check search term for occurrence searches
occurrencelist_many

occurrencelist_many is the same as occurrencelist, but takes in a vector of species names.
name_lookup

Lookup names in all taxonomies in GBIF.
occ_download_queue

Download requests in a queue
organizations

Organizations metadata.
occ_facet

Facet GBIF occurrences
rgbif-package

Interface to the Global Biodiversity Information Facility API.
occ_fields

Vector of fields in the output for the function occ_search()
stylegeojson

Style a data.frame prior to converting to geojson.
occurrencecount

Counts taxon concept records matching a range of filters.
occ_get

Get data for specific GBIF occurrences.
taxonget

Get taxonomic information on a specific taxon or taxa in GBIF by their taxon concept keys.
taxonsearch

Search for taxa in GBIF.
providers

Get data providers and their unique keys.
resources

Get data resources and their unique keys.
count_facet

Facetted count occurrence search.
create_gist

Function that takes a list of files and creates payload for API
DownReq

Download request
GbifQueue

GBIF download queue
blanktheme

Custom ggplot2 theme
check_wkt

Check input WKT
dataset_metrics

Get details on a GBIF dataset.
dataset_search

Search datasets in GBIF.
dataset_suggest

Suggest datasets in GBIF.