Code Samples

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

Overview

GET requests

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

For example, a request in the iDigBio query format (JSON) 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

We get 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

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.

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

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

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

R

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

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