IDigBio Download API

Note: While the download API is currently used by the production portal, it should be considered highly unstable for non-iDigBio consumers. The next revision of the API will most likely be a total rewrite, backend and front.

Overview

The Download API works by performing the requested query and building an archive. Once the archive is completed, the API provides a link to the file. If the optional email parameter is supplied on the query request, an email notification will be sent.

Large queries (and thus large archive file creation) can take multiple hours to complete.

GET requests

A query submitted as a GET request must be URL-encoded.

POST requests

A query submitted as a POST request must be supplied as JSON in the content body and specify the "Content-Type: application/json" request header.

The download service url:

https://csv.idigbio.org/?query={Query in iDigBio query format}

See iDigBio query format for more information on writing queries.

Examples

https://csv.idigbio.org/?query=<[https://github.com/iDigBio/idigbio-search-api/wiki/Query-Format idigbio query format] , not all query types are available yet>&email=<email, optional>

Example:

https://csv.idigbio.org/?query={%22genus%22:%22acer%22}

The resulting JSON will include the "status_url" field which is a link to a status page for this download query.

When the download file is generated, the "complete" field will be set to "true" and the "download_url" field will include a link to the available file.

Status Endpoint

http://csv.idigbio.org/status/<download id> (returned as "status_url" from the original download query)

Ex. http://csv.idigbio.org/status/995ed58b-01fd-4c98-893e-e0cbdfadc8fe