rgbif v1.4.0

0

Monthly downloads

0th

Percentile

Interface to the Global 'Biodiversity' Information Facility API

A programmatic interface to the Web Service methods provided by the Global Biodiversity Information Facility ('GBIF'; <https://www.gbif.org/developer/summary>). 'GBIF' is a database of species occurrence records from sources all over the globe. 'rgbif' includes functions for searching for taxonomic names, retrieving information on data providers, getting species occurrence records, getting counts of occurrence records, and using the 'GBIF' tile map service to make 'rasters' summarizing huge amounts of data.

Readme

rgbif

Project Status: Active – The project has reached a stable, usable state and is being actively developed. cran checks Build Status codecov.io rstudio mirror downloads cran version DOI

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:

  • registry (https://www.gbif.org/developer/registry) - Metadata on datasets, and 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()
  • species (https://www.gbif.org/developer/species) - Species names and metadata
    • rgbif functions: name_backbone(), name_lookup(), name_suggest(), name_usage()
  • occurrences (https://www.gbif.org/developer/occurrence) - Occurrences, both for 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 [14215] 
#> Records returned [50] 
#> No. unique hierarchies [1] 
#> No. media records [49] 
#> No. facets [0] 
#> Args [limit=50, offset=0, scientificName=Ursus americanus, fields=all] 
#> # A tibble: 50 x 88
#>    key   scientificName decimalLatitude decimalLongitude issues datasetKey
#>    <chr> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#>  1 1986… Ursus america…            30.1           -103.  cdrou… 50c9509d-…
#>  2 1990… Ursus america…            45.4            -93.2 cdrou… 50c9509d-…
#>  3 1990… Ursus america…            27.7            -81.5 gass84 50c9509d-…
#>  4 1990… Ursus america…            29.2            -81.8 cdrou… 50c9509d-…
#>  5 1990… Ursus america…            45.4            -93.1 cdrou… 50c9509d-…
#>  6 1993… Ursus america…            45.5            -93.1 cdrou… 50c9509d-…
#>  7 1990… Ursus america…            45.4            -93.2 cdrou… 50c9509d-…
#>  8 1990… Ursus america…            35.7            -76.6 cdrou… 50c9509d-…
#>  9 1990… Ursus america…            33.1            -91.9 cdrou… 50c9509d-…
#> 10 1990… Ursus america…            35.6            -82.9 cdrou… 50c9509d-…
#> # … with 40 more rows, and 82 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>, infraspecificEpithet <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>, http...unknown.org.nick <chr>,
#> #   informationWithheld <chr>, verbatimEventDate <chr>, datasetName <chr>,
#> #   verbatimLocality <chr>, gbifID <chr>, collectionCode <chr>,
#> #   occurrenceID <chr>, taxonID <chr>, catalogNumber <chr>,
#> #   recordedBy <chr>, http...unknown.org.occurrenceDetails <chr>,
#> #   institutionCode <chr>, rights <chr>, eventTime <chr>,
#> #   occurrenceRemarks <chr>, identificationID <chr>, name <chr>,
#> #   sex <chr>, lifeStage <chr>, continent <chr>, recordNumber <chr>,
#> #   dynamicProperties <chr>, georeferenceVerificationStatus <chr>,
#> #   locality <chr>, county <chr>, language <chr>, preparations <chr>,
#> #   disposition <chr>, fieldNotes <chr>, reproductiveCondition <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 [45844] 
#> Records returned [20] 
#> No. unique hierarchies [1] 
#> No. media records [15] 
#> No. facets [0] 
#> Args [limit=20, offset=0, taxonKey=9206251, fields=all] 
#> # A tibble: 20 x 101
#>    key   scientificName decimalLatitude decimalLongitude issues datasetKey
#>    <chr> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#>  1 1990… Helianthus an…            52.6            10.1  cdrou… 6ac3f774-…
#>  2 2235… Helianthus an…            51.2             4.45 ""     7f5e4129-…
#>  3 1990… Helianthus an…            26.2           -98.2  cdrou… 50c9509d-…
#>  4 2247… Helianthus an…            58.4            11.9  cdrou… 38b4c89f-…
#>  5 1993… Helianthus an…            34.0          -117.   cdrou… 50c9509d-…
#>  6 1986… Helianthus an…            27.7           -97.3  cdrou… 50c9509d-…
#>  7 1993… Helianthus an…            33.4          -118.   cdrou… 50c9509d-…
#>  8 1990… Helianthus an…            53.9            10.9  cdrou… 6ac3f774-…
#>  9 1986… Helianthus an…            33.8          -118.   cdrou… 50c9509d-…
#> 10 2247… Helianthus an…            55.7            14.2  gass84 38b4c89f-…
#> 11 2236… Helianthus an…            26.2           -98.2  cdrou… 50c9509d-…
#> 12 2265… Helianthus an…            33.8          -118.   cdrou… 50c9509d-…
#> 13 2005… Helianthus an…            27.5           -99.5  cdrou… 50c9509d-…
#> 14 2247… Helianthus an…            57.6            11.9  gass84 38b4c89f-…
#> 15 2366… Helianthus an…            27.3           -97.7  cdrou… 50c9509d-…
#> 16 2013… Helianthus an…            25.5          -108.   cdrou… 50c9509d-…
#> 17 1993… Helianthus an…            29.8           -95.2  cdrou… 50c9509d-…
#> 18 2269… Helianthus an…            29.8           -95.6  cdrou… 50c9509d-…
#> 19 2424… Helianthus an…            33.4          -118.   gass8… 9b7d1acf-…
#> 20 2006… Helianthus an…            27.7           -97.3  cdrou… 50c9509d-…
#> # … with 95 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>, 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>, catalogNumber <chr>, recordedBy <chr>,
#> #   institutionCode <chr>, locality <chr>, gbifID <chr>,
#> #   collectionCode <chr>, name <chr>, individualCount <int>,
#> #   continent <chr>, stateProvince <chr>, references <chr>,
#> #   rightsHolder <chr>, identifier <chr>, informationWithheld <chr>,
#> #   nomenclaturalCode <chr>, municipality <chr>, datasetName <chr>,
#> #   identificationVerificationStatus <chr>, language <chr>,
#> #   occurrenceID <chr>, type <chr>, taxonID <chr>, vernacularName <chr>,
#> #   datasetID <chr>, samplingProtocol <chr>, accessRights <chr>,
#> #   reproductiveCondition <chr>, dateIdentified <chr>, modified <chr>,
#> #   http...unknown.org.nick <chr>, verbatimEventDate <chr>,
#> #   verbatimLocality <chr>, http...unknown.org.occurrenceDetails <chr>,
#> #   rights <chr>, eventTime <chr>, identificationID <chr>, county <chr>,
#> #   occurrenceStatus <chr>, taxonConceptID <chr>, endDayOfYear <chr>,
#> #   startDayOfYear <chr>, higherClassification <chr>,
#> #   occurrenceRemarks <chr>, elevation <dbl>, recordNumber <chr>,
#> #   georeferencedBy <chr>, associatedTaxa <chr>,
#> #   http...unknown.org.recordId <chr>, otherCatalogNumbers <chr>,
#> #   collectionID <chr>, georeferenceSources <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)
#> Records found [2480598 (33), 9362842 (5525661), 2498387 (1826375)] 
#> Records returned [2480598 (5), 9362842 (5), 2498387 (5)] 
#> No. unique hierarchies [2480598 (1), 9362842 (1), 2498387 (1)] 
#> No. media records [2480598 (5), 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 68
#>   key   scientificName decimalLatitude decimalLongitude issues datasetKey
#>   <chr> <chr>                    <dbl>            <dbl> <chr>  <chr>     
#> 1 2243… Accipiter ery…           -38.3            -60.4 ""     b1047888-…
#> 2 2432… Accipiter ery…           -24.0            -52.2 ""     b1047888-…
#> 3 2243… Accipiter ery…           -24.3            -48.4 ""     b1047888-…
#> 4 2243… Accipiter ery…           -26.3            -48.6 ""     b1047888-…
#> 5 2243… Accipiter ery…           -26.3            -48.6 ""     b1047888-…
#> # … with 62 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>, associatedTaxa <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)
#> crs        : +init=epsg:4326 +proj=longlat +datum=WGS84 +no_defs +ellps=WGS84 +towgs84=0,0,0 
#> source     : memory
#> names      : layer 
#> values     : 0, 1  (min, max)
library(raster)
plot(x, axes = FALSE, box = FALSE)

Example map

Screencast

Contributors

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

adamdsmith - AgustinCamacho - AldoCompagnoni - AlexPeap - andzandz11 - AshleyWoods - AugustT - benmarwick - cathynewman - cboettig - coyotree - damianooldoni - dandaman - djokester - dlebauer - dmcglinn - dnoesgaard - DupontCai - EDiLD - elgabbas - emhart - fxi - ghost - gkburada - hadley - Huasheng12306 - ibartomeus - JanLauGe - jarioksa - jeroen - jhnwllr - jhpoelen - jivelasquezt - jkmccarthy - johnbaums - jwhalennds - karthik - kgturner - Kim1801 - ljuliusson - luisDVA - martinpfannkuchen - MattBlissett - MattOates - maxhenschell - mdsumner - Octoberweather - Pakillo - peterdesmet - PhillRob - poldham - qgroom - raymondben - rossmounce - sacrevert - sagitaninta - sckott - scottsfarley93 - simon-tarr - simontarr-aecom - SriramRamesh - stevenpbachman - stevensotelo - stevenysw - TomaszSuchan - tphilippi - vandit15 - vervis - vijaybarve - willgearty - Xuletajr - 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.


rofooter

Functions in rgbif

Name Description
create_gist Function that takes a list of files and creates payload for API
gbif_issues List all GBIF issues and their codes.
gbif_citation Get citation for datasets used
gbifmap Get Github credentials from use in console
gbifdata Get data.frame from occurrencelist, occurrencelist_many, or densitylist.
installations Installations metadata.
occ_download Spin up a download request for GBIF occurrence data.
mvt_fetch Fetch Map Vector Tiles (MVT)
name_backbone Lookup names in the GBIF backbone taxonomy.
isocodes Table of country two character ISO codes, and GBIF names
occ_download_cancel Cancel a download creation process.
densitylist The density web service provides access to records showing the density of occurrence records from the GBIF Network by one-degree cell.
get_credentials Get Github credentials from use in console
density_spplist The density web service provides access to records showing the density of occurrence records from the GBIF Network by one-degree cell.
gist Post a file as a Github gist
%>% Pipe operator
enumeration Enumerations.
elevation Get elevation for lat/long points from a data.frame or list of points.
downloads Downloads interface
gbifmap_dens Make a simple map to visualize GBIF data density data
gbifmap_list Make a simple map to visualize GBIF point data.
name_lookup Lookup names in all taxonomies in GBIF.
name_issues Parse and examine further GBIF name issues on a dataset.
taxonsearch Search for taxa in GBIF.
occ_search Search for GBIF occurrences
wkt_parse parse wkt into smaller bits
occ_spellcheck Spell check search term for occurrence searches
taxrank Get the possible values to be used for (taxonomic) rank arguments in GBIF API methods.
occ_download_datasets List datasets for a download
occ_download_dataset_activity Lists the downloads activity of a dataset
providers Get data providers and their unique keys.
taxoncount Search by taxon to retrieve number of records in GBIF.
gbif_issues_lookup Lookup issue definitions and short codes
gbif_names View highlighted terms in name results from GBIF.
taxonget Get taxonomic information on a specific taxon or taxa in GBIF by their taxon concept keys.
occ_download_list Lists the downloads created by a user.
gbif_oai GBIF registry data via OAI-PMH
gbif_photos View photos from GBIF.
name_usage Lookup details for specific names in all taxonomies in GBIF.
name_suggest Suggest up to 20 name usages.
gbif_bbox2wkt Convert a bounding box to a Well Known Text polygon, and a WKT to a bounding box
occ_issues Parse and examine further GBIF occurrence issues on a dataset.
networks Networks metadata.
many-values Many value inputs to some parameters
occ_download_meta Retrieves the occurrence download metadata by its unique key.
parsenames Parse taxon names using the GBIF name parser.
occ_metadata Search for catalog numbers, collection codes, collector names, and institution codes.
suggestfields Fields available in gbif_suggest function
organizations Organizations metadata.
stylegeojson Style a data.frame prior to converting to geojson.
occ_download_get Get a download from GBIF.
map_fetch Fetch aggregated density maps of GBIF occurrences
occ_count Get number of occurrence records.
nodes Nodes metadata.
occ_download_import Import a downloaded file from GBIF.
occurrencecount Counts taxon concept records matching a range of filters.
occurrencelist Occurrencelist searches for taxon concept records matching a range of filters.
occ_get Get data for specific GBIF occurrences.
occ_fields Vector of fields in the output for the function occ_search()
rgbif-package Interface to the Global Biodiversity Information Facility API.
occurrenceget Get individual records for a given occurrence record.
rgbif-defunct Defunct functions in rgbif
occurrencedensity Returns summary counts of occurrence records by one-degree cell for a single taxon, country, dataset, data publisher or data network.
occurrencelist_many occurrencelist_many is the same as occurrencelist, but takes in a vector of species names.
occurrencelist_all Occurrencelist_all carries out an occurrencelist query for a single name and all its name variants according to GBIF's name matching.
occ_data Search for GBIF occurrences - simplified for speed
togeojson Convert spatial data files to GeoJSON from various formats.
typestatus Type status options for GBIF searching
rgb_country_codes Look up 2 character ISO country codes
occ_facet Facet GBIF occurrences
occ_download_queue Download requests in a queue
resources Get data resources and their unique keys.
DownReq Download request
datasets Search for datasets and dataset metadata.
blanktheme Custom ggplot2 theme
count_facet Facetted count occurrence search.
check_wkt Check input WKT
dataset_metrics Get details on a GBIF dataset.
GbifQueue GBIF download queue
dataset_suggest Suggest datasets in GBIF.
dataset_search Search datasets in GBIF.
No Results!

Vignettes of rgbif

Name
downloads.Rmd
issues.Rmd
rgbif.Rmd
taxonomic_names.Rmd
No Results!

Last month downloads

Details

License MIT + file LICENSE
URL https://github.com/ropensci/rgbif (devel), https://docs.ropensci.org/rgbif (documentation), https://ropenscilabs.github.io/occurrence-manual/ (user manual)
BugReports https://github.com/ropensci/rgbif/issues
LazyData true
LazyLoad true
VignetteBuilder knitr
Encoding UTF-8
Language en-US
RoxygenNote 6.1.1
X-schema.org-applicationCategory Biodiversity
X-schema.org-keywords GBIF, specimens, API, web-services, occurrences, species, taxonomy
X-schema.org-isPartOf https://ropensci.org
NeedsCompilation no
Packaged 2019-10-30 04:52:11 UTC; sckott
Repository CRAN
Date/Publication 2019-10-30 13:20:02 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/rgbif)](http://www.rdocumentation.org/packages/rgbif)