Package 'rgbif'

Description

rgbif: A programmatic interface to the Web Service methods provided by the Global Biodiversity Information Facility.

About

This package gives you access to data from GBIF https://www.gbif.org/ via their API.

Documentation for the GBIF API

• summary https://www.gbif.org/developer/summary - Summary of the GBIF API

• registry https://www.gbif.org/developer/registry - Metadata on datasets, and contributing organizations

• species names https://www.gbif.org/developer/species - Species names and metadata

• occurrences https://www.gbif.org/developer/occurrence - Occurrences

• maps https://www.gbif.org/developer/maps - Maps - these APIs are not implemented in rgbif, and are meant more for integration with web based maps.

Author(s)

Scott Chamberlain

Karthik Ram

Dan Mcglinn

Vijay Barve

John Waller

Description

Check input WKT

Usage

check_wkt(wkt = NULL, skip_validate = FALSE)

Arguments

Examples

## Not run: 
check_wkt('POLYGON((30.1 10.1, 10 20, 20 60, 60 60, 30.1 10.1))')
check_wkt('POINT(30.1 10.1)')
check_wkt('LINESTRING(3 4,10 50,20 25)')

# check many passed in at once
check_wkt(c('POLYGON((30.1 10.1, 10 20, 20 60, 60 60, 30.1 10.1))',
  'POINT(30.1 10.1)'))

# bad WKT
# wkt <- 'POLYGON((30.1 10.1, 10 20, 20 60, 60 60, 30.1 a))'
# check_wkt(wkt)

# many wkt's, semi-colon separated, for many repeated "geometry" args
wkt <- "POLYGON((-102.2 46.0,-93.9 46.0,-93.9 43.7,-102.2 43.7,-102.2 46.0))
;POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))"
check_wkt(gsub("\n", '', wkt))

## End(Not run)

Description

Facetted count occurrence search.

Usage

count_facet(keys = NULL, by = "country", countries = 10, removezeros = FALSE)

Arguments

Examples

## Not run: 
# Select number of countries to facet on
count_facet(by='country', countries=3, removezeros = TRUE)
# Or, pass in country names
count_facet(by='country', countries='AR', removezeros = TRUE)

spplist <- c('Geothlypis trichas','Tiaris olivacea','Pterodroma axillaris',
             'Calidris ferruginea','Pterodroma macroptera',
             'Gallirallus australis',
             'Falco cenchroides','Telespiza cantans','Oreomystis bairdi',
             'Cistothorus palustris')
keys <- sapply(spplist,
  function(x) name_backbone(x, rank="species")$usageKey)
count_facet(keys, by='country', countries=3, removezeros = TRUE)
count_facet(keys, by='country', countries=3, removezeros = FALSE)
count_facet(by='country', countries=20, removezeros = TRUE)
count_facet(keys, by='basisOfRecord', countries=5, removezeros = TRUE)

# get occurrences by georeferenced state
## across all records
count_facet(by='georeferenced')

## by keys
count_facet(keys, by='georeferenced')

# by basisOfRecord
count_facet(by="basisOfRecord")

## End(Not run)

Description

Search for more obscure dataset metadata.

Usage

dataset(
  country = NULL,
  type = NULL,
  identifierType = NULL,
  identifier = NULL,
  machineTagNamespace = NULL,
  machineTagName = NULL,
  machineTagValue = NULL,
  modified = NULL,
  query = NULL,
  deleted = FALSE,
  limit = NULL,
  start = NULL,
  curlopts = list()
)

Arguments

Details

This function allows you to search for some more obscure dataset metadata that might not be possible with dataset_search(). For example, searching through registry machinetags.

Value

A list.

Examples

## Not run: 
dataset(limit=3)
dataset(country="US",limit=3)
dataset(type="CHECKLIST",limit=3)
dataset(identifierType = "URL",limit=3)
dataset(identifier = 168,limit=3)
dataset(machineTagNamespace = "metasync.gbif.org",limit=3)
dataset(machineTagName = "datasetTitle",limit=3)
dataset(machineTagValue = "Borkhart",limit=3)
dataset(modified = "2023-04-01", limit=3) 
dataset(q = "dog", limit=3) 
dataset(deleted=TRUE,limit=3)

## End(Not run)

Description

Get a GBIF dataset from a doi

Usage

dataset_doi(doi = NULL, limit = 20, start = NULL, curlopts = list())

Arguments

Details

This function allows for dataset lookup using a doi. Be aware that some doi have more than one dataset associated with them.

Value

A list.

Examples

## Not run: 
dataset_doi('10.15468/igasai')

## End(Not run)

Description

Check if a dataset is gridded

Usage

dataset_gridded(
  uuid = NULL,
  min_dis = 0.05,
  min_per = 50,
  min_dis_count = 30,
  return = "logical",
  warn = TRUE
)

Arguments

Details

Gridded datasets are a known problem at GBIF. Many datasets have equally-spaced points in a regular pattern. These datasets are usually systematic national surveys or data taken from some atlas (“so-called rasterized collection designs”). This function uses the percentage of unique lat-long points with the most common nearest neighbor distance to identify gridded datasets.

https://data-blog.gbif.org/post/finding-gridded-datasets/

I recommend keeping the default values for the parameters.

Value

A logical vector indicating whether a dataset is considered gridded. Or if return="data", a data.frame of more information.

Examples

## Not run: 

dataset_gridded("9070a460-0c6e-11dd-84d2-b8a03c50a862")
dataset_gridded(c("9070a460-0c6e-11dd-84d2-b8a03c50a862",
               "13b70480-bd69-11dd-b15f-b8a03c50a862"))



## End(Not run)

Description

List datasets that are deleted or have no endpoint.

Usage

dataset_duplicate(limit = 20, start = NULL, curlopts = list())

dataset_noendpoint(limit = 20, start = NULL, curlopts = list())

Arguments

Details

Get a list of deleted datasets or datasets with no endpoint. You get the full and no parameters aside from limit and start are accepted.

Value

A list.

Examples

## Not run: 
dataset_noendpoint(limit=3)

## End(Not run)

Description

Search for dataset metadata.

Usage

dataset_export(
  query = NULL,
  type = NULL,
  publishingCountry = NULL,
  subtype = NULL,
  license = NULL,
  keyword = NULL,
  publishingOrg = NULL,
  hostingOrg = NULL,
  endorsingNodeKey = NULL,
  decade = NULL,
  projectId = NULL,
  hostingCountry = NULL,
  networkKey = NULL,
  doi = NULL
)

dataset_search(
  query = NULL,
  type = NULL,
  publishingCountry = NULL,
  subtype = NULL,
  license = NULL,
  keyword = NULL,
  publishingOrg = NULL,
  hostingOrg = NULL,
  endorsingNodeKey = NULL,
  decade = NULL,
  projectId = NULL,
  hostingCountry = NULL,
  networkKey = NULL,
  doi = NULL,
  facet = NULL,
  facetLimit = NULL,
  facetOffset = NULL,
  facetMincount = NULL,
  facetMultiselect = NULL,
  limit = 100,
  start = NULL,
  description = FALSE,
  curlopts = list()
)

dataset_suggest(
  query = NULL,
  type = NULL,
  publishingCountry = NULL,
  subtype = NULL,
  license = NULL,
  keyword = NULL,
  publishingOrg = NULL,
  hostingOrg = NULL,
  endorsingNodeKey = NULL,
  decade = NULL,
  projectId = NULL,
  hostingCountry = NULL,
  networkKey = NULL,
  doi = NULL,
  limit = 100,
  start = NULL,
  description = FALSE,
  curlopts = list()
)

Arguments

Details

dataset_search() searches and returns metadata on GBIF datasets from the registry. This function does not search occurrence data, only metadata on the datasets that contain may contain occurrence data. It also searches over other dataset types, such checklist and metadata datasets. Only a sample of results is returned.

dataset_export() function will download a tibble of the results of a dataset_search(). This function is primarily useful if you want the full results of a dataset_search().

Use dataset_search(facet="x",limit=0)$facets to get simple group by counts for different parameters.

Value

A list for dataset_search(). A tibble for dataset_export().

References

https://techdocs.gbif.org/en/openapi/v1/registry#/Datasets/searchDatasets

Examples

## Not run: 
# search metadata on all datasets and return a sample
dataset_search()
# dataset_export() # download info on all +90K datasets 

dataset_search(publishingCountry = "US")
dataset_search(type = "OCCURRENCE") 
dataset_search(keyword = "bird")
dataset_search(subtype = "TAXONOMIC_AUTHORITY") 
dataset_search(license = "CC0_1_0") 
dataset_search(query = "frog") 
dataset_search(publishingCountry = "UA") 
dataset_search(publishingOrg = "e2e717bf-551a-4917-bdc9-4fa0f342c530") 
dataset_search(hostingOrg = "7ce8aef0-9e92-11dc-8738-b8a03c50a862") 
dataset_search(decade="1890,1990",limit=5)
dataset_search(projectId = "GRIIS") 
dataset_search(hostingCountry = "NO") 
dataset_search(networkKey = "99d66b6c-9087-452f-a9d4-f15f2c2d0e7e") 
dataset_search(doi='10.15468/aomfnb') 

# search multiple values 
dataset_search(projectId = "GRIIS;BID-AF2020-140-REG") 
dataset_search(hostingCountry = "NO;SE")
dataset_search(doi="10.15468/aomfnb;10.15468/igasai")

# multiple filters
dataset_search(license = "CC0_1_0",subtype = "TAXONOMIC_AUTHORITY")
# dataset_export(license = "CC0_1_0",subtype = "TAXONOMIC_AUTHORITY")

# using dataset export to get all datasets 
dataset_export(decade="1800,1900")
dataset_export(projectId="GRIIS")

# get simple group by counts 
dataset_search(facet="type",limit=0,facetLimit=5)$facets 
dataset_search(facet="publishingCountry",limit=0,facetLimit=5)$facets
dataset_search(facet="license",limit=0,facetLimit=5, facetMincount=10000)


## End(Not run)

Description

Get dataset metadata using a datasetkey

Usage

