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 [12043] 
#> Records returned [50] 
#> No. unique hierarchies [1] 
#> No. media records [47] 
#> No. facets [0] 
#> Args [limit=50, offset=0, scientificName=Ursus americanus, fields=all] 
#> # A tibble: 50 x 74
#>       key scientificName decimalLatitude decimalLongitude issues datasetKey
#>     <int> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#>  1 1.99e9 Ursus america…            29.2            -81.8 cdrou… 50c9509d-…
#>  2 1.99e9 Ursus america…            45.3            -76.8 cdrou… 50c9509d-…
#>  3 1.99e9 Ursus america…            47.7           -122.  cdrou… 50c9509d-…
#>  4 1.99e9 Ursus america…            32.6           -109.  cdrou… 50c9509d-…
#>  5 1.99e9 Ursus america…            33.1            -91.9 cdrou… 50c9509d-…
#>  6 1.99e9 Ursus america…            27.7            -81.5 gass84 50c9509d-…
#>  7 1.99e9 Ursus america…            30.1           -103.  cdrou… 50c9509d-…
#>  8 1.99e9 Ursus america…            39.4           -120.  cdrou… 50c9509d-…
#>  9 1.99e9 Ursus america…            35.7            -76.6 cdrou… 50c9509d-…
#> 10 1.99e9 Ursus america…            33.1            -91.9 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>, 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>, catalogNumber <chr>,
#> #   recordedBy <chr>, http...unknown.org.occurrenceDetails <chr>,
#> #   institutionCode <chr>, rights <chr>, eventTime <chr>,
#> #   identificationID <chr>, name <chr>,
#> #   coordinateUncertaintyInMeters <dbl>, occurrenceRemarks <chr>,
#> #   infraspecificEpithet <chr>, informationWithheld <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 [43758] 
#> Records returned [20] 
#> No. unique hierarchies [1] 
#> No. media records [16] 
#> No. facets [0] 
#> Args [limit=20, offset=0, taxonKey=9206251, fields=all] 
#> # A tibble: 20 x 91
#>       key scientificName decimalLatitude decimalLongitude issues datasetKey
#>     <int> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#>  1 1.99e9 Helianthus an…            34.0           -117.  cdrou… 50c9509d-…
#>  2 1.99e9 Helianthus an…            33.4           -118.  cdrou… 50c9509d-…
#>  3 1.99e9 Helianthus an…            33.8           -118.  cdrou… 50c9509d-…
#>  4 1.99e9 Helianthus an…            53.9             10.9 cdrou… 6ac3f774-…
#>  5 1.99e9 Helianthus an…            27.7            -97.3 cdrou… 50c9509d-…
#>  6 1.99e9 Helianthus an…            52.6             10.1 cdrou… 6ac3f774-…
#>  7 1.99e9 Helianthus an…            26.2            -98.2 cdrou… 50c9509d-…
#>  8 2.01e9 Helianthus an…            31.5            -97.1 cdrou… 50c9509d-…
#>  9 1.99e9 Helianthus an…            29.8            -95.2 cdrou… 50c9509d-…
#> 10 2.01e9 Helianthus an…            31.6           -106.  cdrou… 50c9509d-…
#> 11 2.01e9 Helianthus an…            27.5            -99.5 cdrou… 50c9509d-…
#> 12 1.95e9 Helianthus an…           -37.8            175.  gass84 50c9509d-…
#> 13 1.82e9 Helianthus an…            59.8             17.5 gass84 38b4c89f-…
#> 14 1.95e9 Helianthus an…           -37.8            175.  gass84 50c9509d-…
#> 15 1.82e9 Helianthus an…            56.6             16.4 cdrou… 38b4c89f-…
#> 16 1.84e9 Helianthus an…            34.1           -116.  gass84 50c9509d-…
#> 17 1.82e9 Helianthus an…            56.6             16.6 cdrou… 38b4c89f-…
#> 18 1.81e9 Helianthus an…            25.7           -100.  cdrou… 50c9509d-…
#> 19 1.81e9 Helianthus an…            25.6           -100.  cdrou… 50c9509d-…
#> 20 1.84e9 Helianthus an…            33.9           -117.  cdrou… 50c9509d-…
#> # … 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>, dateIdentified <chr>, 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>, catalogNumber <chr>,
#> #   recordedBy <chr>, http...unknown.org.occurrenceDetails <chr>,
#> #   institutionCode <chr>, rights <chr>, eventTime <chr>,
#> #   identificationID <chr>, name <chr>,
#> #   coordinateUncertaintyInMeters <dbl>, occurrenceRemarks <chr>,
#> #   locality <chr>, individualCount <int>, continent <chr>, county <chr>,
#> #   municipality <chr>, identificationVerificationStatus <chr>,
#> #   language <chr>, type <chr>, occurrenceStatus <chr>,
#> #   vernacularName <chr>, taxonConceptID <chr>, informationWithheld <chr>,
#> #   endDayOfYear <chr>, startDayOfYear <chr>, datasetID <chr>,
#> #   accessRights <chr>, higherClassification <chr>,
#> #   identificationRemarks <chr>, habitat <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 (3806201), 2498387 (1246518)] 
#> 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
#>    <int> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#> 1 1.98e9 Accipiter ery…          -22.4             -42.9 ""     b1047888-…
#> 2 1.00e9 Accipiter ery…          -27.6             -58.7 cudc,… ad43e954-…
#> 3 1.00e9 Accipiter ery…          -27.9             -59.1 cudc,… ad43e954-…
#> 4 1.93e9 Accipiter ery…          -24.3             -48.4 cdrou… b1047888-…
#> 5 6.86e8 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>, nomenclaturalCode <chr>,
#> #   verbatimEventDate <chr>, locality <chr>, gbifID <chr>,
#> #   collectionCode <chr>, occurrenceID <chr>, catalogNumber <chr>,
#> #   recordedBy <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>, endDayOfYear <chr>,
#> #   georeferenceVerificationStatus <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 - steven2249 - 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

