IDigBio API

iDigBio API Overview

This document serves as the starting page of official documentation for the iDigBio Application Programming Interface (API).

Integrated Digitized Biocollections (iDigBio) is the National Resource for Advancing Digitization of Biodiversity Collections (ADBC) funded by the National Science Foundation. Through ADBC, data and images for millions of biological specimens are being made available in electronic format for the research community, government agencies, students, educators, and the general public. iDigBio is a data aggregator. This means that data is provided to iDigBio through various publishing mechanisms.

Many consumers of the iDigBio aggregated data will choose to use the iDigBio Portal web site. Additionally, to facilitate integration of iDigBio data with other web sites, services, or research uses, iDigBio provides an API.

The iDigBio API is an abstraction layer for retrieving data from the iDigBio back-end data systems. This abstraction allows reuse and mashup of aggregated data without needing to understand the complex underlying details of the back-end data storage. Currently, the public API supports HTTP GET and POST requests for data read operations only. The iDigBio API is a RESTful web service that delivers data primarily as JSON documents.

iDigBio API Mailing List

Please join our list at idigbio-api-users-l@lists.ufl.edu if you are using our APIs. Besides providing notification of API changes, the mailing list gives direct access to the iDigBio API developers and is a good place to ask questions or give and receive feedback.

You can join via the web at: http://lists.ufl.edu/cgi-bin/wa?A0=IDIGBIO-API-USERS-L

Specification

The iDigBio API v2 / iDigBio Search API specification includes detailed information about the Search API endpoints, parameters, query format, values, and returns. It is available in the github wiki associated with the code repository. The iDigBio Search API was released to production in June 2015.

iDigBio transitioned from version 1 to version 2 (v1 to v2) of the API. All v1 endpoints and documentation should be considered deprecated, even if they continue to function. Programmers who are interested in accessing data directly in iDigBio via an API should consult the v2 API documentation. The v2 API is also known as the iDigBio Search API.

The now-deprecated iDigBio API v1 Specification includes detailed information about the old v1 API endpoints, parameters, values, and returns. In most cases, the only reason to use the v1 API was to retrieve raw, unprocessed versions of a record (e.g. no iDigBio data quality enhancements) or to access previous versions of a particular record.

Examples

See iDigBio API v2 / iDigBio Search API Examples in the idigbio-search-api github wiki.

Quick Start

iDigBio API endpoints follow the general form:

https://search.idigbio.org/{api_version}/{endpoint}{optional_parameters}

In nearly all cases, a successful API request returns data as a JSON-formatted document.

Many error cases will also return a JSON-formatted document rather than a bare HTTP status failure.

Searching iDigBio

Search Portal and Bulk Record Downloads

The easiest method for searching iDigBio is to use the Portal website search features, not the API. The portal also provides bulk download capabilities for acquiring larger sets of data. See: https://www.idigbio.org/portal

Search API

The iDigBio Search API has be released and the June 2015 version of the portal is based on this API.

Other APIs

iDigBio Download API

Media API Working Docs

Specimen Web Map Module

The iDigBio Portal Search page map is also provided as a stand-alone module for use in any third-party web site. Go to the Specimen Map page for details on using the map.

Elasticsearch Overview

Direct queries to the iDigBio Elasticsearch service are deprecated. The iDigBio Search API should be used instead.

The public-facing interface to the iDigBio back-end Elasticsearch system is deprecated and will likely be disabled at some point in the future.

Full Recordset Downloads

Instead of generating large queries in the portal or with the API, it may be easier to download iDigBio data from regular dumps of all data in iDigBio. These dumps are available from s.idigbio.org. This is an S3-compatible object store (although it can be treated as a web server if that is easier) that contains .zip files of each record set in iDigBio named by recordset uuid as well as files containing all data across all records sets.

Client Libraries

Client libraries, packages, and modules are pieces of software that make it easier to interface with the iDigBio API. The following list includes the known iDigBio libraries that are currently available.

ridigbio R Package for Search API

R is a free software environment for statistical computing and graphics. It compiles and runs on a wide variety of UNIX platforms, Windows and MacOS.

The production version of this package is in CRAN. The latest development version is available at https://github.com/idigbio/ridigbio

The ridigbio R package is an "official" client library in the iDigBio code repository.

iDigBio Python Library for Search API

The Python client library is available via PyPI:

https://pypi.python.org/pypi/idigbio

or just use pip:

pip install idigbio

The client code can also be found at github if you wish to help develop the library:

https://github.com/idigbio/idigbio-python-client/

The iDigBio Python library is an "official" client library in the iDigBio code repository.

idigbio_client Ruby Gem

The idigbio_client ruby gem is available:

https://rubygems.org/gems/idigbio_client

which can be installed via:

gem install idigbio_client

The idigbio_client ruby gem is a "community-supported" client library with software repository currently at:

https://github.com/GlobalNamesArchitecture/idigbio_client

Suggestions?

If you are in need of other client libraries or iDigBio API features, please use the feedback button to submit your request.