dataset_get(uuid = NULL, curlopts = list())

dataset_process(uuid = NULL, limit = 20, start = NULL, curlopts = list())

dataset_networks(uuid = NULL, limit = 20, start = NULL, curlopts = list())

dataset_constituents(uuid = NULL, limit = 20, start = NULL, curlopts = list())

dataset_comment(uuid = NULL, curlopts = list())

dataset_contact(uuid = NULL, curlopts = list())

dataset_endpoint(uuid = NULL, curlopts = list())

dataset_identifier(uuid = NULL, curlopts = list())

dataset_machinetag(uuid = NULL, curlopts = list())

dataset_tag(uuid = NULL, curlopts = list())

dataset_metrics(uuid = NULL, curlopts = list())

Arguments

Details

dataset_metrics() can only be used with checklist type datasets.

Value

A tibble or a list.

References

https://techdocs.gbif.org/en/openapi/v1/registry

Examples

## Not run: 
dataset_get("38b4c89f-584c-41bb-bd8f-cd1def33e92f")
dataset_process("38b4c89f-584c-41bb-bd8f-cd1def33e92f",limit=3)
dataset_networks("3dab037f-a520-4bc3-b888-508755c2eb52")
dataset_constituents("7ddf754f-d193-4cc9-b351-99906754a03b",limit=3)
dataset_comment("2e4cc37b-302e-4f1b-bbbb-1f674ff90e14")
dataset_contact("7ddf754f-d193-4cc9-b351-99906754a03b")
dataset_endpoint("7ddf754f-d193-4cc9-b351-99906754a03b")
dataset_identifier("7ddf754f-d193-4cc9-b351-99906754a03b")
dataset_machinetag("7ddf754f-d193-4cc9-b351-99906754a03b")
dataset_tag("c47f13c1-7427-45a0-9f12-237aad351040")
dataset_metrics("7ddf754f-d193-4cc9-b351-99906754a03b")

## End(Not run)

Description

Search for datasets and dataset metadata.

Usage

datasets(
  data = "all",
  type = NULL,
  uuid = NULL,
  query = NULL,
  id = NULL,
  limit = 100,
  start = NULL,
  curlopts = list()
)

Arguments

Value

A list.

References

https://www.gbif.org/developer/registry#datasets

Examples

## Not run: 
datasets(limit=5)
datasets(type="occurrence", limit=10)
datasets(uuid="a6998220-7e3a-485d-9cd6-73076bd85657")
datasets(data='contact', uuid="a6998220-7e3a-485d-9cd6-73076bd85657")
datasets(data='metadata', uuid="a6998220-7e3a-485d-9cd6-73076bd85657")
datasets(data='metadata', uuid="a6998220-7e3a-485d-9cd6-73076bd85657",
  id=598)
datasets(data=c('deleted','duplicate'))
datasets(data=c('deleted','duplicate'), limit=1)

# curl options
datasets(data=c('deleted','duplicate'), curlopts = list(verbose=TRUE))

## End(Not run)

Description

Register a derived dataset for citation.

Usage

derived_dataset(
  citation_data = NULL,
  title = NULL,
  description = NULL,
  source_url = NULL,
  gbif_download_doi = NULL,
  user = NULL,
  pwd = NULL,
  curlopts = list()
)

derived_dataset_prep(
  citation_data = NULL,
  title = NULL,
  description = NULL,
  source_url = NULL,
  gbif_download_doi = NULL,
  user = NULL,
  pwd = NULL,
  curlopts = list()
)

Arguments

Value

A list.

Usage

Create a citable DOI for a dataset derived from GBIF mediated occurrences.

Use-case (1) your dataset was obtained with occ_search() and never returned a citable DOI, but you want to cite the data in a research paper.

Use-case (2) your dataset was obtained using occ_download() and you got a DOI, but the data underwent extensive filtering using CoordinateCleaner or some other cleaning pipeline. In this case be sure to fill in your original gbif_download_doi.

Use-case (3) your dataset was generated using a GBIF cloud export but you want a DOI to cite in your research paper.

Use derived_dataset to create a custom citable meta-data description and most importantly a DOI link between an external archive (e.g. Zenodo) and the datasets involved in your research or analysis.

All fields (except gbif_download_doi) are required for the registration to work.

We recommend that you run derived_dataset_prep() to check registration details before making it final with derived_dataset().

Authentication

Some rgbif functions require your GBIF credentials.

For the user and pwd parameters, you can set them in one of three ways:

1. Set them in your .Renviron/.bash_profile (or similar) file with the names GBIF_USER, GBIF_PWD, and GBIF_EMAIL

2. Set them in your .Rprofile file with the names gbif_user and gbif_pwd.

3. Simply pass strings to each of the parameters in the function call.

We strongly recommend the first option - storing your details as environment variables - as it's the most widely used way to store secrets.

You can edit your .Renviron with usethis::edit_r_environ().

After editing, your .Renviron file should look something like this...

GBIF_USER="jwaller"
GBIF_PWD="fakepassword123"
GBIF_EMAIL="[email protected]"

See ?Startup for help.

References

https://data-blog.gbif.org/post/derived-datasets/ https://www.gbif.org/derived-dataset/about

Examples

## Not run: 
data <- data.frame(
 datasetKey = c(
 "3ea36590-9b79-46a8-9300-c9ef0bfed7b8",
 "630eb55d-5169-4473-99d6-a93396aeae38",
 "806bf7d4-f762-11e1-a439-00145eb45e9a"),
 count = c(3, 1, 2781)
 )

## If output looks ok, run derived_dataset to register the dataset
 derived_dataset_prep(
 citation_data = data,
 title = "Test for derived dataset",
 description = "This data was filtered using a fake protocol",
 source_url = "https://zenodo.org/record/4246090#.YPGS2OgzZPY"
 )

#  derived_dataset(
#  citation_data = data,
#  title = "Test for derived dataset",
#  description = "This data was filtered using a fake protocol",
#  source_url = "https://zenodo.org/record/4246090#.YPGS2OgzZPY"
#  )

## Example with occ_search and dplyr
# library(dplyr)

# citation_data <- occ_search(taxonKey=212, limit=20)$data %>%
#   group_by(datasetKey) %>% 
#   count()

# # You would still need to upload your data to Zenodo or something similar 
# derived_dataset_prep(
#   citation_data = citation_data,
#   title="Bird data downloaded for test",
#   description="This data was downloaded using rgbif::occ_search and was 
#   later uploaded to Zenodo.",
#   source_url="https://zenodo.org/record/4246090#.YPGS2OgzZPY",
#   gbif_download_doi = NULL,
# )

## End(Not run)

Description

Download predicate DSL (domain specific language)

Usage

pred(key, value)

pred_gt(key, value)

pred_gte(key, value)

pred_lt(key, value)

pred_lte(key, value)

pred_not(...)

pred_like(key, value)

pred_within(value)

pred_isnull(key)

pred_notnull(key)

pred_or(..., .list = list())

pred_and(..., .list = list())

pred_in(key, value)

pred_default()

Arguments

predicate methods and their equivalent types

⁠pred*⁠ functions are named for the 'type' of operation they do, following the terminology used by GBIF, see https://www.gbif.org/developer/occurrence#predicates

Function names are given, with the equivalent GBIF type value (e.g., pred_gt and greaterThan)

The following functions take one key and one value:

• pred: equals

• pred_lt: lessThan

• pred_lte: lessThanOrEquals

• pred_gt: greaterThan

• pred_gte: greaterThanOrEquals

• pred_like: like

The following function is only for geospatial queries, and only accepts a WKT string:

• pred_within: within

The following function is only for stating the you don't want a key to be null, so only accepts one key:

• pred_notnull: isNotNull

The following function is only for stating that you want a key to be null.

• pred_isnull : isNull

The following two functions accept multiple individual predicates, separating them by either "and" or "or":

• pred_and: and

• pred_or: or

The not predicate accepts one predicate; that is, this negates whatever predicate is passed in, e.g., not the taxonKey of 12345:

• pred_not: not

The following function is special in that it accepts a single key but many values; stating that you want to search for all the values:

• pred_in: in

The following function will apply commonly used defaults.

• pred_default

Using pred_default() is equivalent to running:

  pred_and(
   pred("HAS_GEOSPATIAL_ISSUE",FALSE),
   pred("HAS_COORDINATE",TRUE),
   pred("OCCURRENCE_STATUS","PRESENT"),
   pred_not(pred_in("BASIS_OF_RECORD",
    c("FOSSIL_SPECIMEN","LIVING_SPECIMEN")))
  )

What happens internally

Internally, the input to ⁠pred*⁠ functions turns into JSON to be sent to GBIF. For example ...

pred_in("taxonKey", c(2480946, 5229208)) gives:

{
   "type": "in",
   "key": "TAXON_KEY",
   "values": ["2480946", "5229208"]
 }

pred_gt("elevation", 5000) gives:

{
   "type": "greaterThan",
   "key": "ELEVATION",
   "value": "5000"
}

pred_or(pred("taxonKey", 2977832), pred("taxonKey", 2977901)) gives:

{
  "type": "or",
  "predicates": [
     {
       "type": "equals",
       "key": "TAXON_KEY",
       "value": "2977832"
     },
     {
       "type": "equals",
       "key": "TAXON_KEY",
       "value": "2977901"
     }
  ]
}

Keys

Acceptable arguments to the key parameter are (with the version of the key in parens that must be sent if you pass the query via the body parameter; see below for examples). You can also use the 'ALL_CAPS' version of a key if you prefer. Open an issue in the GitHub repository for this package if you know of a key that should be supported that is not yet.

• taxonKey (TAXON_KEY)

• acceptedTaxonKey (ACCEPTED_TAXON_KEY)

• kingdomKey (KINGDOM_KEY)

• phylumKey (PHYLUM_KEY)

• classKey (CLASS_KEY)

• orderKey (ORDER_KEY)

• familyKey (FAMILY_KEY)

• genusKey (GENUS_KEY)

• subgenusKey (SUBGENUS_KEY)

• speciesKey (SPECIES_KEY)

