Skip to content

Code Samples

Jump to bottom Edit New page
Dan Stoner edited this page Apr 30, 2015 · 25 revisions

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).

The iDigBio python client library can be installed via pip:

$ pip install idigbio

A python code sample that uses the iDigBio python client to create a dataframe for use by the pandas data analysis toolset:

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

A comparison of code to fetch 10 records matching the scientific name 'Puma concolor' and print the verbatim locality field.

"""                                                                                                                                 
Using the iDigBio python client library, fetch 10 records matching the                                                                     
scientific name 'Puma concolor' and print the verbatim locality field.                                                              
"""

import idigbio

query = {"scientificname":"puma concolor"}

api = idigbio.json()

record_list = api.search_records(rq=query,limit=10)

for item in record_list["items"]:
      for key in item["indexTerms"]:
          if key == "verbatimlocality":
              print item["indexTerms"]["verbatimlocality"]
"""                                                                                                                                 
Using the iDigBio API directly, fetch 10 records matching the                                                                       
scientific name 'Puma concolor' and print the verbatim locality field.                                                              
"""

import requests

query_as_string = '{"rq":{"scientificname":"puma concolor"},"limit":10}'

r = requests.post('http://beta-search.idigbio.org/v2/search/records/',data=query_as_string, headers={'content-type': 'application/j\
son'})

response_json = r.json()

for item in response_json["items"]:
     for key in item["indexTerms"]:
          if key == "verbatimlocality":
               print item["indexTerms"]["verbatimlocality"]

Both versions will give output similar to the following:

usa | nm | eddy | sabertooth camel maze, dry cave; pecos river
usa | nm | eddy | room of the vanishing floor, dry cave; pecos river
usa | nm | eddy | sabertooth camel maze, dry cave; pecos river
usa | tx | hudspeth | sierra diablo cave; rio grande
usa | nm | hidalgo | u-bar cave, la 5689; internal - playas valley
usa | nm | eddy | animal fair, dry cave; pecos river
usa | nm | eddy | sabertooth camel maze, dry cave; pecos river
usa | nm | eddy | sabertooth camel maze, dry cave; pecos river
usa | nm | eddy | lost valley, dry cave; pecos river
usa | nm | eddy | sabertooth camel maze, dry cave; pecos river

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.

Add a custom footer
Add a custom sidebar

Clone this wiki locally