IDigBio API v1 Specification
API Version Information
This is the specification for v1 of the iDigBio API. Previous versions of the API continue to exist but should be considered deprecated. API users should migrate to using the current version of the API. This document supercedes iDigBio API v0 Specification.
Endpoints
GET /{api_version}/mediarecords
Description: Returns a collection of Media Record IDs
Resource URL:
http://api.idigbio.org/v1/mediarecords
Parameters:
- something goes here
Sample Result:
# CURL SOMETHING
GET /{api_version}/mediarecords/{ID}
Description: Returns a Media Record with the specific entity ID
Resource URL:
http://api.idigbio.org/v1/mediarecords/{ID}
Parameters:
- something goes here
Sample Result:
# CURL SOMETHING
GET /{api_version}/mediarecords/{ID}/media
Description: Returns an image file (JPEG) associated with the specific entity ID
Resource URL:
http://api.idigbio.org/v1/mediarecords/{ID}/media
Parameters:
- something goes here
Sample Result:
# CURL SOMETHING with -L to follow redirects
GET /{api_version}/records
Description: Returns a collection of record IDs
Resource URL:
http://api.idigbio.org/v1/records
Parameters:
- something goes here
Sample Result:
# CURL SOMETHING
GET /{api_version}/records/{ID}
Description: Returns a record with the specific entity ID
Resource URL:
http://api.idigbio.org/v1/records/{ID}
Parameters:
- something goes here
Sample result:
# CURL SOMETHING
GET /{api_version}/records/{ID}/media
Description: Returns an image (JPEG) associated with the specific entity ID
Resource URL:
http://api.idigbio.org/v1/records/{ID}/media
Parameters:
- something goes here
Sample result:
# CURL SOMETHING with -L to watch redirects
GET /{api_version}/publishers
Description: Returns a collection of publisher IDs
Resource URL:
http://api.idigbio.org/v1/publishers
Parameters:
- something goes here
Sample result:
# CURL SOMETHING
GET /{api_version}/publishers/{ID}
Description: Returns a publisher with specific entity ID
Resource URL:
http://api.idigbio.org/v1/publishers/{ID}
Parameters:
- something goes here
Sample result:
# CURL SOMETHING
GET /{api_version}/recordsets
Description: Returns a collection of recordset IDs
Resource URL:
http://api.idigbio.org/v1/recordsets
Parameters:
- something goes here
Sample result:
# CURL SOMETHING
GET /{api_version}/recordsets/{ID}
Description: Returns a recordset with specific entity ID
Resource URL:
http://api.idigbio.org/v1/recordsets/{ID}
Parameters:
- something goes here
Sample result:
# CURL SOMETHING
Search
Elasticsearch is an open source distributed document-oriented NoSQL search system. Although not technically part of the API, iDigBio exposes a public Elasticsearch interface for programmers to access advanced search functionality of iDigBio data.
The following are external links to Elasticsearch reference documentation and should be considered prerequisite reading before attempting to use the iDigBio Elasticsearch interface.
The iDigBio search index provides two document types to query on: Records (specimen records) and Media Records (media metadata). Search results are returned as JSON-formatted documents.
Each type can be queried through the following respective URLs:
| Query Type | Description | Search URL |
|---|---|---|
| Records | specimen records | https://search.idigbio.org/idigbio/records/_search |
| Media Records | media metadata records | https://search.idigbio.org/idigbio/mediarecords/_search |
The Elasticsearch Query Domain Specific Language (DSL) and Elasticsearch URI Search documents will likely be useful.
There is also an elasticsearch Google Group available.
Elasticsearch - Records
Specimen Records Query URL:
https://search.idigbio.org/idigbio/records/_search
The following terms are currently available in the index for Records type of queries to Elasticsearch:
"barcodevalue" "catalognumber" "class" "collectioncode" "collectionid" "collectionname" "collector" "commonname" "continent" "country" "county" "datecollected" "datemodified" "etag" "family" "fieldnumber" "genus" "geopoint" "hasImage" "highertaxon" "infraspecificepithet" "institutioncode" "institutionid" "institutionname" "kingdom" "locality" "maxdepth" "maxelevation" "mediarecords" "mindepth" "minelevation" "municipality" "occurenceid" "order" "phylum" "recordset" "scientificname" "specificepithet" "stateprovince" "typestatus" "uuid" "verbatimlocality" "version" "waterbody"
The values stored in these terms are converted to lowercase, so searches based on terms should use the all-lowercase version of the string.
For example, searching for "Arkansas" in stateprovince will return no records.
$ curl -s "http://search.idigbio.org/idigbio/records/_search?q=stateprovince:Arkansas" | json_pp | grep scientificname | wc -l 0
Searching for "arkansas" will return multiple records.
$ curl -s "http://search.idigbio.org/idigbio/records/_search?q=stateprovince:arkansas" | json_pp | grep scientificname | wc -l 10
See iDigBio API Examples page for more Elasticsearch examples that are specific to iDigBio.
Elasticsearch - Media Records
Media Records Query URL:
https://search.idigbio.org/idigbio/mediarecords/_search
There are no useful terms for Media Records queries using Elasticsearch at this time.