• scientificName (SCIENTIFIC_NAME)

• country (COUNTRY)

• publishingCountry (PUBLISHING_COUNTRY)

• hasCoordinate (HAS_COORDINATE)

• hasGeospatialIssue (HAS_GEOSPATIAL_ISSUE)

• typeStatus (TYPE_STATUS)

• recordNumber (RECORD_NUMBER)

• lastInterpreted (LAST_INTERPRETED)

• modified (MODIFIED)

• continent (CONTINENT)

• geometry (GEOMETRY)

• basisOfRecord (BASIS_OF_RECORD)

• datasetKey (DATASET_KEY)

• datasetID/datasetId (DATASET_ID)

• eventDate (EVENT_DATE)

• catalogNumber (CATALOG_NUMBER)

• otherCatalogNumbers (OTHER_CATALOG_NUMBERS)

• year (YEAR)

• month (MONTH)

• decimalLatitude (DECIMAL_LATITUDE)

• decimalLongitude (DECIMAL_LONGITUDE)

• elevation (ELEVATION)

• depth (DEPTH)

• institutionCode (INSTITUTION_CODE)

• collectionCode (COLLECTION_CODE)

• issue (ISSUE)

• mediatype (MEDIA_TYPE)

• recordedBy (RECORDED_BY)

• recordedById/recordedByID (RECORDED_BY_ID)

• establishmentMeans (ESTABLISHMENT_MEANS)

• coordinateUncertaintyInMeters (COORDINATE_UNCERTAINTY_IN_METERS)

• gadm (GADM_GID) (for the Database of Global Administrative Areas)

• level0Gid (GADM_LEVEL_0_GID)

• level1Gid (GADM_LEVEL_1_GID)

• level2Gid (GADM_LEVEL_2_GID)

• level3Gid (GADM_LEVEL_3_GID)

• stateProvince (STATE_PROVINCE)

• occurrenceStatus (OCCURRENCE_STATUS)

• publishingOrg (PUBLISHING_ORG)

• occurrenceId/occurrenceID (OCCURRENCE_ID)

• eventId/eventID (EVENT_ID)

• parentEventId/parentEventID (PARENT_EVENT_ID)

• identifiedBy (IDENTIFIED_BY)

• identifiedById/identifiedByID (IDENTIFIED_BY_ID)

• license (LICENSE)

• locality(LOCALITY)

• pathway (PATHWAY)

• preparations (PREPARATIONS)

• networkKey (NETWORK_KEY)

• organismId/organismID (ORGANISM_ID)

• organismQuantity (ORGANISM_QUANTITY)

• organismQuantityType (ORGANISM_QUANTITY_TYPE)

• protocol (PROTOCOL)

• relativeOrganismQuantity (RELATIVE_ORGANISM_QUANTITY)

• repatriated (REPATRIATED)

• sampleSizeUnit (SAMPLE_SIZE_UNIT)

• sampleSizeValue (SAMPLE_SIZE_VALUE)

• samplingProtocol (SAMPLING_PROTOCOL)

• verbatimScientificName (VERBATIM_SCIENTIFIC_NAME)

• taxonID/taxonId (TAXON_ID)

• taxonomicStatus (TAXONOMIC_STATUS)

• waterBody (WATER_BODY)

• iucnRedListCategory (IUCN_RED_LIST_CATEGORY)

• degreeOfEstablishment (DEGREE_OF_ESTABLISHMENT)

• isInCluster (IS_IN_CLUSTER)

• lifeStage (LIFE_STAGE)

• distanceFromCentroidInMeters (DISTANCE_FROM_CENTROID_IN_METERS)

• gbifId (GBIF_ID)

References

Download predicates docs: https://www.gbif.org/developer/occurrence#predicates

See Also

Other downloads: occ_download_cached(), occ_download_cancel(), occ_download_dataset_activity(), occ_download_datasets(), occ_download_get(), occ_download_import(), occ_download_list(), occ_download_meta(), occ_download_queue(), occ_download_wait(), occ_download()

Examples

pred("taxonKey", 3119195)
pred_gt("elevation", 5000)
pred_gte("elevation", 5000)
pred_lt("elevation", 1000)
pred_lte("elevation", 1000)
pred_within("POLYGON((-14 42, 9 38, -7 26, -14 42))")
pred_and(pred_within("POLYGON((-14 42, 9 38, -7 26, -14 42))"),
  pred_gte("elevation", 5000))
pred_or(pred_lte("year", 1989), pred("year", 2000))
pred_and(pred_lte("year", 1989), pred("year", 2000))
pred_in("taxonKey", c(2977832, 2977901, 2977966, 2977835))
pred_in("basisOfRecord", c("MACHINE_OBSERVATION", "HUMAN_OBSERVATION"))
pred_not(pred("taxonKey", 729))
pred_like("catalogNumber", "PAPS5-560%")
pred_notnull("issue")
pred("basisOfRecord", "LITERATURE")
pred("hasCoordinate", TRUE)
pred("stateProvince", "California")
pred("hasGeospatialIssue", FALSE)
pred_within("POLYGON((-14 42, 9 38, -7 26, -14 42))")
pred_or(pred("taxonKey", 2977832), pred("taxonKey", 2977901),
  pred("taxonKey", 2977966))
pred_in("taxonKey", c(2977832, 2977901, 2977966, 2977835))

Description

GBIF provides two ways to get occurrence data: through the ⁠/occurrence/search⁠ route (see occ_search()), or via the ⁠/occurrence/download⁠ route (many functions, see below). occ_search() is more appropriate for smaller data, while ⁠occ_download*()⁠ functions are more appropriate for larger data requests.

Settings

You'll use occ_download() to kick off a download. You'll need to give that function settings from your GBIF profile: your user name, your password, and your email. These three settings are required to use the function. You can specify them in one of three ways:

• Pass them to occ_download as parameters

• Use R options: As options either in the current R session using the options() function, or by setting them in your .Rprofile file, after which point they'll be read in automatically

• Use environment variables: As env vars either in the current R session using the Sys.setenv() function, or by setting them in your .Renviron/.bash_profile or similar files, after which point they'll be read in automatically

BEWARE

You can not perform that many downloads, so plan wisely. See Rate limiting below.

Rate limiting

If you try to launch too many downloads, you will receive an 420 "Enhance Your Calm" response. If there is less then 100 in total across all GBIF users, then you can have 3 running at a time. If there are more than that, then each user is limited to 1 only. These numbers are subject to change.

Functions

• occ_download() - Start a download

• occ_download_prep() - Prepare a download request

• occ_download_queue() - Start many downloads in a queue

• occ_download_cached() - Check for downloads already in your GBIF account

• occ_download_wait() - Re-run occ_download_meta() until ready

• occ_download_meta() - Get metadata progress on a single download

• occ_download_list() - List your downloads

• occ_download_cancel() - Cancel a download

• occ_download_cancel_staged() - Cancels any jobs with status RUNNING or PREPARING

• occ_download_get() - Retrieve a download

• occ_download_import() - Import a download from local file system

• occ_download_datasets() - List datasets for a download

• occ_download_dataset_activity() - Lists the downloads activity of a dataset

Download query composer methods:

See download_predicate_dsl

Query length

GBIF has a limit of 12,000 characters for a download query. This means that you can have a pretty long query, but at some point it may lead to an error on GBIF's side and you'll have to split your query into a few.

Download status

The following statuses can be found with any download:

• PREPARING: just submitted by user and awaiting processing (typically only a few seconds)

• RUNNING: being created (takes typically 1-15 minutes)

• FAILED: something unexpected went wrong

• KILLED: user decided to abort the job while it was in PREPARING or RUNNING phase

• SUCCEEDED: The download was created and the user was informed

• FILE_ERASED: The download was deleted according to the retention policy, see https://www.gbif.org/faq?question=for-how-long-will-does-gbif-store-downloads

Description

Uses the GeoNames web service

Usage

elevation(
  input = NULL,
  latitude = NULL,
  longitude = NULL,
  latlong = NULL,
  elevation_model = "srtm3",
  username = Sys.getenv("GEONAMES_USER"),
  key,
  curlopts,
  ...
)

Arguments

Value

A new column named elevation_geonames in the supplied data.frame or a vector with elevation of each location in meters. Note that data from GBIF can already have a column named elevation, thus the column we add is named differently.

GeoNames user name

To get a GeoNames user name, register for an account at http://www.geonames.org/login - then you can enable your account for the GeoNames webservice on your account page (http://www.geonames.org/manageaccount). Once you are enabled to use the webservice, you can pass in your username to the username parameter. Better yet, store your username in your .Renviron file, or similar (e.g., .zshrc or .bash_profile files) and read it in via Sys.getenv() as in the examples below. By default we do Sys.getenv("GEONAMES_USER") for the username parameter.

Elevation models

• srtm3:

  • sample area: ca 90m x 90m

  • result: a single number giving the elevation in meters according to srtm3, ocean areas have been masked as "no data" and have been assigned a value of -32768

• srtm1:

  • sample area: ca 30m x 30m

  • result: a single number giving the elevation in meters according to srtm1, ocean areas have been masked as "no data" and have been assigned a value of -32768

• astergdem (Aster Global Digital Elevation Model V2 2011):

  • sample area: ca 30m x 30m, between 83N and 65S latitude

  • result: a single number giving the elevation in meters according to aster gdem, ocean areas have been masked as "no data" and have been assigned a value of -32768

• gtopo30:

  • sample area: ca 1km x 1km

  • result: a single number giving the elevation in meters according to gtopo30, ocean areas have been masked as "no data" and have been assigned a value of -9999

References

GeoNames http://www.geonames.org/export/web-services.html

Examples

## Not run: 
user <- Sys.getenv("GEONAMES_USER")

occ_key <- name_suggest('Puma concolor')$key[1]
dat <- occ_search(taxonKey = occ_key, limit = 300, hasCoordinate = TRUE)
head( elevation(dat$data, username = user) )

# Pass in a vector of lat's and a vector of long's
elevation(latitude = dat$data$decimalLatitude[1:10],
  longitude = dat$data$decimalLongitude[1:10],
  username = user, verbose = TRUE)

