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

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 indexes 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#Elasticsearch_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.