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.

Tutorials:

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_cancel(), occ_download_cancel_staged(), occ_download_get(), occ_download_import(), occ_download_list(), occ_download_meta(), occ_get(), occ_issues(), occ_issues_lookup(), occ_metadata(), occ_search()

The GBIF maps API (http://www.gbif.org/developer/maps) is not implemented in rgbif, and are meant more for intergration with web based maps.

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

Search for occurrence data

occ_search(scientificName = "Ursus americanus", limit = 50)
#> Records found [8196] 
#> Records returned [50] 
#> No. unique hierarchies [1] 
#> No. media records [44] 
#> No. facets [0] 
#> Args [scientificName=Ursus americanus, limit=50, offset=0, fields=all] 
#> # A tibble: 50 × 68
#>                name        key decimalLatitude decimalLongitude
#>               <chr>      <int>           <dbl>            <dbl>
#> 1  Ursus americanus 1249277297        35.76789        -75.80894
#> 2  Ursus americanus 1229610216        44.06086        -71.92712
#> 3  Ursus americanus 1253300445        44.65481        -72.67270
#> 4  Ursus americanus 1229610234        44.06062        -71.92692
#> 5  Ursus americanus 1253314877        49.25782       -122.82786
#> 6  Ursus americanus 1272078411        44.41793        -72.70709
#> 7  Ursus americanus 1249296297        39.08590       -105.24586
#> 8  Ursus americanus 1249284297        43.68723        -72.32891
#> 9  Ursus americanus 1257415362        44.32746        -72.41007
#> 10 Ursus americanus 1253317181        43.64214        -72.52494
#> # ... with 40 more rows, and 64 more variables: issues <chr>,
#> #   datasetKey <chr>, publishingOrgKey <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>,
#> #   scientificName <chr>, kingdom <chr>, phylum <chr>, order <chr>,
#> #   family <chr>, genus <chr>, species <chr>, genericName <chr>,
#> #   specificEpithet <chr>, infraspecificEpithet <chr>, taxonRank <chr>,
#> #   dateIdentified <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>, collectionCode <chr>,
#> #   verbatimLocality <chr>, gbifID <chr>, occurrenceID <chr>,
#> #   taxonID <chr>, catalogNumber <chr>, recordedBy <chr>,
#> #   http...unknown.org.occurrenceDetails <chr>, institutionCode <chr>,
#> #   rights <chr>, identificationID <chr>, eventTime <chr>,
#> #   occurrenceRemarks <chr>, coordinateUncertaintyInMeters <dbl>,
#> #   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 [20539] 
#> Records returned [20] 
#> No. unique hierarchies [1] 
#> No. media records [16] 
#> No. facets [0] 
#> Args [taxonKey=3119195, limit=20, offset=0, fields=all] 
#> # A tibble: 20 × 67
#>                 name        key decimalLatitude decimalLongitude
#>                <chr>      <int>           <dbl>            <dbl>
#> 1  Helianthus annuus 1249279611        34.04810       -117.79884
#> 2  Helianthus annuus 1315048347        34.04377       -116.94136
#> 3  Helianthus annuus 1253308332        29.67463        -95.44804
#> 4  Helianthus annuus 1249286909        32.58747        -97.10081
#> 5  Helianthus annuus 1305118889        18.40386        -66.04487
#> 6  Helianthus annuus 1262375813        29.82586        -95.45604
#> 7  Helianthus annuus 1262379231        34.04911       -117.80066
#> 8  Helianthus annuus 1262385911        32.78328        -96.70352
#> 9  Helianthus annuus 1265544678        32.58747        -97.10081
#> 10 Helianthus annuus 1270045172        33.92958       -117.37322
#> 11 Helianthus annuus 1265895094        42.87784       -112.43226
#> 12 Helianthus annuus 1265553900        34.12932       -118.20648
#> 13 Helianthus annuus 1269543851        29.50991        -94.50006
#> 14 Helianthus annuus 1265899487        19.45194        -96.95945
#> 15 Helianthus annuus 1265562148        29.47895        -98.51160
#> 16 Helianthus annuus 1305119137        11.86735        -83.93555
#> 17 Helianthus annuus 1265590989        34.19005       -117.31644
#> 18 Helianthus annuus 1265590198        25.76265       -100.25513
#> 19 Helianthus annuus 1305119139        11.86735        -83.93555
#> 20 Helianthus annuus 1315048128        34.03212       -117.47091
#> # ... with 63 more variables: issues <chr>, datasetKey <chr>,
#> #   publishingOrgKey <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>, 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>, license <chr>, identifiers <chr>, facts <chr>,
#> #   relations <chr>, geodeticDatum <chr>, class <chr>, countryCode <chr>,
#> #   country <chr>, rightsHolder <chr>, identifier <chr>,
#> #   verbatimEventDate <chr>, datasetName <chr>, collectionCode <chr>,
#> #   verbatimLocality <chr>, gbifID <chr>, occurrenceID <chr>,
#> #   taxonID <chr>, catalogNumber <chr>, recordedBy <chr>,
#> #   http...unknown.org.occurrenceDetails <chr>, institutionCode <chr>,
#> #   rights <chr>, eventTime <chr>, identificationID <chr>,
#> #   coordinateUncertaintyInMeters <dbl>, occurrenceRemarks <chr>,
#> #   informationWithheld <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 (22), 2492010 (2453480), 2498387 (772689)] 
#> Occ. returned [2480598 (5), 2492010 (5), 2498387 (5)] 
#> No. unique hierarchies [2480598 (1), 2492010 (1), 2498387 (1)] 
#> No. media records [2480598 (1), 2492010 (4), 2498387 (5)] 
#> No. facets [] 
#> Args [taxonKey=2480598,2492010,2498387, hasCoordinate=TRUE, limit=5,
#>      offset=0, fields=all] 
#> First 10 rows of data from 2480598
#> 
#> # A tibble: 5 × 82
#>                      name        key decimalLatitude decimalLongitude
#>                     <chr>      <int>           <dbl>            <dbl>
#> 1 Accipiter erythronemius  920169861       -20.55244        -56.64104
#> 2 Accipiter erythronemius  920184036       -20.76029        -56.71314
#> 3 Accipiter erythronemius 1001096527       -27.58000        -58.66000
#> 4 Accipiter erythronemius 1001096518       -27.92000        -59.14000
#> 5 Accipiter erythronemius  686297260         5.26667        -60.73333
#> # ... with 78 more variables: issues <chr>, datasetKey <chr>,
#> #   publishingOrgKey <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>, scientificName <chr>, kingdom <chr>,
#> #   phylum <chr>, order <chr>, family <chr>, genus <chr>, species <chr>,
#> #   genericName <chr>, specificEpithet <chr>, taxonRank <chr>,
#> #   coordinateUncertaintyInMeters <dbl>, year <int>, month <int>,
#> #   day <int>, eventDate <chr>, lastInterpreted <chr>, license <chr>,
#> #   identifiers <chr>, facts <chr>, relations <chr>, geodeticDatum <chr>,
#> #   class <chr>, countryCode <chr>, country <chr>, recordedBy <chr>,
#> #   catalogNumber <chr>, institutionCode <chr>, locality <chr>,
#> #   collectionCode <chr>, gbifID <chr>, modified <chr>, identifier <chr>,
#> #   created <chr>, occurrenceID <chr>, associatedSequences <chr>,
#> #   higherClassification <chr>, taxonID <chr>, sex <chr>,
#> #   establishmentMeans <chr>, continent <chr>, references <chr>,
#> #   institutionID <chr>, dynamicProperties <chr>, fieldNumber <chr>,
#> #   language <chr>, type <chr>, preparations <chr>,
#> #   occurrenceStatus <chr>, rights <chr>, higherGeography <chr>,
#> #   nomenclaturalCode <chr>, verbatimEventDate <chr>, endDayOfYear <chr>,
#> #   georeferenceVerificationStatus <chr>, datasetName <chr>,
#> #   verbatimLocality <chr>, otherCatalogNumbers <chr>,
#> #   startDayOfYear <chr>, accessRights <chr>, collectionID <chr>

Maps

Make a simple map of species occurrences.

splist <- c('Cyanocitta stelleri', 'Junco hyemalis', 'Aix sponsa')
keys <- sapply(splist, function(x) name_backbone(name=x)$speciesKey, USE.NAMES=FALSE)
dat <- occ_search(taxonKey=keys, limit=100, return='data', hasCoordinate=TRUE)
library('plyr')
datdf <- ldply(dat)
gbifmap(datdf)

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

6,823

Version

0.9.6

License

MIT + file LICENSE

Issues

37

Pull Requests

1

Stars

163

Forks

51

Maintainer

Scott Chamberlain

Last Published

December 6th, 2016

Functions in rgbif (0.9.6)

datasets

Search for datasets and dataset metadata.
occ_search

Search for GBIF occurrences
rgbif-defunct

Defunct functions in rgbif
rgbif-package

Interface to the Global Biodiversity Information Facility API.
togeojson

Convert spatial data files to GeoJSON from various formats.
type_sum

Type summary
dataset_suggest

Suggest datasets in GBIF.
downloads

Downloads interface
elevation

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

Search for GBIF occurrences - simplified for speed
occ_download_cancel

Cancel a download cretion process.
occ_metadata

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

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

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

View highlighted terms in name results from GBIF.
gbif_photos

View photos from GBIF.
gbifdata

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

Make a map to visualize GBIF occurrence data.
get_credentials

Get Github credentials from use in console
occ_download_meta

Retrieves the occurrence download metadata by its unique key.
occ_download_list

Lists the downloads created by a user.
occ_issues_lookup

Lookup occurrence issue definitions and short codes
occ_issues

Parse and examine further GBIF issues on a dataset.
occurrencedensity

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

Get individual records for a given occurrence record.
dataset_metrics

Get details on a GBIF dataset.
gbif_citation

Get citation for datasets used
dataset_search

Search datasets in GBIF.
gbif_issues

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

Enumerations.
gbif_bbox2wkt

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

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

Lookup names in the GBIF backbone taxonomy.
networks

Networks metadata.
name_usage

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

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

Fields available in gbif_suggest function
gist

Post a file as a Github gist
installations

Installations metadata.
occurrencecount

Counts taxon concept records matching a range of filters.
occ_spellcheck

Spell check search term for occurrence searches
occurrencelist_all

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

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

Search for taxa in GBIF.
taxrank

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

GBIF registry data via OAI-PMH
occ_download_get

Get a download from GBIF.
occ_download_import

Import a downloaded file from GBIF.
occ_download

Spin up a download request for GBIF occurrence data.
providers

Get data providers and their unique keys.
read_wkt

Check input WKT
occ_facet

Facet GBIF occurrences
taxoncount

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

Facetted count occurrence search.
create_gist

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

Lookup 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.
organizations

Organizations metadata.
occurrencelist

Occurrencelist searches for 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.
typestatus

Type status options for GBIF searching
wkt_parse

parse wkt into smaller bits
blanktheme

Custom ggplot2 theme
check_wkt

Check input WKT
nodes

Nodes metadata.
occ_count

Get number of occurrence records.
occ_fields

Vector of fields in the output for the function occ_search
occ_get

Get data for specific GBIF occurrences.
parsenames

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

Pipe operator
gbifmap_dens

Make a simple map to visualize GBIF data density data
gbifmap_list

Make a simple map to visualize GBIF point data.
resources

Get data resources and their unique keys.
rgb_country_codes

Look up 2 character ISO country codes