The Netherlands Biodiversity API (NBA) facilitates access to the Natural History Collection at Naturalis Biodiversity Center. Next to museum specimen records and metadata, access to taxonomic classification and nomenclature, to geographical information, and to multimedia files is provided. By using the powerful Elasticsearch engine, the NBA facilitates searching for collection- and biodiversity data in near real-time. Furthermore, by incorporating information from taxonomic databases, taxonomic name resolution can be accomplished with the NBA. Persistent Uniform Resource Identifiers (PURLs) ensure that each specimen accessible via the NBA is represented by a citeable unambiguous web reference. Access to our data is provided via a RESTful interface and several clients such as the BioPortal, a web application for browsing biodiversity data that is served by the NBA. For more information about the NBA, please see our detailed documentation.
The R programming language is established as a common tool in scientific research, with growing adoption by researchers in biodiversity research. Hence, to ease the access to the NBA for researchers, we developed this R client.
nbaR aims to be a full client of the NBA API, meaning that it
implements all endpoints and the entire NBA object model. The client
thus facilitates all API queries possible. Complex objects returned
by the API, such as Specimen
or Taxon
objects are implemented as
R6
classes. This includes also objects used for querying
(QuerySpec
and QueryCondition
, respectively, see also
here).
For many queries, the full functionality of the NBA won't be
required. The package therefore offers a wrapper function for each
endpoint that does not use R6
classes but common R data structes,
such as list
and data.frame
. However, querying capabilities are
limited for these wrappers. Below we will show how to set up some
simple queries using the wrapper functions.
The data in the NBA consists of four main data types (see NBA docs):
Wrapper functions start with the data type (lower-case letter) and an
underscore (specimen_*
, taxon_*
) etc. There is a wrapper function
for each endpoint (see
here for all
endpoints); camelCase naming is replaced by snake_case. The NBA
endpoint getDistinctValues
for specimen data, for instance, is
called by the function specimen_get_distinct_values
.
Specimen services provide the interface to the Naturalis collection and to species occurrences (see here), wheras Taxon services provide data from taxonomic checklists (see here). Multimedia services give access to photos, videos and sound data (see here); Geo services store polygon data for geographical regions and nature reserves (see here).
Suppose we want to look up specimens of the genus Mola (sunfish).
To find out what field of the NBA we could query, we can use the
function specimen_get_paths()
(see ?specimen_get_paths
for
documentation).
library('nbaR') all_paths <- specimen_get_paths() head(all_paths)
Note that paths of nested objects are seperated via a .
. To search
for a specific genus, we can query the field
identifications.scientificName.genusOrMonomial
. The
specimen_query
method lets us query for a specific field, where the
query parameters are given as a named list (a named vector also
works!):
queryParams <- list("identifications.scientificName.genusOrMonomial" = "Mola") sp_data <- specimen_query(queryParams) ## how many specimens are found? nrow(sp_data) ## which fields are available? colnames(sp_data)
Return type can either be list
or data.frame
(the default). Note
that nested structures in the data frame are represented as list
columns (for instance the field associatedMultiMediaUris
). which
lists, if given, all links to multimedia resources for the specimens:
sp_data$associatedMultiMediaUris
Taxonomic information can be retrieved using the taxon_ functions. Taxon records come from two sources, the Dutch species register (Nederlands Soortregister, NSR) and the Catalogue of Life (COL).
To see how many records are from each source, we can query for all
distinct values (and counts) for a specific field (see
taxon_get_paths
) for all fields in the taxon
data:
taxon_get_distinct_values("sourceSystem.name") ## alternatively, show for sourceSystem.code taxon_get_distinct_values('sourceSystem.code')
To query, for instance all the species listed in the Catalogue of life
for the genus Mola, we can use the wrapper function taxon_query
:
## specify query parameters queryParams <- list("sourceSystem.code"="COL", "defaultClassification.genus"="Mola") ## do the query tax_data <- taxon_query(queryParams) ## access nested field 'accepted Name' -> 'specificEpithet' tax_data$acceptedName$specificEpithet
Let's see if we can find vernacular (common) names for the species Mola ramsayi:
tax_data$vernacularNames[[3]]
The Geo data type in the NBA holds polygon data for countries, Dutch municipalities etc, and Dutch nature reserves. For more information please refer to the API documentation. To retreive e.g. a polygon, encoded in the geoJSON format for a country, we can query as follows:
geo_json <- geo_get_geo_json_for_locality('Nigeria')
Multimedia items accessible via the NBA include items captured from physical specimens (e.g. photos and videos) but also from human observations (e.g. recordings of bird sounds).
As an example, we will retrieve records that represent sounds that
were recorded in the country Cape Verde. The sound data accessible
via the NBA is stored in the
Xeno-Canto database, hosted at the
Naturalis Biodiversity Center. The field sourceSystem.code
for
these records is XC
; the country of occurrence is stored in the
field gatheringEvents.country
.
queryParams <- list("sourceSystem.code"="XC", "gatheringEvents.country"="Cape Verde") mm_data <- multimedia_query(queryParams) ## Access link to Xeno-Canto database for each record: mm_data$recordURI
It is important to note that querying power is limited using the wrapper functions. They relate to basic, human readable NBA queries (see here).
The wrappers are thus designed for easy access for simple queries. In many situations it might be necessary to use the full API client which offers (almost) the entire functionality of the NBA API. Detailed documentation for the full client can be found here.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.