Code Samples

This page will include samples of code against the iDigBio Search API.

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

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.

cURL

GET requests with curl

Consider a query string in the iDigBio query format (JSON) to search for a particular scientific name:

{
  "rq": {
    "scientificname": "puma concolor"
  }
}

without whitespace, still valid JSON, becomes:

{"rq":{"scientificname":"puma concolor"}}

becomes the following when url-encoded:

rq=%7B%22scientificname%22%3A+%22puma+concolor%22%7D

The query request via HTTP GET with a curl command, adding a limit of 5:

$ curl -s 'http://beta-search.idigbio.org/v2/search/records/?rq=%7B%22scientificname%22%3A+%22puma+concolor%22%7D&limit=5'

If we pipe the result to 'json_pp' to "prettify" and 'head' to reduce the number of output lines to 25:

$ curl -s 'http://beta-search.idigbio.org/v2/search/records/?rq=%7B%22scientificname%22%3A+%22puma+concolor%22%7D&limit=5' | json_pp | head -n 25

The search API responds with something like the following:

{
   "items" : [
      {
         "data" : {
            "dwc:eventDate" : "1968-04-11",
            "dwc:recordedBy" : "Harris, Arthur H. (Van Goebel)",
            "dwc:occurrenceStatus" : "present",
            "dwc:catalogNumber" : "5-298",
            "dwc:maximumElevationInMeters" : "1280",
            "dwc:locationRemarks" : "See site 22 for Dry Cave references.",
            "dwc:institutionID" : "http://grbio.org/cool/gq95-3z97",
            "dwc:country" : "United States",
            "dwc:stateProvince" : "New Mexico",
            "dwc:month" : "4",
            "dcterms:type" : "PhysicalObject",
            "dcterms:accessRights" : "http://vertnet.org/resources/norms.html",
            "dcterms:modified" : "2015-02-20",
            "dwc:genus" : "Puma",
            "dwc:day" : "11",
            "dwc:identifiedBy" : "Harris, Arthur H.",
            "dwc:minimumElevationInMeters" : "1280",
            "dwc:higherGeography" : "| USA | NM | EDDY |  |  |  |",
            "dwc:locality" : "Sabertooth Camel Maze, Dry Cave; Pecos River",
            "dwc:individualCount" : "1",
            "dwc:institutionCode" : "UTEP",

POST requests with curl

Given a JSON query:

{
  "limit": 5,
  "rq": {
    "scientificname": "puma concolor"
  }
}

We can use curl to issue a POST rather than a GET by specifying the query in the curl data paramter (-d or --data):

$ curl -s -H "Content-Type: application/json" -d '{"limit":5,"rq":{"scientificname":"puma concolor"}}' 'http://beta-search.idigbio.org/v2/search/records'

If we place the query into a file such as pumaconcolor.json we can use the @ symbol to reference the file.

$ cat pumaconcolor.json 
{
  "limit": 5,
  "rq": {
    "scientificname": "puma concolor"
  }
}

And again, the curl request with 'json_pp' and 'head':

$ curl -s -H "Content-Type: application/json" --data @pumaconcolor.json 'http://beta-search.idigbio.org/v2/search/records' | json_pp | head
{
   "attribution" : [
      {
         "data_rights" : "Unknown License, assume Public Domain",
         "url" : "http://www.msb.unm.edu/mammals",
         "uuid" : "09b18522-5643-478f-86e9-d2e34440d43e",
         "name" : "MSB Mammal Collection (Arctos)",
         "contacts" : [
            {
               "last_name" : "Cook",
}

Python

Rather than writing python code directly at the API, consider using the [Python Client for the iDigBio Search API] (https://pypi.python.org/pypi/idigbio).

pip install idigbio
import idigbio
api = idigbio.pandas()
record_df = api.search_records(rq={"scientificname": "puma concolor"})

R

Rather than writing R code directly against the API, consider using the [ridigbio R Package for Search API] (https://github.com/idigbio/ridigbio)

install_github("idigbio/ridigbio")
library(ridgbio)
record_df <- idig_search_records(rq=list(genus="acer"), limit=10)

Javascript / jQuery

The following javascript AJAX request performs a query for specimen records of the genus "acer" that have image media records associated with them, with a limit of 5 records

$.ajax("http://beta-search.idigbio.org/v2/search/records/", 
{
    dataType: 'json',
    contentType: 'application/json',
    type: "POST",
    data: JSON.stringify({limit:5,rq:{genus:"acer",hasImage:true}})
});​

A complete HTML sample that will display the results in a web page:

<html>
<head>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
</head> 
<body>
<h2>jQuery example</h2>
<hr>
<pre id="results"></pre>

<script>
$.ajax("http://beta-search.idigbio.org/v2/search/records/", {
    dataType: 'json',
    contentType: 'application/json',
    type: "POST",
    data: JSON.stringify({limit:5,rq:{genus:"acer",hasImage:true}}),
    success: function (res) {
        $("#results").html(JSON.stringify(res,undefined,2));
    }
});
</script>

</body>
</html>

Also available in this jsfiddle.