IDigBio API v1 Specification: Difference between revisions
(convert section to use dl and indented li) |
(convert sections to use dl and indented li) |
||
Line 20: | Line 20: | ||
Additional usage examples beyond those provided in this document, including more information on the "curl" command, are available in [[iDigBio API Examples]]. | Additional usage examples beyond those provided in this document, including more information on the "curl" command, are available in [[iDigBio API Examples]]. | ||
=== GET / === | === GET / === | ||
Line 83: | Line 82: | ||
=== GET /v1/aggregates === | === GET /v1/aggregates === | ||
Deprecated, do not use. | ;Description | ||
:Deprecated, do not use. | |||
---- | ---- | ||
=== GET /v1/mediaaps === | === GET /v1/mediaaps === | ||
Deprecated, do not use. | ;Description | ||
:Deprecated, do not use. | |||
---- | ---- | ||
Line 139: | Line 140: | ||
=== GET /v1/mediarecords/{ID}/media === | === GET /v1/mediarecords/{ID}/media === | ||
Description: Returns an image file (JPEG) associated with the specific entity ID | ;Description | ||
:Returns an image file (JPEG) associated with the specific entity ID | |||
Resource URL | ;Resource URL | ||
<pre> | <pre> | ||
Line 147: | Line 149: | ||
</pre> | </pre> | ||
Parameters | ;Parameters | ||
* something goes here | * something goes here | ||
Sample Usage | ;Sample Usage | ||
<pre> | <pre> | ||
Line 160: | Line 162: | ||
=== GET /v1/records === | === GET /v1/records === | ||
Description: Returns a collection of record IDs | ;Description | ||
:Returns a collection of record IDs | |||
Resource URL | ;Resource URL | ||
<pre> | <pre> | ||
Line 168: | Line 171: | ||
</pre> | </pre> | ||
;Parameters | |||
Parameters | |||
* something goes here | * something goes here | ||
Sample Usage | ;Sample Usage | ||
<pre> | <pre> | ||
Line 182: | Line 184: | ||
=== GET /v1/records/{ID} === | === GET /v1/records/{ID} === | ||
Description: Returns a record with the specific entity ID | ;Description | ||
:Returns a record with the specific entity ID | |||
Resource URL | ;Resource URL | ||
<pre> | <pre> | ||
Line 190: | Line 193: | ||
</pre> | </pre> | ||
;Parameters | |||
Parameters | |||
* something goes here | * something goes here | ||
Sample Usage | ;Sample Usage | ||
<pre> | <pre> | ||
# CURL SOMETHING | # CURL SOMETHING | ||
Line 203: | Line 205: | ||
=== GET /v1/records/{ID}/media === | === GET /v1/records/{ID}/media === | ||
Description: Returns an image (JPEG) associated with the specific entity ID | ;Description | ||
:Returns an image (JPEG) associated with the specific entity ID | |||
Resource URL | ;Resource URL | ||
<pre> | <pre> | ||
Line 211: | Line 214: | ||
</pre> | </pre> | ||
;Parameters | |||
Parameters | |||
* something goes here | * something goes here | ||
Sample Usage | ;Sample Usage | ||
<pre> | <pre> | ||
Line 225: | Line 227: | ||
=== GET /v1/publishers === | === GET /v1/publishers === | ||
Description: Returns a collection of publisher IDs | ;Description | ||
:Returns a collection of publisher IDs | |||
Resource URL | ;Resource URL | ||
<pre> | <pre> | ||
Line 234: | Line 237: | ||
Parameters | ;Parameters | ||
* something goes here | * something goes here | ||
Sample Usage | ;Sample Usage | ||
<pre> | <pre> | ||
Line 247: | Line 250: | ||
=== GET /v1/organizations === | === GET /v1/organizations === | ||
Deprecated, do not use. | ;Description | ||
:Deprecated, do not use. | |||
---- | ---- | ||
=== GET /v1/people === | === GET /v1/people === | ||
Deprecated, do not use. | ;Description: | ||
:Deprecated, do not use. | |||
---- | ---- | ||
=== GET /v1/publishers/{ID} === | === GET /v1/publishers/{ID} === | ||
Description: Returns a publisher with specific entity ID | ;Description | ||
:Returns a publisher with specific entity ID | |||
Resource URL | ;Resource URL | ||
<pre> | <pre> | ||
Line 265: | Line 271: | ||
</pre> | </pre> | ||
;Parameters | |||
Parameters | |||
* something goes here | * something goes here | ||
Sample Usage | ;Sample Usage | ||
<pre> | <pre> | ||
Line 279: | Line 284: | ||
=== GET /v1/recordsets === | === GET /v1/recordsets === | ||
Description: Returns a collection of recordset IDs | ;Description | ||
:Returns a collection of recordset IDs | |||
Resource URL | ;Resource URL | ||
<pre> | <pre> | ||
Line 287: | Line 293: | ||
</pre> | </pre> | ||
;Parameters | |||
Parameters | |||
* something goes here | * something goes here | ||
Sample Usage | ;Sample Usage | ||
<pre> | <pre> | ||
Line 301: | Line 306: | ||
=== GET /v1/recordsets/{ID} === | === GET /v1/recordsets/{ID} === | ||
Description: Returns a recordset with specific entity ID | ;Description | ||
:Returns a recordset with specific entity ID | |||
Resource URL | ;Resource URL | ||
<pre> | <pre> | ||
Line 309: | Line 315: | ||
</pre> | </pre> | ||
;Parameters | |||
Parameters | |||
* something goes here | * something goes here | ||
Sample Usage | ;Sample Usage | ||
<pre> | <pre> | ||
Line 323: | Line 328: | ||
=== GET /v1/taxa === | === GET /v1/taxa === | ||
Deprecated, do not use. | ;Description | ||
:Deprecated, do not use. | |||
---- | |||
== Search == | == Search == |
Revision as of 09:14, 16 May 2014
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
- 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.