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 requests for data read operations only. The iDigBio API is a RESTful web service that delivers data primarily as JSON documents.

Specification

iDigBio is transitioning from version 1 to version 2 (v1 to v2) of the API. We plan to keep the v1 endpoints in production for the foreseeable future. However, most programmers who are interested in accessing data directly in iDigBio via an API are going to be interested in the new v2 features. The v2 API is also known as the iDigBio Search API.

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 is currently in beta with a target release to production by June 2015.

The iDigBio API v1 Specification includes detailed information about the v1 API endpoints, parameters, values, and returns. In most cases, the only reason to use the v1 API is 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

Examples of the iDigBio Search API in action are forthcoming.

See IDigBio API v1 Examples for examples of the iDigBio v1 API in action.

Quick Start

iDigBio API endpoints follow the general form:

http://api.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.

Examples of the iDigBio Search API in action are forthcoming.

Searching iDigBio

Search Portal and Bulk Record Downloads

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

Search API

The iDigBio Search API is currently in beta testing. The next release of the iDigBio Portal will make use of this v2 API and the new search features provided.

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.

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.

R Package Coming soon! Draft available at https://github.com/fmichonneau/ridigbio