-
Notifications
You must be signed in to change notification settings - Fork 5
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.
Request only certain fields in the output with the fields parameter.
fields=["scientificname","kingdom","geopoint"]
A full url-encoded would look something like:
https://search.idigbio.org/v2/search/records?fields=[%22scientificname%22,%22kingdom%22]
and produce the following results (trimmed for brevity):
{
"items" : [
{
"uuid" : "d3747526-4aa9-4193-8864-1eb10c090f9a",
"indexTerms" : {
"scientificname" : "srianta dawsoni",
"kingdom" : "animalia"
},
"data" : {},
"type" : "records"
},
{
"type" : "records",
"indexTerms" : {
"scientificname" : "netsepoye hawesi",
"kingdom" : "animalia"
},
"data" : {},
"uuid" : "8b1f86b8-2a57-4f9b-a8ae-6208af69c3de"
},
{
"uuid" : "37ac603e-c90e-4c79-9d3c-8ddfa9ec5746",
"type" : "records",
"data" : {},
"indexTerms" : {
"scientificname" : "srianta iarlis",
"kingdom" : "animalia"
}
},
{
"uuid" : "9382cb97-6371-407b-9561-28090a8b1d80",
"data" : {},
"indexTerms" : {
"kingdom" : "animalia",
"scientificname" : "orestiacanthus fergusi"
},
"type" : "records"
},
{
"uuid" : "87282c92-c2e1-41fd-8238-b92d27b70fd0",
"type" : "records",
"indexTerms" : {
"scientificname" : "falcatus falcatus",
"kingdom" : "animalia"
},
"data" : {}
},HTTPie is a cross-platform command-line http tool that may be easier to use than curl because it is smart about url encoding and query parameters. The human writing the query can focus on the query syntax instead of url encodings. HTTPie also automatically pretty-prints results.
HTTPie allows you to specify the query parameters as key-value pairs on the command line.
For example, find the identifiers (indexData.dcterms:identifier) of 5 media records that belong to a particular recordset:
$ http 'https://search.idigbio.org/v2/search/media' limit=5 fields="indexData.dcterms:identifier" mq='{"recordset":"beb74dc2-22ea-49e4-b1e3-bedb8e06e8f2"}'Perhaps you want 3 specific fields and a more complicated query, in this case looking for records with geopoints:
http 'https://search.idigbio.org/v2/search/records' limit=5 fields='["scientificname","kingdom","geopoint"]' rq='{"geopoint": {"type": "exists"}, "genus":"puma"}'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 'https://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 'https://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",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"}}' 'https://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 'https://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",
}
Rather than writing python code directly at the API, consider using the Python Client for the iDigBio Search API.
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('https://search.idigbio.org/v2/search/records/',data=query_as_string, headers={'content-type': 'application/json'})
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
Rather than writing R code directly against the API, consider using the ridigbio R Package for Search API
install_github("idigbio/ridigbio")
library(ridgbio)
record_df <- idig_search_records(rq=list(genus="acer"), limit=10)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("https://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("https://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.