IDigBio API v1 Specification

From iDigBio
Revision as of 09:14, 16 May 2014 by Dstoner (talk | contribs) (convert sections to use dl and indented li)
Jump to navigation Jump to search


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.

iDigBio Data and Schema

Data elements generally conform to the Biodiversity Information Standards (also known as the Taxonomic Databases Working Group or TDWG) Darwin Core and Audobon Core.

The iDigBio Data Ingestion Requirements and Guidelines may be useful to understand how data becomes available in iDigBio.

Endpoints

Unless otherwise noted, successful responses from the API will return a JSON-formatted document.

Additional usage examples beyond those provided in this document, including more information on the "curl" command, are available in iDigBio API Examples.

GET /

Description
Returns a list of top-level api_version or service URLs
Resource URL
http://api.idigbio.org/
Parameters
None
Sample Usage
$ curl -s http://api.idigbio.org/ | json_pp
{
   "v1" : "http://api.idigbio.org/v1/",
   "check" : "http://api.idigbio.org/check",
   "v0" : "http://api.idigbio.org/v0/"
}

GET /{api_version}

Description
Returns a list of top-level API feature types for a particular version of the API
Resource URL
http://api.idigbio.org/v1
Parameters
None
Sample Usage
$ curl -s http://api.idigbio.org/v1 | json_pp
{
   "aggregates" : "http://api.idigbio.org/v1/aggregates",
   "records" : "http://api.idigbio.org/v1/records",
   "mediaaps" : "http://api.idigbio.org/v1/mediaaps",
   "taxa" : "http://api.idigbio.org/v1/taxa",
   "people" : "http://api.idigbio.org/v1/people",
   "organizations" : "http://api.idigbio.org/v1/organizations",
   "recordsets" : "http://api.idigbio.org/v1/recordsets",
   "mediarecords" : "http://api.idigbio.org/v1/mediarecords"
}
Notes
Some of the listed feature types may deprecated. This will be noted elsewhere in the API specification document.

GET /v1/aggregates

Description
Deprecated, do not use.

GET /v1/mediaaps

Description
Deprecated, do not use.

GET /v1/mediarecords

Description
Returns a collection of Media Record IDs
Resource URL
http://api.idigbio.org/v1/mediarecords
Parameters
        1. need table
Sample Usage
# CURL SOMETHING

GET /v1/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 Usage
# CURL SOMETHING

GET /v1/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 Usage
# CURL SOMETHING with -L to follow redirects

GET /v1/records

Description
Returns a collection of record IDs
Resource URL
http://api.idigbio.org/v1/records
Parameters
  • something goes here
Sample Usage
# CURL SOMETHING

GET /v1/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 Usage
# CURL SOMETHING

GET /v1/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 Usage
# CURL SOMETHING with -L to watch redirects

GET /v1/publishers

Description
Returns a collection of publisher IDs
Resource URL
http://api.idigbio.org/v1/publishers


Parameters
  • something goes here
Sample Usage
# CURL SOMETHING

GET /v1/organizations

Description
Deprecated, do not use.

GET /v1/people

Description
Deprecated, do not use.

GET /v1/publishers/{ID}

Description
Returns a publisher with specific entity ID
Resource URL
http://api.idigbio.org/v1/publishers/{ID}
Parameters
  • something goes here
Sample Usage
# CURL SOMETHING

GET /v1/recordsets

Description
Returns a collection of recordset IDs
Resource URL
http://api.idigbio.org/v1/recordsets
Parameters
  • something goes here
Sample Usage
# CURL SOMETHING

GET /v1/recordsets/{ID}

Description
Returns a recordset with specific entity ID
Resource URL
http://api.idigbio.org/v1/recordsets/{ID}
Parameters
  • something goes here
Sample Usage
# CURL SOMETHING

GET /v1/taxa

Description
Deprecated, do not use.


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.

There is also an elasticsearch Google Group available.

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

Examples specific to iDigBio are available in iDigBio API Examples.

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 search terms for Media Records queries using Elasticsearch at this time.

Retrieved from "http://www.idigbio.org/wiki/index.php?title=IDigBio_API_v1_Specification&oldid=9793"