IDigBio Download API: Difference between revisions

From iDigBio
Jump to navigation Jump to search
(add fiendly and other edits.)
Line 1: Line 1:
'''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.
'''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 may not provide "friendly" error messages at this time.'''
 
== 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.
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.
Line 20: Line 23:


<pre>
<pre>
https://csv.idigbio.org/?query={Query in iDigBio query format}
https://csv.idigbio.org/?query={Query in iDigBio query format}[&email={valid email address}]
</pre>
</pre>


See [https://github.com/iDigBio/idigbio-search-api/wiki/Query-Format iDigBio query format] for more information on writing queries.
See [https://github.com/iDigBio/idigbio-search-api/wiki/Query-Format iDigBio query format] for more information on writing queries.


=== Examples ===
== Examples ==
 
Consider the following query:
 
<pre>
{ "genus" : "acer"}
</pre>
 
Without specifying an email address, we could request a download
 


<pre>
<pre>

Revision as of 13:13, 27 April 2015

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.

The download API may not provide "friendly" error messages at this time.

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}[&email={valid email address}]

See iDigBio query format for more information on writing queries.

Examples

Consider the following query:

{ "genus" : "acer"}

Without specifying an email address, we could request a download


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