# Pass in lat/long pairs in a single vector
pairs <- list(c(31.8496,-110.576060), c(29.15503,-103.59828))
elevation(latlong=pairs, username = user)

# Pass on curl options
pairs <- list(c(31.8496,-110.576060), c(29.15503,-103.59828))
elevation(latlong=pairs, username = user, verbose = TRUE)

# different elevation models
lats <- dat$data$decimalLatitude[1:5]
lons <- dat$data$decimalLongitude[1:5]
elevation(latitude = lats, longitude = lons, elevation_model = "srtm3")
elevation(latitude = lats, longitude = lons, elevation_model = "srtm1")
elevation(latitude = lats, longitude = lons, elevation_model = "astergdem")
elevation(latitude = lats, longitude = lons, elevation_model = "gtopo30")

## End(Not run)

Description

Many parts of the GBIF API make use of enumerations, i.e. controlled vocabularies for specific topics - and are available via these functions

Usage

enumeration(x = NULL, curlopts = list())

enumeration_country(curlopts = list())

Arguments

Value

enumeration returns a character vector, while enumeration_country returns a data.frame.

Examples

## Not run: 
# basic enumeration
enumeration()
enumeration("NameType")
enumeration("MetadataType")
enumeration("TypeStatus")

# country enumeration
enumeration_country()

# curl options
enumeration(curlopts = list(verbose=TRUE))

## End(Not run)

Description

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

Usage

gbif_bbox2wkt(minx = NA, miny = NA, maxx = NA, maxy = NA, bbox = NULL)

gbif_wkt2bbox(wkt = NULL)

Arguments

Value

gbif_bbox2wkt returns an object of class charactere, a Well Known Text string of the form 'POLYGON((minx miny, maxx miny, maxx maxy, minx maxy, minx miny))'.

gbif_wkt2bbox returns a numeric vector of length 4, like c(minx, miny, maxx, maxy)

Examples

## Not run: 
# Convert a bounding box to a WKT
## Pass in a vector of length 4 with all values
gbif_bbox2wkt(bbox=c(-125.0,38.4,-121.8,40.9))

## Or pass in each value separately
gbif_bbox2wkt(minx=-125.0, miny=38.4, maxx=-121.8, maxy=40.9)

# Convert a WKT object to a bounding box
wkt <- "POLYGON((-125 38.4,-125 40.9,-121.8 40.9,-121.8 38.4,-125 38.4))"
gbif_wkt2bbox(wkt)

## End(Not run)

Description

Get citation for datasets used

Usage

gbif_citation(x)

Arguments

Details

The function is deprecated for use with occ_search() and occ_data() results, and is deprecated for use with datasetKeys and gbifids. Instead, we encourage you to use derived_dataset() instead.

occ_download_get() and occ_download_meta() results are still supported.

Value

list with S3 class assigned, used by a print method to pretty print citation information. Though you can unclass the output or just index to the named items as needed.

Examples

## Not run: 
# Downloads
## occ_download_get()
# d1 <- occ_download(pred("country", "BG"), pred_gte("year", 2020))
# occ_download_meta(d1) # wait until status = succeeded
# d1 <- occ_download_get(d1, overwrite = TRUE)
# gbif_citation(d1)

## occ_download_meta()
# key <- "0000122-171020152545675"
# res <- occ_download_meta(key)
# gbif_citation(res)

## End(Not run)

Description

Geocode lat-lon point(s) with GBIF's set of geo-polygons (experimental)

Usage

gbif_geocode(latitude = NULL, longitude = NULL)

Arguments

Value

A data.frame of results from the GBIF gecoding service.

• latitude : The input latitude

• longitude : The input longitude

• index : The original input rownumber

• id : The polygon id from which the geocode comes from