7,110

Version

1.2.0

License

MIT + file LICENSE

Issues

37

Pull Requests

1

Stars

163

Forks

51

Maintainer

Scott Chamberlain

Last Published

February 26th, 2019

Functions in rgbif (1.2.0)

downloads

Downloads interface
enumeration

Enumerations.
gbif_oai

GBIF registry data via OAI-PMH
name_issues

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

View highlighted terms in name results from GBIF.
dataset_search

Search datasets in GBIF.
installations

Installations metadata.
name_lookup

Lookup names in all taxonomies in GBIF.
occurrencedensity

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

Post a file as a Github gist
gbifmap_list

Make a simple map to visualize GBIF point data.
gbif_bbox2wkt

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

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

Get individual records for a given occurrence record.
occ_download_queue

Download requests in a queue
occ_facet

Facet GBIF occurrences
gbif_photos

View photos from GBIF.
gbif_issues

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

Get citation for datasets used
gbifdata

Get data.frame from occurrencelist, occurrencelist_many, or densitylist.
get_credentials

Get Github credentials from use in console
rgb_country_codes

Look up 2 character ISO country codes
occ_count

Get number of occurrence records.
networks

Networks metadata.
nodes

Nodes metadata.
occ_download_meta

Retrieves the occurrence download metadata by its unique key.
occ_fields

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

Lists the downloads created by a user.
occ_get

Get data for specific GBIF occurrences.
occ_data

Search for GBIF occurrences - simplified for speed
rgbif-defunct

Defunct functions in rgbif
occ_metadata

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

Lists the downloads activity of a dataset
densitylist

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

List datasets for a download
parsenames

Parse taxon names using the GBIF name parser.
gbifmap

Get Github credentials from use in console
%>%

Pipe operator
occ_search

Search for GBIF occurrences
suggestfields

Fields available in gbif_suggest function
occ_issues

Parse and examine further GBIF issues on a dataset
occ_issues_lookup

Lookup occurrence issue definitions and short codes
occurrencelist

Occurrencelist searches for taxon concept records matching a range of filters.
elevation

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

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

Get data providers and their unique keys.
resources

Get data resources and their unique keys.
rgbif-package

Interface to the Global Biodiversity Information Facility API.
gbifmap_dens

Make a simple map to visualize GBIF data density data
typestatus

Type status options for GBIF searching
stylegeojson

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

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

parse wkt into smaller bits
many-values

Many value inputs to some parameters
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.
taxoncount

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

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

Fetch aggregated density maps of GBIF occurrences
occ_download_get

Get a download from GBIF.
name_backbone

Lookup names in the GBIF backbone taxonomy.
occ_download

Spin up a download request for GBIF occurrence data.
occ_download_import

Import a downloaded file from GBIF.
occ_download_cancel

Cancel a download creation process.
occ_spellcheck

Spell check search term for occurrence searches
occurrencecount

Counts taxon concept records matching a range of filters.
taxonget

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

Search for taxa in GBIF.
occurrencelist_many

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

Organizations metadata.
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.
blanktheme

Custom ggplot2 theme
check_wkt

Check input WKT
count_facet

Facetted count occurrence search.
create_gist

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

Get details on a GBIF dataset.
dataset_suggest

Suggest datasets in GBIF.
datasets

Search for datasets and dataset metadata.
DownReq

Download request
GbifQueue

GBIF download queue