• type : One of the following : "Political" (county codes), "IHO" (marine regions), "SeaVox" (marine regions), "WGSRPD" (tdwg regions), "EEZ", (in national waters) or "GADM0","GADM1","GADM2","GADM2"(http://gadm.org/)

• title : The name of the source polygon

• distance : distance to the polygon boarder

This function uses the GBIF geocoder API which is not guaranteed to be stable and is undocumented. As such, this may return different data over time, may be rate-limited or may stop working if GBIF change the service. Use this function with caution.

References

http://gadm.org/ http://marineregions.org/ http://www.tdwg.org/standards/ http://api.gbif.org/v1/geocode/reverse?lat=0&lng=0

Examples

## Not run: 
# one pair 
gbif_geocode(0,0)
# or multiple pairs of points
gbif_geocode(c(0,50),c(0,20))


## End(Not run)

Description

Returns a data.frame of all GBIF issues with the following columns:

• code: issue short code, e.g. gass84

• code: issue full name, e.g. GEODETIC_DATUM_ASSUMED_WGS84

• description: issue description

• type: issue type, either related to occurrence or name

Usage

gbif_issues()

Source

https://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/OccurrenceIssue.html https://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/NameUsageIssue.html

Description

Lookup issue definitions and short codes

Usage

gbif_issues_lookup(issue = NULL, code = NULL)

Arguments

Examples

gbif_issues_lookup(issue = 'CONTINENT_COUNTRY_MISMATCH')
gbif_issues_lookup(code = 'ccm')
gbif_issues_lookup(issue = 'COORDINATE_INVALID')
gbif_issues_lookup(code = 'cdiv')

Description

View highlighted terms in name results from GBIF.

Usage

gbif_names(input, output = NULL, browse = TRUE)

Arguments

Examples

## Not run: 
# browse=FALSE returns path to file
gbif_names(name_lookup(query='snake', hl=TRUE), browse=FALSE)

(out <- name_lookup(query='canada', hl=TRUE, limit=5))
gbif_names(out)
gbif_names(name_lookup(query='snake', hl=TRUE))
gbif_names(name_lookup(query='bird', hl=TRUE))

# or not highlight
gbif_names(name_lookup(query='bird', limit=200))

## End(Not run)

Description

GBIF registry data via OAI-PMH

Usage

gbif_oai_identify(...)

gbif_oai_list_identifiers(
  prefix = "oai_dc",
  from = NULL,
  until = NULL,
  set = NULL,
  token = NULL,
  as = "df",
  ...
)

gbif_oai_list_records(
  prefix = "oai_dc",
  from = NULL,
  until = NULL,
  set = NULL,
  token = NULL,
  as = "df",
  ...
)

gbif_oai_list_metadataformats(id = NULL, ...)

gbif_oai_list_sets(token = NULL, as = "df", ...)

gbif_oai_get_records(ids, prefix = "oai_dc", as = "parsed", ...)

Arguments

Details

These functions only work with GBIF registry data, and do so via the OAI-PMH protocol (https://www.openarchives.org/OAI/openarchivesprotocol.html)

Value

raw text, list or data.frame, depending on requested output via as parameter

Examples

## Not run: 
gbif_oai_identify()

today <- format(Sys.Date(), "%Y-%m-%d")
gbif_oai_list_identifiers(from = today)
gbif_oai_list_identifiers(set = "country:NL")

gbif_oai_list_records(from = today)
gbif_oai_list_records(set = "country:NL")

gbif_oai_list_metadataformats()
gbif_oai_list_metadataformats(id = "9c4e36c1-d3f9-49ce-8ec1-8c434fa9e6eb")

gbif_oai_list_sets()
gbif_oai_list_sets(as = "list")

gbif_oai_get_records("9c4e36c1-d3f9-49ce-8ec1-8c434fa9e6eb")
ids <- c("9c4e36c1-d3f9-49ce-8ec1-8c434fa9e6eb",
         "e0f1bb8a-2d81-4b2a-9194-d92848d3b82e")
gbif_oai_get_records(ids)

## End(Not run)

Description

View photos from GBIF.

Usage

gbif_photos(input, output = NULL, which = "table", browse = TRUE)

Arguments

Details

The max number of photos you can see when which="map" is ~160, so cycle through if you have more than that.

BEWARE

The maps in the table view may not show up correctly if you are using RStudio

Examples

## Not run: 
res <- occ_search(mediaType = 'StillImage', limit = 100)
gbif_photos(res)
gbif_photos(res, which='map')

res <- occ_search(scientificName = "Aves", mediaType = 'StillImage',
  limit=150)
gbif_photos(res)
gbif_photos(res, output = '~/barfoo')

## End(Not run)

Description

Installations metadata.

Usage

installations(
  data = "all",
  uuid = NULL,
  query = NULL,
  identifier = NULL,
  identifierType = NULL,
  limit = 100,
  start = NULL,
  curlopts = list()
)

Arguments

Details

identifierType options:

• DOI No description.

• FTP No description.

• GBIF_NODE Identifies the node (e.g: DK for Denmark, sp2000 for Species 2000).

• GBIF_PARTICIPANT Participant identifier from the GBIF IMS Filemaker system.

• GBIF_PORTAL Indicates the identifier originated from an auto_increment column in the portal.data_provider or portal.data_resource table respectively.

• HANDLER No description.

• LSID Reference controlled by a separate system, used for example by DOI.

• SOURCE_ID No description.

• UNKNOWN No description.

• URI No description.

• URL No description.

• UUID No description.

References

https://www.gbif.org/developer/registry#installations

Examples

## Not run: 
installations(limit=5)
installations(query="france", limit = 25)
installations(uuid="b77901f9-d9b0-47fa-94e0-dd96450aa2b4")
installations(data='contact', uuid="2e029a0c-87af-42e6-87d7-f38a50b78201")
installations(data='endpoint', uuid="b77901f9-d9b0-47fa-94e0-dd96450aa2b4")
installations(data='dataset', uuid="b77901f9-d9b0-47fa-94e0-dd96450aa2b4")
installations(data='deleted', limit = 25)
installations(data='deleted', limit=2)
installations(data=c('deleted','nonPublishing'), limit=2)
installations(identifierType='DOI', limit=2)

# Pass on curl options
installations(data='deleted', curlopts = list(verbose=TRUE))

## End(Not run)

Description

Search for literature that cites GBIF mediated data

Usage

lit_search(
  q = NULL,
  countriesOfResearcher = NULL,
  countriesOfCoverage = NULL,
  literatureType = NULL,
  relevance = NULL,
  year = NULL,
  topics = NULL,
  datasetKey = NULL,
  publishingOrg = NULL,
  peerReview = NULL,
  openAccess = NULL,
  downloadKey = NULL,
  doi = NULL,
  journalSource = NULL,
  journalPublisher = NULL,
  flatten = TRUE,
  limit = NULL,
  curlopts = list()
)

lit_count(...)

Arguments

Details

This function enables you to search for literature indexed by GBIF, including peer-reviewed papers, citing GBIF datasets and downloads. The literature API powers the literature search on GBIF.

The GBIF Secretariat maintains an ongoing literature tracking programme, which identifies research uses and citations of biodiversity information accessed through GBIF’s global infrastructure.

In the literature database, relevance refers to how publications relate to GBIF following these definitions:

• GBIF_USED : makes substantive use of data in a quantitative analysis (e.g. ecological niche modelling)

• GBIF_CITED : cites a qualitative fact derived in data (e.g. a given species is found in a given country)

• GBIF_DISCUSSED : discusses GBIF as an infrastructure or the use of data

• GBIF_PRIMARY : GBIF is the primary source of data (no longer applied)

• GBIF_ACKNOWLEDGED : acknowledges GBIF (but doesn't use or cite data)

• GBIF_PUBLISHED : describes or talks about data published to GBIF

• GBIF_AUTHOR : authored by GBIF staff

• GBIF_MENTIONED : unspecifically mentions GBIF or the GBIF portal

• GBIF_FUNDED : funded by GBIF or a GBIF-managed funding programme

The following arguments can take multiple values:

• relevance

• countriesOfResearcher

• countriesOfCoverage

• literatureType

• topics

• datasetKey

• publishingOrg

• downloadKey

• doi

• journalSource

• journalPublisher

If flatten=TRUE, then data will be returned as flat data.frame with no complex column types (i.e. no lists or data.frames).

limit=NULL will return up to 10,000 records. The maximum value for limit is 10,000. If no filters are used, only the first 1,000 records will be returned, limit must be explicitly set to limit=10000, to get the first 10,000 records in this case.

lit_count() is a convenience wrapper, which will return the number of literature references for a certain lit_search() query. This is the same as running lit_search()$meta$count.

Value

A named list with two values: $data and $meta. $data is a data.frame of literature references.

Examples

## Not run: 
lit_search(q="bats")$data 
lit_search(datasetKey="50c9509d-22c7-4a22-a47d-8c48425ef4a7")
lit_search(year=2020)
lit_search(year="2011,2020") # year ranges
lit_search(relevance=c("GBIF_CITED","GBIF_USED")) # multiple values
lit_search(relevance=c("GBIF_USED","GBIF_CITED"), 
topics=c("EVOLUTION","PHYLOGENETICS"))
lit_count() # total number of literature referencing GBIF
lit_count(peerReview=TRUE)
# number of citations of iNaturalist 
lit_count(datasetKey="50c9509d-22c7-4a22-a47d-8c48425ef4a7")
# number of peer-reviewed articles used GBIF mediated data
lit_count(peerReview=TRUE,literatureType="JOURNAL",relevance="GBIF_USED")
 
# Typically what is meant by "literature that uses GBIF" 
lit_search(peerReview=TRUE,literatureType="JOURNAL",relevance="GBIF_USED")
lit_count(peerReview=TRUE,literatureType="JOURNAL",relevance="GBIF_USED")

## End(Not run)

Description

This function is a wrapper for the GBIF mapping api version 2.0. The mapping API is a web map tile service making it straightforward to visualize GBIF content on interactive maps, and overlay content from other sources. It returns tile maps with number of GBIF records per area unit that can be used in a variety of ways, for example in interactive leaflet web maps. Map details are specified by a number of query parameters, some of them optional. Full documentation of the GBIF mapping api can be found at https://www.gbif.org/developer/maps

Usage

map_fetch(
  source = "density",
  x = 0:1,
  y = 0,
  z = 0,
  format = "@1x.png",
  srs = "EPSG:4326",
  bin = NULL,
  hexPerTile = NULL,
  squareSize = NULL,
  style = NULL,
  taxonKey = NULL,
  datasetKey = NULL,
  country = NULL,
  publishingOrg = NULL,
  publishingCountry = NULL,
  year = NULL,
  basisOfRecord = NULL,
  return = "png",
  base_style = NULL,
  plot_terra = TRUE,
  curlopts = list(http_version = 2),
  ...
)

Arguments

Details

The default settings, return='png', will return a magick-image png. This image will be a composite image of the the occurrence tiles fetched and a base map. This map is primarily useful as a high quality image of occurrence records.

The args x and y can both be integer sequences. For example, x=0:3 or y=0:1. Note that the tile index starts at 0. Higher values of z, will will produce more tiles that can be fetched and stitched together. Selecting a too high value for x or y will produce a blank image.

Setting return='terra' will return a terra::SpatRaster object. This is primarily useful if you were interested in the underlying aggregated occurrence density data.

See the article

Value

a magick-image or terra::SpatRaster object.

Author(s)

John Waller and Laurens Geffert [email protected]

References

https://www.gbif.org/developer/maps

https://api.gbif.org/v2/map/demo.html

https://api.gbif.org/v2/map/demo13.html

See Also

mvt_fetch()

Examples

## Not run: 

# all occurrences
map_fetch()
# get artic map
map_fetch(srs='EPSG:3031') 
# only preserved specimens
map_fetch(basisOfRecord="PRESERVED_SPECIMEN")

# Map of occ in Great Britain
map_fetch(z=3,y=1,x=7:8,country="GB")
# Peguins with artic projection
map_fetch(srs='EPSG:3031',taxonKey=2481660,style='glacier.point', 
base_style="gbif-dark")

# occ from a long time ago
map_fetch(year=1600) 
# polygon style 
map_fetch(style="iNaturalist.poly",bin="hex")
# iNaturalist dataset plotted 
map_fetch(datasetKey="50c9509d-22c7-4a22-a47d-8c48425ef4a7",
  style="iNaturalist.poly")
 
# use source="adhoc" for more filters
map_fetch(z=1,
  source="adhoc",
  iucn_red_list_category="CR",
  style="scaled.circles",
  base_style='gbif-light')

# cropped map of Hawaii
map_fetch(z=5,x=3:4,y=12,source="adhoc",gadmGid="USA.12_1")



## End(Not run)

Description

This function is a wrapper for the GBIF mapping api version 2.0. The mapping API is a web map tile service making it straightforward to visualize GBIF content on interactive maps, and overlay content from other sources. It returns maps vector tiles with number of GBIF records per area unit that can be used in a variety of ways, for example in interactive leaflet web maps. Map details are specified by a number of query parameters, some of them optional. Full documentation of the GBIF mapping api can be found at https://www.gbif.org/developer/maps

Usage

mvt_fetch(
  source = "density",
  x = 0,
  y = 0,
  z = 0,
  srs = "EPSG:4326",
  bin = NULL,
  hexPerTile = NULL,
  squareSize = NULL,
  style = "classic.point",
  taxonKey = NULL,
  datasetKey = NULL,
  country = NULL,
  publishingOrg = NULL,
  publishingCountry = NULL,
  year = NULL,
  basisOfRecord = NULL,
  ...
)

Arguments

Details

This function uses the arguments passed on to generate a query to the GBIF web map API. The API returns a web tile object as png that is read and converted into an R raster object. The break values or nbreaks generate a custom colour palette for the web tile, with each bin corresponding to one grey value. After retrieval, the raster is reclassified to the actual break values. This is a somewhat hacky but nonetheless functional solution in the absence of a GBIF raster API implementation.

We add extent and set the projection for the output. You can reproject after retrieving the output.

Value

an sf object

References

https://www.gbif.org/developer/maps

See Also

map_fetch()

Examples

## Not run: 
if (
 requireNamespace("sf", quietly = TRUE) &&
 requireNamespace("protolite", quietly = TRUE)
) {
  x <- mvt_fetch(taxonKey = 2480498, year = 2007:2011)
  x
  
  # gives an sf object
  class(x)
  
  # different srs
  ## 3857
  y <- mvt_fetch(taxonKey = 2480498, year = 2010, srs = "EPSG:3857")
  y
  ## 3031
  z <- mvt_fetch(taxonKey = 2480498, year = 2010, srs = "EPSG:3031", verbose = TRUE)
  z
  # 3575
  z <- mvt_fetch(taxonKey = 2480498, year = 2010, srs = "EPSG:3575")
  z

  # bin
  x <- mvt_fetch(taxonKey = 212, year = 1998, bin = "hex",
     hexPerTile = 30, style = "classic-noborder.poly")
  x

  # query with basisOfRecord
  mvt_fetch(taxonKey = 2480498, year = 2010,
    basisOfRecord = "HUMAN_OBSERVATION")
  mvt_fetch(taxonKey = 2480498, year = 2010,
    basisOfRecord = c("HUMAN_OBSERVATION", "LIVING_SPECIMEN"))
 }

## End(Not run)

Description

Lookup names in the GBIF backbone taxonomy.

Usage

name_backbone(
  name,
  rank = NULL,
  kingdom = NULL,
  phylum = NULL,
  class = NULL,
  order = NULL,
  family = NULL,
  genus = NULL,
  strict = FALSE,
  verbose = FALSE,
  start = NULL,
  limit = 100,
  curlopts = list()
)

name_backbone_verbose(
  name,
  rank = NULL,
  kingdom = NULL,
  phylum = NULL,
  class = NULL,
  order = NULL,
  family = NULL,
  genus = NULL,
  strict = FALSE,
  start = NULL,
  limit = 100,
  curlopts = list()
)

Arguments

Details

If you don't get a match, GBIF gives back a data.frame with columns synonym, confidence, and matchType='NONE'.

Value

For name_backbone, a data.frame for a single taxon with many columns. For name_backbone_verbose, a larger number of results in a data.frame the results of resulting from fuzzy matching. You will also get back your input name, rank, kingdom, phylum ect. as columns input_name, input_rank, input_kingdom ect. so you can check the results.

References

https://www.gbif.org/developer/species#searching

Examples

## Not run: 
name_backbone(name='Helianthus annuus', kingdom='plants')
name_backbone(name='Helianthus', rank='genus', kingdom='plants')
name_backbone(name='Poa', rank='genus', family='Poaceae')

# Verbose - gives back alternatives
## Strictness
name_backbone_verbose(name='Poa', kingdom='plants',
  strict=FALSE)
name_backbone_verbose(name='Helianthus annuus', kingdom='plants',
  strict=TRUE)

# Non-existent name - returns list of lenght 3 stating no match
name_backbone(name='Aso')
name_backbone(name='Oenante')

# Pass on curl options
name_backbone(name='Oenante', curlopts = list(verbose=TRUE))

## End(Not run)

Description

Lookup names in the GBIF backbone taxonomy in a checklist.

Usage

name_backbone_checklist(
  name_data = NULL,
  rank = NULL,
  kingdom = NULL,
  phylum = NULL,
  class = NULL,
  order = NULL,
  family = NULL,
  genus = NULL,
  strict = FALSE,
  verbose = FALSE,
  curlopts = list()
)

Arguments

Details

This function is an alternative for name_backbone(), which will work with a list of names (a vector or a data.frame). The data.frame should have the following column names, but only the 'name' column is required. If only one column is present, then that column is assumed to be the 'name' column.

• name : (required)

• rank : (optional)

• kingdom : (optional)

• phylum : (optional)

• class : (optional)

• order : (optional)

• family : (optional)

• genus : (optional)

The input columns will be returned as "verbatim_name","verbatim_rank", "verbatim_phylum" ect. A column of "verbatim_index" will also be returned giving the index of the input.

The following aliases for the 'name' column will work (any case or with '_' will work) :

• "scientificName", "ScientificName", "scientific_name" ...

• "sci_name", "sciname", "SCI_NAME" ...

• "names", "NAMES" ...

• "species", "SPECIES" ...

• "species_name", "speciesname" ...

• "sp_name", "SP_NAME", "spname" ...

• "taxon_name", "taxonname", "TAXON NAME" ...

If more than one aliases is present and no column is named 'name', then the left-most column with an acceptable aliased name above is used.

If verbose=TRUE, a column called is_alternative will be returned, which species if a name was originally a first choice or not. is_alternative=TRUE means the name was not is not considered to be the best match by GBIF.

Default values for rank, kingdom, phylum, class, order, family, and genus can can be supplied. If a default value is supplied, the values for these fields are ignored in name_data, and the default value is used instead. This is most useful if you have a list of names and you know they are all plants, insects, birds, ect. You can also input multiple values, if they are the same length as list of names you are trying to match.

This function can also be used with a character vector of names. In that case no column names are needed of course.

This function is very similar to the GBIF species-lookup tool. https://www.gbif.org/tools/species-lookup.

If you have 1000s of names to match, it can take some minutes to get back all of the matches. I have tested it with 60K names. Scientific names with author details usually get better matches.

See also article Working With Taxonomic Names.

Value

A data.frame of matched names.

Examples

## Not run: 

library(rgbif)

name_data <- data.frame(
 scientificName = c(
   "Cirsium arvense (L.) Scop.", # a plant
   "Calopteryx splendens (Harris, 1780)", # an insect
   "Puma concolor (Linnaeus, 1771)", # a big cat
   "Ceylonosticta alwisi (Priyadarshana & Wijewardhane, 2016)", # newly discovered insect 
   "Puma concuolor (Linnaeus, 1771)", # a mis-spelled big cat
   "Fake species (John Waller 2021)", # a fake species
   "Calopteryx" # Just a Genus   
 ), description = c(
   "a plant",
   "an insect",
   "a big cat",
   "newly discovered insect",
   "a mis-spelled big cat",
   "a fake species",
   "just a GENUS"
 ), 
 kingdom = c(
   "Plantae",
   "Animalia",
   "Animalia",
   "Animalia",
   "Animalia",
   "Johnlia",
   "Animalia"
 ))

name_backbone_checklist(name_data)

# return more than 1 result per name
name_backbone_checklist(name_data,verbose=TRUE) 

# works with just vectors too 
name_list <- c(
"Cirsium arvense (L.) Scop.", 
"Calopteryx splendens (Harris, 1780)", 
"Puma concolor (Linnaeus, 1771)", 
"Ceylonosticta alwisi (Priyadarshana & Wijewardhane, 2016)", 
"Puma concuolor", 
"Fake species (John Waller 2021)", 
"Calopteryx")

name_backbone_checklist(name_list)
name_backbone_checklist(name_list,verbose=TRUE)
name_backbone_checklist(name_list,strict=TRUE) 

# default values
name_backbone_checklist(c("Aloe arborecens Mill.",
"Cirsium arvense (L.) Scop."),kingdom="Plantae")
name_backbone_checklist(c("Aloe arborecens Mill.",
"Calopteryx splendens (Harris, 1780)"),kingdom=c("Plantae","Animalia"))


## End(Not run)

Description

Parse and examine further GBIF name issues on a dataset.

Usage

name_issues(.data, ..., mutate = NULL)

Arguments

References

https://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/NameUsageIssue.html

Examples

## Not run: 
# what do issues mean, can print whole table
head(gbif_issues())
# or just name related issues
gbif_issues()[which(gbif_issues()$type %in% c("name")),]
# or search for matches
gbif_issues()[gbif_issues()$code %in% c('bbmn','clasna','scina'),]
# compare out data to after name_issues use
(aa <- name_usage(name = "Lupus"))
aa %>% name_issues("clasna")

## or parse issues in various ways
### remove data rows with certain issue classes
aa %>% name_issues(-clasna, -scina)

### expand issues to more descriptive names
aa %>% name_issues(mutate = "expand")

### split and expand
aa %>% name_issues(mutate = "split_expand")

### split, expand, and remove an issue class
aa %>% name_issues(-bbmn, mutate = "split_expand")

## Or you can use name_issues without %>%
name_issues(aa, -bbmn, mutate = "split_expand")

## End(Not run)

Description

This service uses fuzzy lookup so that you can put in partial names and you should get back those things that match. See examples below.

Faceting: If facet=FALSE or left to the default (NULL), no faceting is done. And therefore, all parameters with facet in their name are ignored (facetOnly, facetMincount, facetMultiselect).

Usage

name_lookup(
  query = NULL,
  rank = NULL,
  higherTaxonKey = NULL,
  status = NULL,
  isExtinct = NULL,
  habitat = NULL,
  nameType = NULL,
  datasetKey = NULL,
  origin = NULL,
  nomenclaturalStatus = NULL,
  limit = 100,
  start = 0,
  facet = NULL,
  facetMincount = NULL,
  facetMultiselect = NULL,
  type = NULL,
  hl = NULL,
  issue = NULL,
  constituentKey = NULL,
  verbose = FALSE,
  return = NULL,
  curlopts = list()
)

Arguments

Value

An object of class gbif, which is a S3 class list, with slots for metadata (meta), the data itself (data), the taxonomic hierarchy data (hierarchies), and vernacular names (names). In addition, the object has attributes listing the user supplied arguments and type of search, which is, differently from occurrence data, always equals to 'single' even if multiple values for some parameters are given. meta is a list of length four with offset, limit, endOfRecords and count fields. data is a tibble (aka data.frame) containing all information about the found taxa. hierarchies is a list of data.frame's, one per GBIF key (taxon), containing its taxonomic classification. Each data.frame contains two columns: rankkey and name. names returns a list of data.frame's, one per GBIF key (taxon), containing all vernacular names. Each data.frame contains two columns: vernacularName and language.

A list of length five:

• metadata

• data: either a data.frame (verbose=FALSE, default) or a list (verbose=TRUE).

• facets

• hierarchies

• names

Repeat parameter inputs

Some parameters can take many inputs, and treated as 'OR' (e.g., a or b or c). The following take many inputs:

• rank

• higherTaxonKey

• status

• habitat

• nameType

• datasetKey

• origin

References

https://www.gbif.org/developer/species#searching

Examples

## Not run: 
# Look up names like mammalia
name_lookup(query='mammalia', limit = 20)

# Start with an offset
name_lookup(query='mammalia', limit=1)
name_lookup(query='mammalia', limit=1, start=2)

# large requests (paging is internally implemented).
# hard maximum limit set by GBIF API: 99999
# name_lookup(query = "Carnivora", limit = 10000)

# Get all data and parse it, removing descriptions which can be quite long
out <- name_lookup('Helianthus annuus', rank="species", verbose=TRUE)
lapply(out$data, function(x) {
  x[!names(x) %in% c("descriptions","descriptionsSerialized")]
})

# Search for a genus
name_lookup(query="Cnaemidophorus", rank="genus")
# Limit records to certain number
name_lookup('Helianthus annuus', rank="species", limit=2)

# Query by habitat
name_lookup(habitat = "terrestrial", limit=2)
name_lookup(habitat = "marine", limit=2)
name_lookup(habitat = "freshwater", limit=2)

# Using faceting
name_lookup(facet='status', limit=0, facetMincount='70000')
name_lookup(facet=c('status','higherTaxonKey'), limit=0,
  facetMincount='700000')

name_lookup(facet='nameType', limit=0)
name_lookup(facet='habitat', limit=0)
name_lookup(facet='datasetKey', limit=0)
name_lookup(facet='rank', limit=0)
name_lookup(facet='isExtinct', limit=0)

name_lookup(isExtinct=TRUE, limit=0)

# text highlighting
## turn on highlighting
res <- name_lookup(query='canada', hl=TRUE, limit=5)
res$data
name_lookup(query='canada', hl=TRUE, limit=45)
## and you can pass the output to gbif_names() function
res <- name_lookup(query='canada', hl=TRUE, limit=5)
gbif_names(res)

# Lookup by datasetKey (set up sufficient high limit, API maximum: 99999)
# name_lookup(datasetKey='3f8a1297-3259-4700-91fc-acc4170b27ce',
#   limit = 50000)

# Some parameters accept many inputs, treated as OR
name_lookup(rank = c("family", "genus"))
name_lookup(higherTaxonKey = c("119", "120", "121", "204"))
name_lookup(status = c("misapplied", "synonym"))$data
name_lookup(habitat = c("marine", "terrestrial"))
name_lookup(nameType = c("cultivar", "doubtful"))
name_lookup(datasetKey = c("73605f3a-af85-4ade-bbc5-522bfb90d847",
  "d7c60346-44b6-400d-ba27-8d3fbeffc8a5"))
name_lookup(datasetKey = "289244ee-e1c1-49aa-b2d7-d379391ce265",
  origin = c("SOURCE", "DENORMED_CLASSIFICATION"))

# Pass on curl options
name_lookup(query='Cnaemidophorus', rank="genus",
  curlopts = list(verbose = TRUE))

## End(Not run)

Description

Parse taxon names using the GBIF name parser.

Usage

name_parse(scientificname, curlopts = list())

Arguments

Value

A data.frame containing fields extracted from parsed taxon names. Fields returned are the union of fields extracted from all species names in scientificname.

Author(s)

John Baumgartner ([email protected])

References

https://www.gbif.org/developer/species#parser

Examples

## Not run: 
name_parse(scientificname='x Agropogon littoralis')
name_parse(c('Arrhenatherum elatius var. elatius',
             'Secale cereale subsp. cereale', 'Secale cereale ssp. cereale',
             'Vanessa atalanta (Linnaeus, 1758)'))
name_parse("Ajuga pyramidata")
name_parse("Ajuga pyramidata x reptans")

# Pass on curl options
# res <- name_parse(c('Arrhenatherum elatius var. elatius',
#          'Secale cereale subsp. cereale', 'Secale cereale ssp. cereale',
#          'Vanessa atalanta (Linnaeus, 1758)'), curlopts=list(verbose=TRUE))

## End(Not run)

Description

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.

Usage

name_suggest(
  q = NULL,
  datasetKey = NULL,
  rank = NULL,
  fields = NULL,
  start = NULL,
  limit = 100,
  curlopts = list()
)

Arguments

Value

A list, with two elements data (tibble) and hierarchy (list of data.frame's). If 'higherClassificationMap' is one of the fields requested, then hierarchy is a list of data.frame's; if not included, hierarchy is an empty list.

Repeat parmeter inputs

Some parameters can take many inputs, and treated as 'OR' (e.g., a or b or c). The following take many inputs:

• rank

• datasetKey

References

https://www.gbif.org/developer/species#searching

Examples

## Not run: 
name_suggest(q='Puma concolor')
name_suggest(q='Puma')
name_suggest(q='Puma', rank="genus")
name_suggest(q='Puma', rank="subspecies")
name_suggest(q='Puma', rank="species")
name_suggest(q='Puma', rank="infraspecific_name")

name_suggest(q='Puma', limit=2)
name_suggest(q='Puma', fields=c('key','canonicalName'))
name_suggest(q='Puma', fields=c('key','canonicalName',
  'higherClassificationMap'))

# Some parameters accept many inputs, treated as OR
name_suggest(rank = c("family", "genus"))
name_suggest(datasetKey = c("73605f3a-af85-4ade-bbc5-522bfb90d847",
  "d7c60346-44b6-400d-ba27-8d3fbeffc8a5"))

# If 'higherClassificationMap' in fields, a list is returned
name_suggest(q='Puma', fields=c('key','higherClassificationMap'))

# Pass on curl options
name_suggest(q='Puma', limit=200, curlopts = list(verbose=TRUE))

## End(Not run)

Description

Lookup details for specific names in all taxonomies in GBIF.

Usage

name_usage(
  key = NULL,
  name = NULL,
  data = "all",
  language = NULL,
  datasetKey = NULL,
  uuid = NULL,
  rank = NULL,
  shortname = NULL,
  start = 0,
  limit = 100,
  return = NULL,
  curlopts = list()
)

Arguments

Details

This service uses fuzzy lookup so that you can put in partial names and you should get back those things that match. See examples below.

This function is different from name_lookup() in that that function searches for names. This function encompasses a bunch of API endpoints, most of which require that you already have a taxon key, but there is one endpoint that allows name searches (see examples below).

Note that data="verbatim" hasn't been working.

Options for the data parameter are: 'all', 'verbatim', 'name', 'parents', 'children', 'related', 'synonyms', 'descriptions','distributions', 'media', 'references', 'speciesProfiles', 'vernacularNames', 'typeSpecimens', 'root', 'iucnRedListCategory'

This function used to be vectorized with respect to the data parameter, where you could pass in multiple values and the function internally loops over each option making separate requests. This has been removed. You can still loop over many options for the data parameter, just use an lapply family function, or a for loop, etc.

See name_issues() for more information about issues in issues column.

Value

An object of class gbif, which is a S3 class list, with slots for metadata (meta) and the data itself (data). In addition, the object has attributes listing the user supplied arguments and type of search, which is, differently from occurrence data, always equals to 'single' even if multiple values for some parameters are given. meta is a list of length four with offset, limit, endOfRecords and count fields. data is a tibble (aka data.frame) containing all information about the found taxa.

Repeat parameter inputs

These parameters used to accept many inputs, but no longer do:

• rank

• name

• langugae

• datasetKey

References

https://www.gbif.org/developer/species#nameUsages

Examples

## Not run: 
# A single name usage
name_usage(key=1)

# Name usage for a taxonomic name
name_usage(name='Puma', rank="GENUS")

# Name usage for all taxa in a dataset
# (set sufficient high limit, but less than 100000)
# name_usage(datasetKey = "9ff7d317-609b-4c08-bd86-3bc404b77c42", 
#  limit = 10000)
# All name usages
name_usage()

# References for a name usage
name_usage(key=2435099, data='references')

# Species profiles, descriptions
name_usage(key=3119195, data='speciesProfiles')
name_usage(key=3119195, data='descriptions')
name_usage(key=2435099, data='children')

# Vernacular names for a name usage
name_usage(key=3119195, data='vernacularNames')

# Limit number of results returned
name_usage(key=3119195, data='vernacularNames', limit=3)

# Search for names by dataset with datasetKey parameter
name_usage(datasetKey="d7dddbf4-2cf0-4f39-9b2a-bb099caae36c")

# Search for a particular language
name_usage(key=3119195, language="FRENCH", data='vernacularNames')

# get root usage with a uuid
name_usage(data = "root", uuid = "73605f3a-af85-4ade-bbc5-522bfb90d847")

# search by language
name_usage(language = "spanish")

# Pass on curl options
name_usage(name='Puma concolor', limit=300, curlopts = list(verbose=TRUE))

# look up iucn red list category 
name_usage(key = 7707728, data = 'iucnRedListCategory') 

## End(Not run)

Description

Get data about GBIF networks

Usage

network(
  data = "all",
  uuid = NULL,
  query = NULL,
  identifier = NULL,
  identifierType = NULL,
  limit = 100,
  start = NULL,
  curlopts = list()
)

network_constituents(uuid = NULL, limit = 100, start = 0)

Arguments

Details

identifierType options:

• DOI No description.

• FTP No description.

• GBIF_NODE Identifies the node (e.g: DK for Denmark, sp2000 for Species 2000).

• GBIF_PARTICIPANT Participant identifier from the GBIF IMS Filemaker system.

• GBIF_PORTAL Indicates the identifier originated from an auto_increment column in the portal.data_provider or portal.data_resource table respectively.

• HANDLER No description.

• LSID Reference controlled by a separate system, used for example by DOI.

• SOURCE_ID No description.

• UNKNOWN No description.

• URI No description.

• URL No description.

• UUID No description.

Get various information about GBIF networks. network_constituents() is a convenience function that allows you to get all the datasets in a network.

Value

• network() returns a list

• network_constituents() returns a data.frame of datasets in the network

References

https://www.gbif.org/developer/registry#networks

Examples

## Not run: 
network()
network(uuid='2b7c7b4f-4d4f-40d3-94de-c28b6fa054a6')

network_constituents('2b7c7b4f-4d4f-40d3-94de-c28b6fa054a6')

# curl options
network(curlopts = list(verbose=TRUE))

## End(Not run)

Description

Networks metadata.

Usage

networks(
  data = "all",
  uuid = NULL,
  query = NULL,
  identifier = NULL,
  identifierType = NULL,
  limit = 100,
  start = NULL,
  curlopts = list()
)

Arguments

Details

identifierType options:

• DOI No description.

• FTP No description.

• GBIF_NODE Identifies the node (e.g: DK for Denmark, sp2000 for Species 2000).

• GBIF_PARTICIPANT Participant identifier from the GBIF IMS Filemaker system.

• GBIF_PORTAL Indicates the identifier originated from an auto_increment column in the portal.data_provider or portal.data_resource table respectively.

• HANDLER No description.

• LSID Reference controlled by a separate system, used for example by DOI.

• SOURCE_ID No description.

• UNKNOWN No description.

• URI No description.

• URL No description.

• UUID No description.

References

https://www.gbif.org/developer/registry#networks

Examples

## Not run: 
networks()
networks(uuid='2b7c7b4f-4d4f-40d3-94de-c28b6fa054a6')

# curl options
networks(curlopts = list(verbose=TRUE))

## End(Not run)

Description

Nodes metadata.

Usage

nodes(
  data = "all",
  uuid = NULL,
  query = NULL,
  identifier = NULL,
  identifierType = NULL,
  limit = 100,
  start = NULL,
  isocode = NULL,
  curlopts = list()
)

Arguments

Details

identifierType options:

• DOI No description.

• FTP No description.

• GBIF_NODE Identifies the node (e.g: DK for Denmark, sp2000 for Species 2000).

• GBIF_PARTICIPANT Participant identifier from the GBIF IMS Filemaker system.

• GBIF_PORTAL Indicates the identifier originated from an auto_increment column in the portal.data_provider or portal.data_resource table respectively.

• HANDLER No description.

• LSID Reference controlled by a separate system, used for example by DOI.

• SOURCE_ID No description.

• UNKNOWN No description.

• URI No description.

• URL No description.

• UUID No description.

References

https://www.gbif.org/developer/registry#nodes

Examples

## Not run: 
nodes(limit=5)
nodes(uuid="1193638d-32d1-43f0-a855-8727c94299d8")
nodes(data='identifier', uuid="03e816b3-8f58-49ae-bc12-4e18b358d6d9")
nodes(data=c('identifier','organization','comment'),
  uuid="03e816b3-8f58-49ae-bc12-4e18b358d6d9")

uuids = c("8cb55387-7802-40e8-86d6-d357a583c596",
  "02c40d2a-1cba-4633-90b7-e36e5e97aba8",
  "7a17efec-0a6a-424c-b743-f715852c3c1f",
  "b797ce0f-47e6-4231-b048-6b62ca3b0f55",
  "1193638d-32d1-43f0-a855-8727c94299d8",
  "d3499f89-5bc0-4454-8cdb-60bead228a6d",
  "cdc9736d-5ff7-4ece-9959-3c744360cdb3",
  "a8b16421-d80b-4ef3-8f22-098b01a89255",
  "8df8d012-8e64-4c8a-886e-521a3bdfa623",
  "b35cf8f1-748d-467a-adca-4f9170f20a4e",
  "03e816b3-8f58-49ae-bc12-4e18b358d6d9",
  "073d1223-70b1-4433-bb21-dd70afe3053b",
  "07dfe2f9-5116-4922-9a8a-3e0912276a72",
  "086f5148-c0a8-469b-84cc-cce5342f9242",
  "0909d601-bda2-42df-9e63-a6d51847ebce",
  "0e0181bf-9c78-4676-bdc3-54765e661bb8",
  "109aea14-c252-4a85-96e2-f5f4d5d088f4",
  "169eb292-376b-4cc6-8e31-9c2c432de0ad",
  "1e789bc9-79fc-4e60-a49e-89dfc45a7188",
  "1f94b3ca-9345-4d65-afe2-4bace93aa0fe")

res <- lapply(uuids, function(x) nodes(x, data='identifier')$data)
res <- res[!sapply(res, NROW)==0]
res[1]

# Pass on curl options
nodes(limit=20, curlopts=list(verbose=TRUE))

## End(Not run)

Description

Get number of occurrence records.

Usage

occ_count(..., occurrenceStatus = "PRESENT", curlopts = list())

Arguments

Details

occ_count() is a short convenience wrapper for occ_search(limit=0)$meta$count.

The current version (since rgbif 3.7.6) of occ_count() uses a different GBIF API endpoint from previous versions. This change greatly improves the usability of occ_count(). Legacy parameters georeferenced, type, date, to, from are no longer supported and not guaranteed to work correctly.

Multiple values of the type c("a","b") will give an error, but "a;b" will work.

Value

The occurrence count of the occ_search() query.

See Also

occ_count_year(), occ_count_country(), occ_count_pub_country(), occ_count_basis_of_record()

Examples

## Not run: 
# total occurrences mediated by GBIF
occ_count() # should be > 2 billion! 

# number of plant occurrences
occ_count(kingdomKey=name_backbone("Plantea")$usageKey) 
occ_count(scientificName = 'Ursus americanus')

occ_count(country="DK") # found in Denmark 
occ_count(country="DK;US") # found in Denmark and United States
occ_count(publishingCountry="US") # published by the United States
# number of repatriated eBird records in India
occ_count(repatriated = TRUE,country="IN") 
 
occ_count(taxonKey=212) # number of bird occurrences
# between years 1800-1900
occ_count(basisOfRecord="PRESERVED_SPECIMEN", year="1800,1900") 
occ_count(recordedBy="John Waller") # recorded by John Waller
occ_count(decimalLatitude=0, decimalLongitude=0) # exactly on 0,0

# close to a known iso2 centroid
occ_count(distanceFromCentroidInMeters="0,2000") 
# close to a known iso2 centroid in Sweden
occ_count(distanceFromCentroidInMeters="0,2000",country="SE") 

occ_count(hasCoordinate=TRUE) # with coordinates
occ_count(protocol = "DIGIR") # published using DIGIR format
occ_count(mediaType = 'StillImage') # with images

# number of occurrences iucn status "critically endangered"
occ_count(iucnRedListCategory="CR") 
occ_count(verbatimScientificName="Calopteryx splendens;Calopteryx virgo")
occ_count(
geometry="POLYGON((24.70938 48.9221,24.71056 48.92175,24.71107
 48.92296,24.71002 48.92318,24.70938 48.9221))")

# getting a table of counts using the facets interface
# occurrence counts by year
occ_count(facet="year")
occ_count(facet="year",facetLimit=400)

# top scientificNames from Japan
occ_count(facet="scientificName",country="JP")
# top countries publishing specimen bird records between 1850 and 1880
occ_count(facet="scientificName",taxonKey=212,basisOfRecord="PRESERVED_SPECIMEN"
,year="1850,1880")

# Number of present or absence records of Elephants
occ_count(facet="occurrenceStatus",scientificName="Elephantidae")

# top 100 datasets publshing occurrences to GBIF
occ_count(facet="datasetKey",facetLimit=100)
# top datasets publishing country centroids on GBIF
occ_count(facet="datasetKey",distanceFromCentroidInMeters="0")

# common values for coordinateUncertaintyInMeters for museum specimens
occ_count(facet="coordinateUncertaintyInMeters",basisOfRecord="PRESERVED_SPECIMEN")

# number of iucn listed bird and insect occurrences in Mexico
occ_count(facet="iucnRedListCategory",taxonKey="212;216",country="MX")

# most common latitude values mediated by GBIF
occ_count(facet="decimalLatitude")

# top iNaturalist users publishing research-grade obs to GBIF
occ_count(facet="recordedBy",datasetKey="50c9509d-22c7-4a22-a47d-8c48425ef4a7")
# top 100 iNaturalist users from Ukraine
occ_count(facet="recordedBy",datasetKey="50c9509d-22c7-4a22-a47d-8c48425ef4a7"
,country="UA",facetLimit=100)

# top institutions publishing specimen occurrences to GBIF
occ_count(facet="institutionCode",basisOfRecord="PRESERVED_SPECIMEN")


## End(Not run)

Description

Get quick pre-computed occurrence counts of a limited number of dimensions.

Usage

occ_count_country(publishingCountry = NULL)

occ_count_pub_country(country = NULL)

occ_count_year(year = NULL)

occ_count_basis_of_record(curlopts = list())

Arguments

Details

Get quick pre-computed counts of a limited number of dimensions.

occ_count_country() will return a data.frame with occurrence counts by country. By using occ_count_country(publishingCountry="DK") will return the occurrence contributions Denmark has made to each country.

occ_count_pub_country() will return a data.frame with occurrence counts by publishing country. Using occ_count_pub_country(country="DK"), will return the occurrence contributions each country has made to that focal country=DK.

occ_count_year() will return a data.frame with the total occurrences mediated by GBIF for each year. By using occ_counts_year(year="1800,1900") will only return counts for that range.

occ_count_basis_of_record() will return a data.frame with total occurrences mediated by GBIF for each basis of record.

Value

A data.frame of counts.

See Also

occ_count()

Examples

## Not run: 
# total occurrence counts for all countries and iso2 places
occ_count_country()  
# the occurrences Mexico has published in other countries 
occ_count_country("MX") 
# the occurrences Denmark has published in other countries 
occ_count_country("DK")

# the occurrences other countries have published in Denmark
occ_count_pub_country("DK")
# the occurrences other countries have published in Mexico
occ_count_pub_country("MX")

# total occurrence counts for each year that an occurrence was 
# recorded or collected.
occ_count_year()
# supports ranges
occ_count_year("1800,1900")

# table of occurrence counts by basis of record
occ_count_basis_of_record()


## End(Not run)

Description

Legacy alternative to occ_search

Usage

occ_data(
  taxonKey = NULL,
  scientificName = NULL,
  country = NULL,
  publishingCountry = NULL,
  hasCoordinate = NULL,
  typeStatus = NULL,
  recordNumber = NULL,
  lastInterpreted = NULL,
  continent = NULL,
  geometry = NULL,
  geom_big = "asis",
  geom_size = 40,
  geom_n = 10,
  recordedBy = NULL,
  recordedByID = NULL,
  identifiedByID = NULL,
  basisOfRecord = NULL,
  datasetKey = NULL,
  eventDate = NULL,
  catalogNumber = NULL,
  year = NULL,
  month = NULL,
  decimalLatitude = NULL,
  decimalLongitude = NULL,
  elevation = NULL,
  depth = NULL,
  institutionCode = NULL,
  collectionCode = NULL,
  hasGeospatialIssue = NULL,
  issue = NULL,
  search = NULL,
  mediaType = NULL,
  subgenusKey = NULL,
  repatriated = NULL,
  phylumKey = NULL,
  kingdomKey = NULL,
  classKey = NULL,
  orderKey = NULL,
  familyKey = NULL,
  genusKey = NULL,
  speciesKey = NULL,
  establishmentMeans = NULL,
  degreeOfEstablishment = NULL,
  protocol = NULL,
  license = NULL,
  organismId = NULL,
  publishingOrg = NULL,
  stateProvince = NULL,
  waterBody = NULL,
  locality = NULL,
  occurrenceStatus = "PRESENT",
  gadmGid = NULL,
  coordinateUncertaintyInMeters = NULL,
  verbatimScientificName = NULL,
  eventId = NULL,
  identifiedBy = NULL,
  networkKey = NULL,
  verbatimTaxonId = NULL,
  occurrenceId = NULL,
  organismQuantity = NULL,
  organismQuantityType = NULL,
  relativeOrganismQuantity = NULL,
  iucnRedListCategory = NULL,
  lifeStage = NULL,
  isInCluster = NULL,
  distanceFromCentroidInMeters = NULL,
  skip_validate = TRUE,
  limit = 500,
  start = 0,
  curlopts = list(http_version = 2)
)

Arguments