IDigBio API v1 Specification: Difference between revisions

From iDigBio
Jump to navigation Jump to search
No edit summary
 
(119 intermediate revisions by 2 users not shown)
Line 2: Line 2:
[[Category:API]]
[[Category:API]]
[[Category:Documentation]]
[[Category:Documentation]]
{{Caution|The v1 API has been superseded by [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API]. API users should migrate to using the most recent version of the API. This page remains for historical reference.}}


== API Version Information ==
== 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]].
This is the specification for v1 of the [[iDigBio API]]. The v1 API has been superceded by [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API]. API users should migrate to using the most recent version of the API. The v1 API specification supercedes [[iDigBio API v0 Specification]]. Previous versions of the API may continue to exist but should be considered deprecated.


== iDigBio Data and Schema ==
== iDigBio Data and Schema ==
Line 13: Line 15:
The  
The  
[https://www.idigbio.org/content/idigbio-data-ingestion-requirements-and-guidelines iDigBio Data Ingestion Requirements and Guidelines] may be useful to understand how data becomes available in iDigBio.
[https://www.idigbio.org/content/idigbio-data-ingestion-requirements-and-guidelines iDigBio Data Ingestion Requirements and Guidelines] may be useful to understand how data becomes available in iDigBio.
Every record that is submitted to iDigBio receives a Globally Unique Identifier (GUID) of type UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field.


== Endpoints ==
== Endpoints ==


Unless otherwise noted, successful responses from the API will return a JSON-formatted document.
'''Unless otherwise noted, a successful response from an API endpoint will return a JSON-formatted document.'''
 
The curly braces <code> { </code> and <code> } </code> in this document are used as a placeholder to indicate that a real value needs to be substituted.  For example, <code> {api_version} </code> would be replaced with the actual representation of the API version such as "v1" (without the quotes).


Most of the provided examples include a JSON formatter (such as json_pp) to make the output easier for humans to read. Additional usage examples as well as information on JSON formatting and the "curl" command, are available in [[iDigBio API Examples]].
Most of the provided usage examples include a JSON formatter (such as json_pp) to make the JSON document response easier for humans to read. Additional usage examples as well as information on JSON formatting and the "curl" command, are available in [[iDigBio API Examples]].


There are two major types of API enpoints:  
There are three major types of API endpoints:  


*Collection - which is a group endpoint that returns lists of multiple records. These urls are of the form <base url>/<version>/<type>, such as http://api.idigbio.org/v1/mediarecords/ . Additionally, a collection endpoint can contain optional query parameters, [[?limit]] indicates the number of records returned in the collection and defaults to 1000 and the [[?offset]] parameter which indicates the number of records to skip before returning a set of records and defaults to 0. If a collection endpoint request finds more then the set limit of records it will include a "next page" link to retrieve the next set of records in the collection. See the [[#endpointprops|endpoint properties]] section for more information on properties returned.
*List - The endpoint returns a JSON document containing a list of iDigBio UUIDs and links to other records. The List of UUIDs normally does not contain content data. To get to record content data, links to each item in the List are followed.
   
   
*Entity - A single item endpoint which returns all of the data available about an object. These urls are of the form  <base url>/<version>/<type>/<id> like the example used above.
*Full Record - The endpoint returns a JSON document representing a Full Record for a type of object.  Examples include a Specimen Record or a Media Record. The Full Record endpoint is used to retrieve all of the data about a particular object.
 
*Media - A media endpoint returns one or more HTTP redirects to an actual media file (typically a JPEG image).
 
'''Special Note about the idigbio:links section'''
 
The iDigBio API tries to follow the REST paradigm's HATEOAS (Hypermedia as the Engine of Application State) model, which basically means that within each API endpoint a list of relevant links to further API actions is included. The list of relevant links to further API actions is typically stored in "idigbio:links".


Examples:
For example, a Recordset record may include links to its publisher, the related records, and the related mediarecords.


collection:
If the number of related items for a particular type exceeds 20, the idigbio:links for that type of relation will be a single link to a List of itemsIf the number of related items for a particular type is less than 20, the items will simply be included in the idigbio:links section.
"http://api.idigbio.org/v1/mediarecords"
collection w/ optional query parameters:
  "http://api.idigbio.org/v1/mediarecords?limit=100&offset=100"
entity:
"http://api.idigbio.org/v1/mediarecords/00000230-01bc-4a4f-8389-204f39da9530"


[[iDigBio API Examples]] includes examples that demonstrate this behavior.


[[#toc|Back to contents]]
----
----


Line 41: Line 50:


;Description
;Description
:Returns a list of top-level api_version or service URLs
:Returns a List of top-level API versions or service URLs.


;Resource URL
;Resource URL
Line 62: Line 71:
</pre>
</pre>


[[#toc|Back to contents]]
----
----


Line 67: Line 77:


;Description
;Description
:Returns a list of top-level API feature types for a particular version of the API
:Returns a List of top-level API feature types for a particular version of the API.


;Resource URL
;Resource URL
Line 94: Line 104:


;Notes
;Notes
:Some of the listed feature types may deprecated. This will be noted elsewhere in the API specification document.
:Some of the listed feature types may deprecated. This will be noted elsewhere in this API specification document.


[[#toc|Back to contents]]
----
----


Line 103: Line 114:
:Deprecated, do not use.
:Deprecated, do not use.


[[#toc|Back to contents]]
----
----
=== GET /v1/mediaaps ===
=== GET /v1/mediaaps ===
Line 109: Line 121:
:Deprecated, do not use.
:Deprecated, do not use.


[[#toc|Back to contents]]
----
----
=== GET /v1/mediarecords ===
=== GET /v1/mediarecords ===


;Description
;Description
:Returns a collection of Media Record IDs
:Returns a List of Media Record iDigBio UUIDs. The iDigBio UUID is represented by the "idigbio:uuid" data field.


;Resource URL
;Resource URL
Line 129: Line 142:
|-
|-
|limit
|limit
|
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|
|Controls the number of items returned in the List. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
|-
|-
|offset
|offset
|
|0, 1, 2, ... 1000, ..., 10000, ..., n
|
|Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|}
|}
;Sample Usage
;Sample Usage
Request five media record items:
<pre>
$ curl -s "http://api.idigbio.org/v1/mediarecords?limit=5" | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000003cd-0cca-421b-8f26-f557a26b0393"
        },
        "idigbio:uuid" : "000003cd-0cca-421b-8f26-f557a26b0393",
        "idigbio:version" : 1,
        "idigbio:etag" : "ce3e2f7272ec996bb479c87549ba90c15ba96426",
        "idigbio:dateModified" : "2014-04-21T22:19:27.436Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00000728-ffb3-4a68-9f93-137f19961121"
        },
        "idigbio:uuid" : "00000728-ffb3-4a68-9f93-137f19961121",
        "idigbio:version" : 3,
        "idigbio:etag" : "ef2cac326a60d89d8cb9005abaa82068bfa83565",
        "idigbio:dateModified" : "2014-04-24T05:03:56.782Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00000b03-e208-4d22-983b-506ad2842f7c"
        },
        "idigbio:uuid" : "00000b03-e208-4d22-983b-506ad2842f7c",
        "idigbio:version" : 2,
        "idigbio:etag" : "bc118a7ea53e004c82ab9b7e813e1010ae5f8e17",
        "idigbio:dateModified" : "2014-04-20T05:16:20.389Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000010bc-a4d4-483d-b71d-0dbdd4fd2d5a"
        },
        "idigbio:uuid" : "000010bc-a4d4-483d-b71d-0dbdd4fd2d5a",
        "idigbio:version" : 0,
        "idigbio:etag" : "68c441bd3c49507bf930f3b278f2c58f9cb792ec",
        "idigbio:dateModified" : "2014-04-20T21:38:46.679Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000012f9-d288-4a14-b898-77430e0a137a"
        },
        "idigbio:uuid" : "000012f9-d288-4a14-b898-77430e0a137a",
        "idigbio:version" : 1,
        "idigbio:etag" : "cf49416750fdb9bdb808c334a74b84f27bb8160b",
        "idigbio:dateModified" : "2014-04-23T02:43:08.344Z"
      }
  ],
  "idigbio:itemCount" : "2342880"
}
</pre>
One point of interest here is that <code> "idigbio:itemCount" </code> contains the number of items of this type in the API. In this case, there are 2,342,880 mediarecords total in the API.
The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:


<pre>
<pre>
# CURL SOMETHING
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5"
  }
</pre>
</pre>


More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in [[iDigBio API Examples]].
''DO NOT expect to be able to page through the entire iDigBio data this way.  See [[iDigBio API Performance]] if you find yourself trying to page through large amounts of data.''
[[#toc|Back to contents]]
----
----


=== GET /v1/mediarecords/{ID}  ===
=== GET /v1/mediarecords/{UUID}  ===


;Description
;Description
:Returns a Media Record with the specific entity ID
:Returns the full Media Record matching the specified iDigBio UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field. A Media Record contains metadata and relationship information about media (typically an image).


;Resource URL
;Resource URL


<pre>
<pre>
http://api.idigbio.org/v1/mediarecords/{ID}
http://api.idigbio.org/v1/mediarecords/{UUID}
</pre>
</pre>


Line 164: Line 249:
|version
|version
|Integer values from 0 to maxium version of a particular record
|Integer values from 0 to maxium version of a particular record
|The API normally returns the most recent version of a particular record. Records may be updated over time. The version parameter can be used to retrieve previous versions of a record.
|Media Records may be updated over time (changes submitted by data publishers). The "version" parameter is used to retrieve a previous version of a record. A value of "-1" returns the most recent version of a record. Omitting the "version" parameter returns the most recent version of a record.
|}
|}


Line 170: Line 255:
;Sample Usage
;Sample Usage


Request a single mediarecord:


<pre>
$ curl -s "http://api.idigbio.org/v1/mediarecords/ed135aeb-2bf6-4296-9e0c-014b170565b0" | json_pp
{
  "idigbio:uuid" : "ed135aeb-2bf6-4296-9e0c-014b170565b0",
  "idigbio:etag" : "3b929ca537cb245a6c640f876dbb363d90c409c3",
  "idigbio:links" : {
      "owner" : [
        "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "record" : [
        "http://api.idigbio.org/v1/records/5414f6f3-849a-4f62-9c5d-0cc662392910"
      ],
      "recordset" : [
        "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
      ],
      "mediaap" : [
        "http://api.idigbio.org/v1/mediaaps/3460b9bf-0802-45bd-85bb-45a39e443d7c"
      ]
  },
  "idigbio:version" : 1,
  "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
  "idigbio:recordIds" : [
      "urn:uuid:b1b7d9b6-1078-46ea-861d-94c8cc5daf01"
  ],
  "idigbio:dateModified" : "2014-04-20T23:37:00.310Z",
  "idigbio:data" : {
      "ac:accessURI" : "http://swbiodiversity.org/imglib/seinet/ASU/ASU0055/ASU0055165_lg.jpg",
      "ac:metadataLanguage" : "en",
      "ac:subtype" : "Photograph",
      "dwc:occurrenceID" : "765167",
      "xmpRights:WebStatement" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
      "dcterms:format" : "image/jpeg",
      "dcterms:type" : "StillImage",
      "xmp:MetadataDate" : "2012-01-24 12:20:26",
      "xmpRights:UsageTerms" : "CC BY-NC-SA (Attribution-NonCommercial-ShareAlike)",
      "xmpRights:Owner" : "Arizona State University Vascular Plant Herbarium (ASU-Plants)",
      "ac:providerManagedID" : "urn:uuid:b1b7d9b6-1078-46ea-861d-94c8cc5daf01",
      "ac:associatedSpecimenReference" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=765167"
  }
}
</pre>


[[#toc|Back to contents]]
----
----


=== GET /v1/mediarecords/{ID}/media ===
=== GET /v1/mediarecords/{UUID}/media ===


;Description
;Description
:Returns an image file (JPEG) associated with the specific entity ID
:Returns one or more HTTP redirects to a target image file (JPEG) that is associated with the specified iDigBio UUID. Omitting the "quality" parameter will return the full size image specified in the source data accessURI field and is usually served from the provider's infrastructure. Specifying the "quality" parameter will return a derivative image file that is hosted on iDigBio infrastructure. For many use cases, the recommended use of this endpoint would include the quality parameter.


;Resource URL
;Resource URL


<pre>
<pre>
http://api.idigbio.org/v1/mediarecords/{ID}/media
http://api.idigbio.org/v1/mediarecords/{UUID}/media
</pre>
</pre>


Line 193: Line 321:
|-
|-
|quality
|quality
|"thumbnail" "webview"
|"thumbnail" "webview" "fullsize"
|Specifiy the quality of the image returned from the API. Omitting quality will return the full-size high quality original image from source provider. The values "thumbnail" and "webview" return images of width 260 and 600 pixels respectively.
|Specify the quality of the JPEG image returned from the API. The values "thumbnail" or "webview" return derivative images of width 260 and 600 pixels respectively. The value "fullsize" returns a derivative image that matches the size (width in pixels) of the original image. Omitting quality will return the full-size original image as specified in accessURI by the provider.
|}
|}


;Sample Usage
;Sample Usage
Request a thumbnail image for a media record with iDigBio UUID of <code>00002091-4fb3-410a-9307-bd3e917dfcca</code> by issuing an HTTP "GET" to the following URL:


<pre>
<pre>
# CURL SOMETHING with -L to follow redirects
http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca/media?quality=thumbnail
</pre>
</pre>


The response to the above URL is a series of HTTP Redirects that lead to a thumbnail image, illustrated here with the Firefox Web Developer Tools visible:
[[File:Screenshot_firefox_webdevtools_thumbnail_00002091-4fb3-410a-9307-bd3e917dfcca.png]]
''Note that the final image URL should not be considered stable or permanent. Images can be moved around to various storage platforms. The iDigBio UUID of the Media Record will remain constant, but the containing data, including the image locations, may change over time.''
[[#toc|Back to contents]]
----
----


Line 208: Line 346:


;Description
;Description
:Returns a collection of record IDs
:Returns a List of Specimen Record iDigBio UUIDs. The iDigBio UUID is represented by the "idigbio:uuid" data field.


;Resource URL
;Resource URL
Line 224: Line 362:
|-
|-
|limit
|limit
|
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|
|Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000. 
|-
|-
|offset
|offset
|
|0, 1, 2, ... 1000, ..., 10000, ..., n
|
|Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|}
|}


;Sample Usage
;Sample Usage
Request five specimen record items:


<pre>
<pre>
# CURL SOMETHING
$ curl -s "http://api.idigbio.org/v1/records?limit=5" | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/records?limit=5&offset=5"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/0000012b-9bb8-42f4-ad3b-c958cb22ae45"
        },
        "idigbio:uuid" : "0000012b-9bb8-42f4-ad3b-c958cb22ae45",
        "idigbio:version" : 2,
        "idigbio:etag" : "9d2209ef58ddfef276e4a06cad57d106942516c1",
        "idigbio:dateModified" : "2014-04-21T04:36:29.192Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000230-01bc-4a4f-8389-204f39da9530"
        },
        "idigbio:uuid" : "00000230-01bc-4a4f-8389-204f39da9530",
        "idigbio:version" : 3,
        "idigbio:etag" : "b9083a241369e3e1c5a81db7d6e396d796a402ee",
        "idigbio:dateModified" : "2014-04-21T12:23:42.181Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000234-ac13-4e01-a2ae-e9aa95f35693"
        },
        "idigbio:uuid" : "00000234-ac13-4e01-a2ae-e9aa95f35693",
        "idigbio:version" : 3,
        "idigbio:etag" : "ca72b24d3fe3c4685f417849fcec00a21b201467",
        "idigbio:dateModified" : "2014-05-03T08:57:03.106Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000330-918b-4d62-bf7f-23a1f4f240e5"
        },
        "idigbio:uuid" : "00000330-918b-4d62-bf7f-23a1f4f240e5",
        "idigbio:version" : 4,
        "idigbio:etag" : "5922ca971561608960f96a4b7b30c83234aa7ea8",
        "idigbio:dateModified" : "2014-04-24T08:16:50.204Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000397-5012-4dda-9b03-52230c7f4bfc"
        },
        "idigbio:uuid" : "00000397-5012-4dda-9b03-52230c7f4bfc",
        "idigbio:version" : 3,
        "idigbio:etag" : "70d7064d6a135b6d3a66c03f82e95ad498a0c047",
        "idigbio:dateModified" : "2014-04-23T04:50:44.684Z"
      }
  ],
  "idigbio:itemCount" : "15324705"
}
 
</pre>
</pre>


One point of interest here is that <code> "idigbio:itemCount" </code> contains the number of items of this type in the API. In this case, there are 15,324,705 specimen records total in the API.
The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:
<pre>
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/records?limit=5&offset=5"
  },
</pre>
More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in [[iDigBio API Examples]].
''DO NOT expect to be able to page through the entire iDigBio data this way.  See [[iDigBio API Performance]] if you find yourself trying to page through large amounts of data.''
[[#toc|Back to contents]]
----
----


=== GET /v1/records/{ID} ===
=== GET /v1/records/{UUID} ===


;Description
;Description
:Returns a record with the specific entity ID
:Returns a full Specimen Record matching the specified iDigBio UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field. A Specimen Record contains occurrence data.
 


;Resource URL
;Resource URL


<pre>
<pre>
http://api.idigbio.org/v1/records/{ID}
http://api.idigbio.org/v1/records/{UUID}
</pre>
</pre>


Line 260: Line 471:
|version
|version
|Numeric values from 0 to maxium version of a particular record
|Numeric values from 0 to maxium version of a particular record
|The API normally returns the "latest" or most recent version of a particular record. Records may be updated over time. The version parameter can be used to retrieve previous versions of a record.
|Specimen Records may be updated over time (changes submitted by data publishers). The "version" parameter is used to retrieve a previous version of a record. A value of "-1" returns the most recent version of a record. Omitting the "version" parameter returns the most recent version of a record.
|}
|}


;Sample Usage
;Sample Usage
<pre>
<pre>
# CURL SOMETHING
$ curl -s http://api.idigbio.org/v1/records/0000012b-9bb8-42f4-ad3b-c958cb22ae45 | json_pp
{
  "idigbio:uuid" : "0000012b-9bb8-42f4-ad3b-c958cb22ae45",
  "idigbio:etag" : "9d2209ef58ddfef276e4a06cad57d106942516c1",
  "idigbio:links" : {
      "mediarecord" : [
        "http://api.idigbio.org/v1/mediarecords/ae175cc6-82f4-456b-910c-34da322e768d",
        "http://api.idigbio.org/v1/mediarecords/d0ca23cd-d4eb-43b5-aaba-cb75f8aef9e3"
      ],
      "owner" : [
        "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "recordset" : [
        "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
      ]
  },
  "idigbio:version" : 2,
  "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
  "idigbio:recordIds" : [
      "urn:uuid:ed400275-09d7-4302-b777-b4e0dcf7f2a3"
  ],
  "idigbio:dateModified" : "2014-04-21T00:36:29.192Z",
  "idigbio:data" : {
      "dwc:identifiedBy" : "Andrew Salywon, Jan 2003",
      "dwc:catalogNumber" : "ASU0010142",
      "dwc:basisOfRecord" : "PreservedSpecimen",
      "symbiotaverbatimScientificName" : "Eugenia monticola",
      "dwc:collectionCode" : "Plants",
      "dwc:decimalLongitude" : "-64.7131",
      "dcterms:references" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=762944",
      "dwc:scientificNameAuthorship" : "Hitchc.",
      "dwc:collectionID" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
      "dwc:georeferenceSources" : "georef batch tool 2012-07-09",
      "dwc:georeferenceVerificationStatus" : "reviewed - high confidence",
      "dwc:occurrenceRemarks" : "Small tree. 3.0 m. Bark brown, stems smooth; flowers in buds yellow.",
      "dwc:otherCatalogNumbers" : "156664",
      "dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
      "dwc:decimalLatitude" : "18.348",
      "dwc:day" : "21",
      "idigbio:recordId" : "urn:uuid:ed400275-09d7-4302-b777-b4e0dcf7f2a3",
      "dwc:specificEpithet" : "monticola",
      "dwc:locality" : "Coral Bay Quarter, Bordeaux Mountain Road.",
      "dwc:occurrenceID" : "762944",
      "dwc:year" : "1987",
      "dwc:recordedBy" : "P. Acevedo; A. Reilly",
      "dwc:recordNumber" : "1897",
      "dwc:family" : "Myrtaceae",
      "dwc:scientificName" : "Eugenia monticola",
      "dwc:georeferencedBy" : "jssharpe",
      "dcterms:modified" : "2012-07-09 12:00:09",
      "dwc:country" : "U.S. Virgin Islands",
      "dwc:eventDate" : "1987-08-21",
      "dwc:reproductiveCondition" : "flowers",
      "dwc:startDayOfYear" : "233",
      "dwc:habitat" : "Sunny roadside.",
      "dwc:dynamicProperties" : "Small tree. 3.0 m. Bark brown, stems smooth; flowers in buds yellow.",
      "dwc:month" : "8",
      "dwc:stateProvince" : "Saint John",
      "dwc:genus" : "Eugenia",
      "dwc:coordinateUncertaintyInMeters" : "2000",
      "dwc:institutionCode" : "ASU"
  }
}
 
</pre>
</pre>


[[#toc|Back to contents]]
----
----


=== GET /v1/records/{ID}/media ===
=== GET /v1/records/{UUID}/media ===


;Description
;Description
:Returns an image (JPEG) associated with the specific entity ID (via the relationship to a mediarecord). If multiple mediarecords are associated with a specimen record, the particular image returned in non-deterministic.
:Returns one or more HTTP redirects to a target image file (JPEG) that is associated with the specified iDigBio UUID (via the relationship to a mediarecord). If multiple mediarecords are associated with a specimen record, the particular mediarecord chosen by the API is non-deterministic.  Omitting the "quality" parameter will return the full size image specified in the source data accessURI field and is usually served from the provider's infrastructure. Specifying the "quality" parameter will return a derivative image file that is hosted on iDigBio infrastructure. For many use cases, the recommended use of this endpoint would include the quality parameter. .


;Resource URL
;Resource URL


<pre>
<pre>
http://api.idigbio.org/v1/records/{ID}/media
http://api.idigbio.org/v1/records/{UUID}/media
</pre>
</pre>


Line 289: Line 564:
|-
|-
|quality
|quality
|"thumbnail" "webview"
|"thumbnail" "webview" "fullsize"
|Specifiy the quality of the image returned from the API. Omitting quality will return the full-size high quality original image from source provider. The values "thumbnail" and "webview" return images of width 260 and 600 pixels respectively.
|Specify the quality of the JPEG image returned from the API. The values "thumbnail" or "webview" return derivative images of width 260 and 600 pixels respectively. The value "fullsize" returns a derivative image that matches the size (width in pixels) of the original image. Omitting quality will return the full-size original image as specified in accessURI by the provider.
|}
|}


;Sample Usage
;Sample Usage
Request a thumbnail image for a specimen record with iDigBio UUID of <code>182c9260-0151-454a-a648-4d58ddf51bd8</code> by issuing an HTTP "GET" to the following URL:


<pre>
<pre>
# CURL SOMETHING with -L to watch redirects
http://api.idigbio.org/v1/records/182c9260-0151-454a-a648-4d58ddf51bd8/media?quality=thumbnail
</pre>
</pre>


The response to the above URL is a series of HTTP Redirects that lead to a thumbnail image, illustrated here with the Firefox Web Developer Tools visible:
[[File:Screenshot_firefox_webdevtools_thumbnail_specimen_182c9260-0151-454a-a648-4d58ddf51bd8.png]]
''Note that the final image URL should not be considered stable or permanent. Images can be moved around to various storage platforms. The iDigBio UUID of the Specimen Record will remain constant, but the containing data, including the image locations, may change over time.''
[[#toc|Back to contents]]
----
=== GET /v1/organizations ===
;Description
:Deprecated, do not use.
[[#toc|Back to contents]]
----
=== GET /v1/people ===
;Description:
:Deprecated, do not use.
[[#toc|Back to contents]]
----
----


Line 304: Line 605:


;Description
;Description
:Returns a collection of publisher IDs
:Returns a List of Publisher iDigBio UUIDs. Publishers are the top-level entities containing metadata about data publishing locations.


;Resource URL
;Resource URL
Line 313: Line 614:




;Parameters
;Optional Parameters


* something goes here
{| class="wikitable" style="background-color: #ffffcc;" width="100%"
!parameter
!valid values
!detailed description
|-
|limit
|0, 1, 2, ..., 10, ..., n
|Controls the number of items returned.
|-
|offset
|0, 1, 2, ..., 10, ..., n
|Controls the starting offset for paging through the API.
|}


;Sample Usage
;Sample Usage
Retrieve a List with only one publisher entity.


<pre>
<pre>
# CURL SOMETHING
$ curl -s "http://api.idigbio.org/v1/publishers?limit=1" | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/publishers?limit=1&offset=1"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "publisher" : "http://api.idigbio.org/v1/publishers/076c0ff6-65e9-48a5-8e4b-2447936f9a1c"
        },
        "idigbio:uuid" : "076c0ff6-65e9-48a5-8e4b-2447936f9a1c",
        "idigbio:version" : 15,
        "idigbio:etag" : "154afad64618151ae4e39da1874acf7f0c86a6c2",
        "idigbio:dateModified" : "2014-04-18T19:14:53.966Z"
      }
  ],
  "idigbio:itemCount" : "20"
}
 
</pre>
</pre>


The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:
<pre>
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/publishers?limit=1&offset=1"
  },
</pre>
More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in [[iDigBio API Examples]].
[[#toc|Back to contents]]
----
----
=== GET /v1/organizations ===
 
=== GET /v1/publishers/{UUID} ===


;Description
;Description
:Deprecated, do not use.
:Returns a full Publisher Record matching the specified iDigBio UUID. A publisher record includes links to all of the recordsets provided to iDigBio by the publisher as well as other information about each recordset.
 
;Resource URL
 
<pre>
http://api.idigbio.org/v1/publishers/{UUID}
</pre>
 
;Optional Parameters
 
{| class="wikitable" style="background-color: #ffffcc;" width="100%"
!parameter
!valid values
!detailed description
|-
|version
|Numeric values from 0 to maximum version of a particular record
|Publisher records may be updated over time. The "version" parameter is used to retrieve a previous version of a record. A value of "-1" returns the most recent version of a record. Omitting the "version" parameter returns the most recent version of a record.
|}
 
;Sample Usage


----
<pre>
=== GET /v1/people ===
$ curl -s http://api.idigbio.org/v1/publishers/a9dfa037-425b-442b-8974-94487c29114e | json_pp
{
  "idigbio:uuid" : "a9dfa037-425b-442b-8974-94487c29114e",
  "idigbio:etag" : "e436abe5ac4015449f885f74443abd48cc2ff7f4",
  "idigbio:links" : {
      "recordset" : [
        "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd",
        "http://api.idigbio.org/v1/recordsets/b531ea59-025d-4c29-9d23-99ae75bcd55f",
        "http://api.idigbio.org/v1/recordsets/c569e530-7322-40b8-9b66-1e0ed96fefcb"
      ]
  },
  "idigbio:version" : 9,
  "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
  "idigbio:recordIds" : [
      "http://swbiodiversity.org/seinet/webservices/dwc/rss.xml",
      "http://swbiodiversity.org/seinet/"
  ],
  "idigbio:dateModified" : "2014-04-18T15:15:19.172Z",
  "idigbio:data" : {
      "auto_publish" : false,
      "rss_url" : "http://swbiodiversity.org/seinet/webservices/dwc/rss.xml",
      "publisher_type" : "symbiota",
      "base_url" : "http://swbiodiversity.org/seinet/",
      "name" : "SEINet Darwin Core Archive rss feed",
      "recordsets" : {
        "http://swbiodiversity.org/seinet/webservices/dwc/17a53c97-835b-409e-8a9a-c9a7307a4965" : {
            "link" : "http://swbiodiversity.org/seinet/collections/datasets/dwc/ASC_DwC-A.zip",
            "contacts" : [
              {
                  "email" : "seinetadmin@asu.edu",
                  "first_name" : "Edward Gilbert"
              },
              {
                  "email" : "tina.ayers@nau.edu & deaver.herbarium@nau.edu",
                  "first_name" : "Tina Ayers"
              }
            ],
            "ingest" : true,
            "collection_description" : "Number of Specimens: 105 000 Specialty: Colorado Plateau, especially northern Arizona; northeastern Mojave Desert; northern Arizona National Parks and Monuments; vascular plants of the San Francisco Peaks and Coconino National Forest. Important Collections: M. Baker; R. E. Collom; C. F. Deaver; D. Demaree; R. K. Gierisch; L. N. Goodding; G. Goodwin; H. D. Hammond; R. H. Hevly; M. E. Jones; T. H. Kearney; Max Licher; E. L. Little, Jr.; V. O. Mayes; A. M. Phillips; G. R. Rink; C. G. Schaack; J. J. Thornber; A. F. Whiting Incorporated Herbaria: FSLF (1000 specimens) in 1989. Notes: Name for Arizona State College changed to Northern Arizona University in 1966. ASC fungi transferred to MICH in 1998. ASC is temporarily housing NAVA, until the Navajo Natural Heritage builds a new building. Date Founded: 1930. Number of Specimens: 105 000 Specialty: Colorado Plateau, especially northern Arizona; northeastern Mojave Desert; northern Arizona National Parks and Monuments; vascular plants of the San Francisco Peaks and Coconino National Forest. Important Collections: M. Baker; R. E. Collom; C. F. Deaver; D. Demaree; R. K. Gierisch; L. N. Goodding; G. Goodwin; H. D. Hammond; R. H. Hevly; M. E. Jones; T. H. Kearney; Max Licher; E. L. Little, Jr.; V. O. Mayes; A. M. Phillips; G. R. Rink; C. G. Schaack; J. J. Thornber; A. F. Whiting Incorporated Herbaria: FSLF (1000 specimens) in 1989. Notes: Name for Arizona State College changed to Northern Arizona University in 1966. ASC fungi transferred to MICH in 1998. ASC is temporarily housing NAVA, until the Navajo Natural Heritage builds a new building. Date Founded: 1930.",
            "logo_url" : "http://swbiodiversity.org/seinet/images/collicons/nauplant.jpg",
            "collection_name" : "Deaver Herbarium (Northern Arizona University)",
            "institution_web_address" : "http://nau.edu/Merriam-Powell/Biodiversity-Center/Deaver-Herbarium/",
            "id" : "http://swbiodiversity.org/seinet/webservices/dwc/17a53c97-835b-409e-8a9a-c9a7307a4965",
            "other_guids" : [],
            "update" : "2014-04-15T01:00:00"
        },
        "http://swbiodiversity.org/seinet/webservices/dwc/a2e32c87-d320-4a01-bafd-a9182ae2e191" : {
            "link" : "http://swbiodiversity.org/seinet/collections/datasets/dwc/ASU-Plants_DwC-A.zip",
            "contacts" : [
              {
                  "email" : "seinetadmin@asu.edu",
                  "first_name" : "Edward Gilbert"
              },
              {
                  "email" : "les.landrum@asu.edu",
                  "first_name" : "Leslie Landrum"
              }
            ],
            "ingest" : true,
            "collection_description" : "The Arizona State University Vascular Plant Herbarium is the second largest in the Arid Southwest with over 285,000 specimens. Our collection of Cactaceae is one of the best in the world, being particularly rich in cytological vouchers. The Arizona State University Vascular Plant Herbarium is the second largest in the Arid Southwest with over 285,000 specimens. Our collection of Cactaceae is one of the best in the world, being particularly rich in cytological vouchers.",
            "logo_url" : "http://swbiodiversity.org/seinet/images/collicons/asu.jpg",
            "collection_name" : "Arizona State University Vascular Plant Herbarium",
            "institution_web_address" : "http://lifesciences.asu.edu/herbarium/",
            "id" : "http://swbiodiversity.org/seinet/webservices/dwc/a2e32c87-d320-4a01-bafd-a9182ae2e191",
            "other_guids" : [],
            "update" : "2014-04-15T01:00:00"
        },
        "http://swbiodiversity.org/seinet/webservices/dwc/edb9860c-c481-4d19-88cc-224a536ebcd4" : {
            "link" : "http://swbiodiversity.org/seinet/collections/datasets/dwc/DES_DwC-A.zip",
            "contacts" : [
              {
                  "email" : "seinetadmin@asu.edu",
                  "first_name" : "Edward Gilbert"
              },
              {
                  "email" : "asalywon@dbg.org",
                  "first_name" : "Andrew Salywon"
              }
            ],
            "ingest" : true,
            "collection_description" : "Approximately 75000 specimens in collection, with emphasis on plants of the Southwest and northern Mexico, Cactaceae and Agavaceae. &lt;div style=&quot;margin-top:10px&quot;&gt;&lt;b&gt;Curator:&lt;/b&gt; Wendy C. Hodgson (whodgson&lt;at&gt;dbg.org) &lt;/div&gt; &lt;div style=&quot;margin-top:10px&quot;&gt;&lt;b&gt;Assistant Curator:&lt;/b&gt; Andrew Salywon &lt;/div&gt; Approximately 75000 specimens in collection, with emphasis on plants of the Southwest and northern Mexico, Cactaceae and Agavaceae. &lt;div style=&quot;margin-top:10px&quot;&gt;&lt;b&gt;Curator:&lt;/b&gt; Wendy C. Hodgson (whodgson&lt;at&gt;dbg.org) &lt;/div&gt; &lt;div style=&quot;margin-top:10px&quot;&gt;&lt;b&gt;Assistant Curator:&lt;/b&gt; Andrew Salywon &lt;/div&gt;",
            "logo_url" : "http://swbiodiversity.org/seinet/images/collicons/des.jpg",
            "collection_name" : "Desert Botanical Garden Herbarium Collection",
            "institution_web_address" : "http://www.dbg.org/",
            "id" : "http://swbiodiversity.org/seinet/webservices/dwc/edb9860c-c481-4d19-88cc-224a536ebcd4",
            "other_guids" : [],
            "update" : "2014-04-15T01:00:00"
        }
      }
  }
}


;Description:
</pre>
:Deprecated, do not use.


[[#toc|Back to contents]]
----
----
=== GET /v1/publishers/{ID} ===
 
=== GET /v1/publishers/{UUID}/recordsets ===


;Description
;Description
:Returns a publisher with specific entity ID
:Return a List of recordset iDigBio UUIDs that are associated with the Publisher of the specified iDigBio UUID (returns a list of recordsets that are published by a particular Publisher).


;Resource URL
;Resource URL


<pre>
<pre>
http://api.idigbio.org/v1/publishers/{ID}
http://api.idigbio.org/v1/publishers/{UUID}/recordsets
</pre>
</pre>


;Parameters


* something goes here
;Optional Parameters
 
{| class="wikitable" style="background-color: #ffffcc;" width="100%"
!parameter
!valid values
!detailed description
|-
|limit
|0, 1, 2, ..., 10, ..., n
|Controls the number of items returned.
|-
|offset
|0, 1, 2, ..., 10, ..., n
|Controls the starting offset for paging through the API.
|}


;Sample Usage
;Sample Usage


<pre>
<pre>
# CURL SOMETHING
$ curl -s http://api.idigbio.org/v1/publishers/d347ee15-f16e-4650-930c-4e54d9ce549e/recordsets | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {},
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/271a9ce9-c6d3-4b63-a722-cb0adc48863f"
        },
        "idigbio:uuid" : "271a9ce9-c6d3-4b63-a722-cb0adc48863f"
      }
  ],
  "idigbio:itemCount" : "1"
}
 
</pre>
</pre>


[[#toc|Back to contents]]
----
----


Line 362: Line 847:


;Description
;Description
:Returns a collection of recordset IDs
:Returns a List of recordset iDigBio UUIDs. A recordset is a group of published data.


;Resource URL
;Resource URL
Line 370: Line 855:
</pre>
</pre>


;Parameters
;Optional Parameters


* something goes here
{| class="wikitable" style="background-color: #ffffcc;" width="100%"
!parameter
!valid values
!detailed description
|-
|limit
|0, 1, 2, ..., 10, ..., n
|Controls the number of items returned.
|-
|offset
|0, 1, 2, ..., 10, ..., n
|Controls the starting offset for paging through the API.
|}


;Sample Usage
;Sample Usage
Request a List of recordset iDigBio UUIDs (and in this usage example, limit the number of results to 3):
<pre>
$ curl -s http://api.idigbio.org/v1/recordsets?limit=3 | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets?limit=3&offset=3"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/0072bf11-a354-4998-8730-c0cb4cfc9517"
        },
        "idigbio:uuid" : "0072bf11-a354-4998-8730-c0cb4cfc9517",
        "idigbio:version" : 2,
        "idigbio:etag" : "c6df1d0673b5452af4118caf96c5c066b498e095",
        "idigbio:dateModified" : "2014-04-18T17:54:38.751Z"
      },
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/00d9fcc1-c8e2-4ef6-be64-9994ca6a32c3"
        },
        "idigbio:uuid" : "00d9fcc1-c8e2-4ef6-be64-9994ca6a32c3",
        "idigbio:version" : 3,
        "idigbio:etag" : "3d3c08b1155db3353048648fae23d05ca52e3a24",
        "idigbio:dateModified" : "2014-04-18T17:54:32.657Z"
      },
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/02fceae6-c71c-4db9-8b2f-e235ced6624a"
        },
        "idigbio:uuid" : "02fceae6-c71c-4db9-8b2f-e235ced6624a",
        "idigbio:version" : 2,
        "idigbio:etag" : "28b6a174e77f4f81f22dbf9b463a89d3b6b479a9",
        "idigbio:dateModified" : "2014-04-18T17:54:50.955Z"
      }
  ],
  "idigbio:itemCount" : "255"
}
</pre>
The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:


<pre>
<pre>
# CURL SOMETHING
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets?limit=3&offset=3"
  },
</pre>
</pre>


More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in [[iDigBio API Examples]].
[[#toc|Back to contents]]
----
----
=== GET /v1/recordsets/{ID} ===
 
=== GET /v1/recordsets/{UUID} ===


;Description
;Description
:Returns information about a recordset with specific entity ID
:Returns the full Recordset record with the specified iDigBio UUID.


;Resource URL
;Resource URL


<pre>
<pre>
http://api.idigbio.org/v1/recordsets/{ID}
http://api.idigbio.org/v1/recordsets/{UUID}
</pre>
</pre>


;Parameters
;Parameters


* something goes here
 
{| class="wikitable" style="background-color: #ffffcc;" width="100%"
!parameter
!valid values
!detailed description
|-
|version
|Integer values from 0 to maxium version of a particular record
|Recordset Records may be updated over time (changes submitted by data publishers). The "version" parameter is used to retrieve a previous version of a record. A value of "-1" returns the most recent version of a record. Omitting the "version" parameter returns the most recent version of a record.
|}


;Sample Usage
;Sample Usage


<pre>
<pre>
# CURL SOMETHING
$ curl -s http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f | json_pp
{
  "idigbio:uuid" : "7a8d946d-083f-4d2a-9cc9-cd590398194f",
  "idigbio:etag" : "29105ddc719b92504fdc619d0be225c5fb6d3341",
  "idigbio:links" : {
      "mediarecord" : [
        "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/mediarecords"
      ],
      "owner" : [
        "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "record" : [
        "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/records"
      ],
      "publisher" : [
        "http://api.idigbio.org/v1/publishers/1c29be70-24e7-480b-aab1-61224ded0f34"
      ]
  },
  "idigbio:version" : 0,
  "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
  "idigbio:recordIds" : [
      "http://portal.neherbaria.org/portal/webservices/dwc/cedd578e-3475-4eb9-b6a9-c630f417ffc6"
  ],
  "idigbio:dateModified" : "2014-04-30T21:01:28.391Z",
  "idigbio:data" : {
      "link" : "http://portal.neherbaria.org/portal/collections/datasets/dwc/YPM-YU_DwC-A.zip",
      "contacts" : [
        {
            "email" : "patrick.sweeney@yale.edu",
            "first_name" : "General Administrator"
        },
        {
            "email" : "patrick.sweeney@yale.edu",
            "first_name" : "Patrick W. Sweeney"
        }
      ],
      "ingest" : true,
      "collection_description" : "Founded in 1864 by Daniel Cady Eaton from his personal library and plant collection, the Yale Herbarium is an internationally recognized repository with holdings of approximately 350,000 specimens from throughout the world. There are an estimated 5,000 type specimens. The collection is particularly rich in ferns, bryophytes and grasses, as well as in historically important materials from the early botanical collectors. In addition, it was the herbarium of record for the flora of southern New England from 1864 until 1955, when that function passed to the University of Connecticut at Storrs. Founded in 1864 by Daniel Cady Eaton from his personal library and plant collection, the Yale Herbarium is an internationally recognized repository with holdings of approximately 350,000 specimens from throughout the world. There are an estimated 5,000 type specimens. The collection is particularly rich in ferns, bryophytes and grasses, as well as in historically important materials from the early botanical collectors. In addition, it was the herbarium of record for the flora of southern New England from 1864 until 1955, when that function passed to the University of Connecticut at Storrs.",
      "logo_url" : "http://portal.neherbaria.org/portal/images/collicons/YU_logo_60.gif",
      "collection_name" : "Yale University Herbarium, Peabody Museum of Natural History",
      "institution_web_address" : "http://www.peabody.yale.edu/collections/bot/",
      "id" : "http://portal.neherbaria.org/portal/webservices/dwc/cedd578e-3475-4eb9-b6a9-c630f417ffc6",
      "other_guids" : [],
      "update" : "2014-04-17T01:00:00"
  }
}
 
</pre>
</pre>


[[#toc|Back to contents]]
----
----


=== GET /v1/recordsets/{ID}/mediarecords ===
=== GET /v1/recordsets/{UUID}/mediarecords ===


;Description
;Description
:Returns a colleciton of mediarecord IDs that belong to the recordset of the specified entity ID
:Returns a List of Media Record iDigBio UUIDs that belong to the recordset of the specified iDigBio UUID.


;Resource URL
;Resource URL


<pre>
<pre>
http://api.idigbio.org/v1/recordsets/{ID}/mediarecords
http://api.idigbio.org/v1/recordsets/{UUID}/mediarecords
</pre>
</pre>


;Parameters
;Optional Parameters


* something goes here
{| class="wikitable" style="background-color: #ffffcc;" width="100%"
!parameter
!valid values
!detailed description
|-
|limit
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
|-
|offset
|0, 1, 2, ... 100, ..., 1000, ..., n
|Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|}


;Sample Usage
;Sample Usage
Return a List of mediarecord iDigBio UUIDs that belong to a particular recordset (and in this usage example, limit the number of results to 1):
<pre>
$ curl -s http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/mediarecords?limit=1 | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/mediarecords?limit=1&offset=1"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/0002429e-28a5-46ee-8bce-c4a7bc3870d9"
        },
        "idigbio:uuid" : "0002429e-28a5-46ee-8bce-c4a7bc3870d9"
      }
  ],
  "idigbio:itemCount" : "14897"
}
</pre>
The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:


<pre>
<pre>
# CURL SOMETHING
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/mediarecords?limit=1&offset=1"
  },
</pre>
</pre>


More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in [[iDigBio API Examples]].
''DO NOT expect to be able to page through the entire iDigBio data this way.  See [[iDigBio API Performance]] if you find yourself trying to page through large amounts of data.''
[[#toc|Back to contents]]
----
----
=== GET /v1/recordsets/{ID}/records ===
 
=== GET /v1/recordsets/{UUID}/records ===


;Description
;Description
:Returns a collection of record IDs that belong to the recordset of the specified entity ID
:Returns a List of iDigBio UUIDs that belong to the recordset of the specified entity ID.


;Resource URL
;Resource URL


<pre>
<pre>
http://api.idigbio.org/v1/recordsets/{ID}/records
http://api.idigbio.org/v1/recordsets/{UUID}/records
</pre>
</pre>


;Parameters
;Optional Parameters


* something goes here
{| class="wikitable" style="background-color: #ffffcc;" width="100%"
!parameter
!valid values
!detailed description
|-
|limit
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000. 
|-
|offset
|0, 1, 2, ... 1000, ..., 10000, ..., n
|Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|}


;Sample Usage
;Sample Usage
Return a list with a single record item that belongs to the recordset of the specified iDigBio UUID:
<pre>
$ curl -s http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/records?limit=1 | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/records?limit=1&offset=1"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/0002b73f-9c48-477f-b90e-13c86733f1ab"
        },
        "idigbio:uuid" : "0002b73f-9c48-477f-b90e-13c86733f1ab"
      }
  ],
  "idigbio:itemCount" : "18889"
}
</pre>
The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:


<pre>
<pre>
# CURL SOMETHING
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/records?limit=1&offset=1"
  },
</pre>
</pre>


More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in [[iDigBio API Examples]].
''DO NOT expect to be able to page through the entire iDigBio data this way.  See [[iDigBio API Performance]] if you find yourself trying to page through large amounts of data.''
[[#toc|Back to contents]]
----
----


Line 454: Line 1,146:
:Deprecated, do not use.
:Deprecated, do not use.


[[#toc|Back to contents]]
----
----


== Search ==
== Search ==
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''
The public-facing interface to the iDigBio back-end Elasticsearch system will likely be disabled at some point in the future.}}


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.
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.
Line 485: Line 1,181:
|}
|}


Examples specific to iDigBio are available in [[iDigBio API Examples]].
The query string is appended to the URL as a parameter named "q" and follows the following pattern:
 
<pre>
http://search.idigbio.org/idigbio/records/_search?&q=term:value
</pre>
 
The number of records returned can be adjusted with the "size" parameter.
 
Search examples that are specific to iDigBio are available in [[iDigBio API Examples]].
 
In most cases, iDigBio Elasticsearch terms are generated by dropping the leading namespace and colon, then lowercasing the remaining portion. This was done for a number of reasons including the fact that Elasticsearch itself uses colons in the query syntax.
 
Some examples:
 
{| class="wikitable"
!Definition
!DwC Term / iDigBio API Record Field
!iDigBio Elasticsearch Index Term
|-
|Scientific Name
|dwc:scientificName
|scientificname
|-
|Institution Code
|dwc:institutionCode
|institutioncode
|-
|iDigBio Record UUID
|idigbio:uuid
|uuid
|-
|...
|...
|...
|}
 
 
[[#toc|Back to contents]]
----


=== Elasticsearch - Records ===
=== Elasticsearch - Records ===
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''}}


Specimen Records Query URL:
Specimen Records Query URL:
Line 560: Line 1,296:


See [[iDigBio API Examples]] page for more Elasticsearch examples that are specific to iDigBio.
See [[iDigBio API Examples]] page for more Elasticsearch examples that are specific to iDigBio.
[[#toc|Back to contents]]
----


=== Elasticsearch - Media Records ===
=== Elasticsearch - Media Records ===
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''}}


Media Records Query URL:
Media Records Query URL:
Line 568: Line 1,310:
</pre>
</pre>


There are no useful search terms for '''Media Records''' queries using Elasticsearch at this time.
The following terms are currently available in the index for '''Media Records''' type of queries to Elasticsearch:
 
<pre>
recordset
uuid
</pre>
 
See [[iDigBio API Examples]] page for more Elasticsearch examples that are specific to iDigBio.
 
[[#toc|Back to contents]]
----
 
== Response and Error Codes ==
 
The API returns standard HTTP status codes. Errors will likely not return a JSON document so your code should handle the [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes raw HTTP status codes].

Latest revision as of 18:09, 9 July 2018


Caution! Caution: The v1 API has been superseded by iDigBio API v2 / iDigBio Search API. API users should migrate to using the most recent version of the API. This page remains for historical reference.


API Version Information

This is the specification for v1 of the iDigBio API. The v1 API has been superceded by iDigBio API v2 / iDigBio Search API. API users should migrate to using the most recent version of the API. The v1 API specification supercedes iDigBio API v0 Specification. Previous versions of the API may continue to exist but should be considered deprecated.

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.

Every record that is submitted to iDigBio receives a Globally Unique Identifier (GUID) of type UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field.

Endpoints

Unless otherwise noted, a successful response from an API endpoint will return a JSON-formatted document.

The curly braces { and } in this document are used as a placeholder to indicate that a real value needs to be substituted. For example, {api_version} would be replaced with the actual representation of the API version such as "v1" (without the quotes).

Most of the provided usage examples include a JSON formatter (such as json_pp) to make the JSON document response easier for humans to read. Additional usage examples as well as information on JSON formatting and the "curl" command, are available in iDigBio API Examples.

There are three major types of API endpoints:

  • List - The endpoint returns a JSON document containing a list of iDigBio UUIDs and links to other records. The List of UUIDs normally does not contain content data. To get to record content data, links to each item in the List are followed.
  • Full Record - The endpoint returns a JSON document representing a Full Record for a type of object. Examples include a Specimen Record or a Media Record. The Full Record endpoint is used to retrieve all of the data about a particular object.
  • Media - A media endpoint returns one or more HTTP redirects to an actual media file (typically a JPEG image).

Special Note about the idigbio:links section

The iDigBio API tries to follow the REST paradigm's HATEOAS (Hypermedia as the Engine of Application State) model, which basically means that within each API endpoint a list of relevant links to further API actions is included. The list of relevant links to further API actions is typically stored in "idigbio:links".

For example, a Recordset record may include links to its publisher, the related records, and the related mediarecords.

If the number of related items for a particular type exceeds 20, the idigbio:links for that type of relation will be a single link to a List of items. If the number of related items for a particular type is less than 20, the items will simply be included in the idigbio:links section.

iDigBio API Examples includes examples that demonstrate this behavior.

Back to contents


GET /

Description
Returns a List of top-level API versions or service URLs.
Resource URL
http://api.idigbio.org/
Optional 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/"
}

Back to contents


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
Optional 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 this API specification document.

Back to contents


GET /v1/aggregates

Description
Deprecated, do not use.

Back to contents


GET /v1/mediaaps

Description
Deprecated, do not use.

Back to contents


GET /v1/mediarecords

Description
Returns a List of Media Record iDigBio UUIDs. The iDigBio UUID is represented by the "idigbio:uuid" data field.
Resource URL
http://api.idigbio.org/v1/mediarecords
Optional Parameters
parameter valid values detailed description
limit 0, 1, 2, 10, ..., 100, ..., 1000, ..., n Controls the number of items returned in the List. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
offset 0, 1, 2, ... 1000, ..., 10000, ..., n Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
Sample Usage

Request five media record items:

$ curl -s "http://api.idigbio.org/v1/mediarecords?limit=5" | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000003cd-0cca-421b-8f26-f557a26b0393"
         },
         "idigbio:uuid" : "000003cd-0cca-421b-8f26-f557a26b0393",
         "idigbio:version" : 1,
         "idigbio:etag" : "ce3e2f7272ec996bb479c87549ba90c15ba96426",
         "idigbio:dateModified" : "2014-04-21T22:19:27.436Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00000728-ffb3-4a68-9f93-137f19961121"
         },
         "idigbio:uuid" : "00000728-ffb3-4a68-9f93-137f19961121",
         "idigbio:version" : 3,
         "idigbio:etag" : "ef2cac326a60d89d8cb9005abaa82068bfa83565",
         "idigbio:dateModified" : "2014-04-24T05:03:56.782Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00000b03-e208-4d22-983b-506ad2842f7c"
         },
         "idigbio:uuid" : "00000b03-e208-4d22-983b-506ad2842f7c",
         "idigbio:version" : 2,
         "idigbio:etag" : "bc118a7ea53e004c82ab9b7e813e1010ae5f8e17",
         "idigbio:dateModified" : "2014-04-20T05:16:20.389Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000010bc-a4d4-483d-b71d-0dbdd4fd2d5a"
         },
         "idigbio:uuid" : "000010bc-a4d4-483d-b71d-0dbdd4fd2d5a",
         "idigbio:version" : 0,
         "idigbio:etag" : "68c441bd3c49507bf930f3b278f2c58f9cb792ec",
         "idigbio:dateModified" : "2014-04-20T21:38:46.679Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000012f9-d288-4a14-b898-77430e0a137a"
         },
         "idigbio:uuid" : "000012f9-d288-4a14-b898-77430e0a137a",
         "idigbio:version" : 1,
         "idigbio:etag" : "cf49416750fdb9bdb808c334a74b84f27bb8160b",
         "idigbio:dateModified" : "2014-04-23T02:43:08.344Z"
      }
   ],
   "idigbio:itemCount" : "2342880"
}

One point of interest here is that "idigbio:itemCount" contains the number of items of this type in the API. In this case, there are 2,342,880 mediarecords total in the API.

The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:

   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5"
   }

More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in iDigBio API Examples.

DO NOT expect to be able to page through the entire iDigBio data this way. See iDigBio API Performance if you find yourself trying to page through large amounts of data.

Back to contents


GET /v1/mediarecords/{UUID}

Description
Returns the full Media Record matching the specified iDigBio UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field. A Media Record contains metadata and relationship information about media (typically an image).
Resource URL
http://api.idigbio.org/v1/mediarecords/{UUID}
Optional Parameters
parameter valid values detailed description
version Integer values from 0 to maxium version of a particular record Media Records may be updated over time (changes submitted by data publishers). The "version" parameter is used to retrieve a previous version of a record. A value of "-1" returns the most recent version of a record. Omitting the "version" parameter returns the most recent version of a record.


Sample Usage

Request a single mediarecord:

$ curl -s "http://api.idigbio.org/v1/mediarecords/ed135aeb-2bf6-4296-9e0c-014b170565b0" | json_pp
{
   "idigbio:uuid" : "ed135aeb-2bf6-4296-9e0c-014b170565b0",
   "idigbio:etag" : "3b929ca537cb245a6c640f876dbb363d90c409c3",
   "idigbio:links" : {
      "owner" : [
         "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "record" : [
         "http://api.idigbio.org/v1/records/5414f6f3-849a-4f62-9c5d-0cc662392910"
      ],
      "recordset" : [
         "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
      ],
      "mediaap" : [
         "http://api.idigbio.org/v1/mediaaps/3460b9bf-0802-45bd-85bb-45a39e443d7c"
      ]
   },
   "idigbio:version" : 1,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
      "urn:uuid:b1b7d9b6-1078-46ea-861d-94c8cc5daf01"
   ],
   "idigbio:dateModified" : "2014-04-20T23:37:00.310Z",
   "idigbio:data" : {
      "ac:accessURI" : "http://swbiodiversity.org/imglib/seinet/ASU/ASU0055/ASU0055165_lg.jpg",
      "ac:metadataLanguage" : "en",
      "ac:subtype" : "Photograph",
      "dwc:occurrenceID" : "765167",
      "xmpRights:WebStatement" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
      "dcterms:format" : "image/jpeg",
      "dcterms:type" : "StillImage",
      "xmp:MetadataDate" : "2012-01-24 12:20:26",
      "xmpRights:UsageTerms" : "CC BY-NC-SA (Attribution-NonCommercial-ShareAlike)",
      "xmpRights:Owner" : "Arizona State University Vascular Plant Herbarium (ASU-Plants)",
      "ac:providerManagedID" : "urn:uuid:b1b7d9b6-1078-46ea-861d-94c8cc5daf01",
      "ac:associatedSpecimenReference" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=765167"
   }
}

Back to contents


GET /v1/mediarecords/{UUID}/media

Description
Returns one or more HTTP redirects to a target image file (JPEG) that is associated with the specified iDigBio UUID. Omitting the "quality" parameter will return the full size image specified in the source data accessURI field and is usually served from the provider's infrastructure. Specifying the "quality" parameter will return a derivative image file that is hosted on iDigBio infrastructure. For many use cases, the recommended use of this endpoint would include the quality parameter.
Resource URL
http://api.idigbio.org/v1/mediarecords/{UUID}/media
Optional Parameters
parameter valid values detailed description
quality "thumbnail" "webview" "fullsize" Specify the quality of the JPEG image returned from the API. The values "thumbnail" or "webview" return derivative images of width 260 and 600 pixels respectively. The value "fullsize" returns a derivative image that matches the size (width in pixels) of the original image. Omitting quality will return the full-size original image as specified in accessURI by the provider.
Sample Usage

Request a thumbnail image for a media record with iDigBio UUID of 00002091-4fb3-410a-9307-bd3e917dfcca by issuing an HTTP "GET" to the following URL:

http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca/media?quality=thumbnail

The response to the above URL is a series of HTTP Redirects that lead to a thumbnail image, illustrated here with the Firefox Web Developer Tools visible:

Screenshot firefox webdevtools thumbnail 00002091-4fb3-410a-9307-bd3e917dfcca.png


Note that the final image URL should not be considered stable or permanent. Images can be moved around to various storage platforms. The iDigBio UUID of the Media Record will remain constant, but the containing data, including the image locations, may change over time.

Back to contents


GET /v1/records

Description
Returns a List of Specimen Record iDigBio UUIDs. The iDigBio UUID is represented by the "idigbio:uuid" data field.
Resource URL
http://api.idigbio.org/v1/records
Optional Parameters
parameter valid values detailed description
limit 0, 1, 2, 10, ..., 100, ..., 1000, ..., n Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
offset 0, 1, 2, ... 1000, ..., 10000, ..., n Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
Sample Usage

Request five specimen record items:

$ curl -s "http://api.idigbio.org/v1/records?limit=5" | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/records?limit=5&offset=5"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/0000012b-9bb8-42f4-ad3b-c958cb22ae45"
         },
         "idigbio:uuid" : "0000012b-9bb8-42f4-ad3b-c958cb22ae45",
         "idigbio:version" : 2,
         "idigbio:etag" : "9d2209ef58ddfef276e4a06cad57d106942516c1",
         "idigbio:dateModified" : "2014-04-21T04:36:29.192Z"
      },
      {
         "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000230-01bc-4a4f-8389-204f39da9530"
         },
         "idigbio:uuid" : "00000230-01bc-4a4f-8389-204f39da9530",
         "idigbio:version" : 3,
         "idigbio:etag" : "b9083a241369e3e1c5a81db7d6e396d796a402ee",
         "idigbio:dateModified" : "2014-04-21T12:23:42.181Z"
      },
      {
         "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000234-ac13-4e01-a2ae-e9aa95f35693"
         },
         "idigbio:uuid" : "00000234-ac13-4e01-a2ae-e9aa95f35693",
         "idigbio:version" : 3,
         "idigbio:etag" : "ca72b24d3fe3c4685f417849fcec00a21b201467",
         "idigbio:dateModified" : "2014-05-03T08:57:03.106Z"
      },
      {
         "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000330-918b-4d62-bf7f-23a1f4f240e5"
         },
         "idigbio:uuid" : "00000330-918b-4d62-bf7f-23a1f4f240e5",
         "idigbio:version" : 4,
         "idigbio:etag" : "5922ca971561608960f96a4b7b30c83234aa7ea8",
         "idigbio:dateModified" : "2014-04-24T08:16:50.204Z"
      },
      {
         "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000397-5012-4dda-9b03-52230c7f4bfc"
         },
         "idigbio:uuid" : "00000397-5012-4dda-9b03-52230c7f4bfc",
         "idigbio:version" : 3,
         "idigbio:etag" : "70d7064d6a135b6d3a66c03f82e95ad498a0c047",
         "idigbio:dateModified" : "2014-04-23T04:50:44.684Z"
      }
   ],
   "idigbio:itemCount" : "15324705"
}

One point of interest here is that "idigbio:itemCount" contains the number of items of this type in the API. In this case, there are 15,324,705 specimen records total in the API.

The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:

   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/records?limit=5&offset=5"
   },

More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in iDigBio API Examples.

DO NOT expect to be able to page through the entire iDigBio data this way. See iDigBio API Performance if you find yourself trying to page through large amounts of data.

Back to contents


GET /v1/records/{UUID}

Description
Returns a full Specimen Record matching the specified iDigBio UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field. A Specimen Record contains occurrence data.


Resource URL
http://api.idigbio.org/v1/records/{UUID}
Optional Parameters
parameter valid values detailed description
version Numeric values from 0 to maxium version of a particular record Specimen Records may be updated over time (changes submitted by data publishers). The "version" parameter is used to retrieve a previous version of a record. A value of "-1" returns the most recent version of a record. Omitting the "version" parameter returns the most recent version of a record.
Sample Usage
$ curl -s http://api.idigbio.org/v1/records/0000012b-9bb8-42f4-ad3b-c958cb22ae45 | json_pp
{
   "idigbio:uuid" : "0000012b-9bb8-42f4-ad3b-c958cb22ae45",
   "idigbio:etag" : "9d2209ef58ddfef276e4a06cad57d106942516c1",
   "idigbio:links" : {
      "mediarecord" : [
         "http://api.idigbio.org/v1/mediarecords/ae175cc6-82f4-456b-910c-34da322e768d",
         "http://api.idigbio.org/v1/mediarecords/d0ca23cd-d4eb-43b5-aaba-cb75f8aef9e3"
      ],
      "owner" : [
         "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "recordset" : [
         "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
      ]
   },
   "idigbio:version" : 2,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
      "urn:uuid:ed400275-09d7-4302-b777-b4e0dcf7f2a3"
   ],
   "idigbio:dateModified" : "2014-04-21T00:36:29.192Z",
   "idigbio:data" : {
      "dwc:identifiedBy" : "Andrew Salywon, Jan 2003",
      "dwc:catalogNumber" : "ASU0010142",
      "dwc:basisOfRecord" : "PreservedSpecimen",
      "symbiotaverbatimScientificName" : "Eugenia monticola",
      "dwc:collectionCode" : "Plants",
      "dwc:decimalLongitude" : "-64.7131",
      "dcterms:references" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=762944",
      "dwc:scientificNameAuthorship" : "Hitchc.",
      "dwc:collectionID" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
      "dwc:georeferenceSources" : "georef batch tool 2012-07-09",
      "dwc:georeferenceVerificationStatus" : "reviewed - high confidence",
      "dwc:occurrenceRemarks" : "Small tree. 3.0 m. Bark brown, stems smooth; flowers in buds yellow.",
      "dwc:otherCatalogNumbers" : "156664",
      "dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
      "dwc:decimalLatitude" : "18.348",
      "dwc:day" : "21",
      "idigbio:recordId" : "urn:uuid:ed400275-09d7-4302-b777-b4e0dcf7f2a3",
      "dwc:specificEpithet" : "monticola",
      "dwc:locality" : "Coral Bay Quarter, Bordeaux Mountain Road.",
      "dwc:occurrenceID" : "762944",
      "dwc:year" : "1987",
      "dwc:recordedBy" : "P. Acevedo; A. Reilly",
      "dwc:recordNumber" : "1897",
      "dwc:family" : "Myrtaceae",
      "dwc:scientificName" : "Eugenia monticola",
      "dwc:georeferencedBy" : "jssharpe",
      "dcterms:modified" : "2012-07-09 12:00:09",
      "dwc:country" : "U.S. Virgin Islands",
      "dwc:eventDate" : "1987-08-21",
      "dwc:reproductiveCondition" : "flowers",
      "dwc:startDayOfYear" : "233",
      "dwc:habitat" : "Sunny roadside.",
      "dwc:dynamicProperties" : "Small tree. 3.0 m. Bark brown, stems smooth; flowers in buds yellow.",
      "dwc:month" : "8",
      "dwc:stateProvince" : "Saint John",
      "dwc:genus" : "Eugenia",
      "dwc:coordinateUncertaintyInMeters" : "2000",
      "dwc:institutionCode" : "ASU"
   }
}

Back to contents


GET /v1/records/{UUID}/media

Description
Returns one or more HTTP redirects to a target image file (JPEG) that is associated with the specified iDigBio UUID (via the relationship to a mediarecord). If multiple mediarecords are associated with a specimen record, the particular mediarecord chosen by the API is non-deterministic. Omitting the "quality" parameter will return the full size image specified in the source data accessURI field and is usually served from the provider's infrastructure. Specifying the "quality" parameter will return a derivative image file that is hosted on iDigBio infrastructure. For many use cases, the recommended use of this endpoint would include the quality parameter. .
Resource URL
http://api.idigbio.org/v1/records/{UUID}/media
Optional Parameters
parameter valid values detailed description
quality "thumbnail" "webview" "fullsize" Specify the quality of the JPEG image returned from the API. The values "thumbnail" or "webview" return derivative images of width 260 and 600 pixels respectively. The value "fullsize" returns a derivative image that matches the size (width in pixels) of the original image. Omitting quality will return the full-size original image as specified in accessURI by the provider.
Sample Usage


Request a thumbnail image for a specimen record with iDigBio UUID of 182c9260-0151-454a-a648-4d58ddf51bd8 by issuing an HTTP "GET" to the following URL:

http://api.idigbio.org/v1/records/182c9260-0151-454a-a648-4d58ddf51bd8/media?quality=thumbnail

The response to the above URL is a series of HTTP Redirects that lead to a thumbnail image, illustrated here with the Firefox Web Developer Tools visible:

Screenshot firefox webdevtools thumbnail specimen 182c9260-0151-454a-a648-4d58ddf51bd8.png

Note that the final image URL should not be considered stable or permanent. Images can be moved around to various storage platforms. The iDigBio UUID of the Specimen Record will remain constant, but the containing data, including the image locations, may change over time.

Back to contents


GET /v1/organizations

Description
Deprecated, do not use.

Back to contents


GET /v1/people

Description
Deprecated, do not use.

Back to contents


GET /v1/publishers

Description
Returns a List of Publisher iDigBio UUIDs. Publishers are the top-level entities containing metadata about data publishing locations.
Resource URL
http://api.idigbio.org/v1/publishers


Optional Parameters
parameter valid values detailed description
limit 0, 1, 2, ..., 10, ..., n Controls the number of items returned.
offset 0, 1, 2, ..., 10, ..., n Controls the starting offset for paging through the API.
Sample Usage

Retrieve a List with only one publisher entity.

$ curl -s "http://api.idigbio.org/v1/publishers?limit=1" | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/publishers?limit=1&offset=1"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "publisher" : "http://api.idigbio.org/v1/publishers/076c0ff6-65e9-48a5-8e4b-2447936f9a1c"
         },
         "idigbio:uuid" : "076c0ff6-65e9-48a5-8e4b-2447936f9a1c",
         "idigbio:version" : 15,
         "idigbio:etag" : "154afad64618151ae4e39da1874acf7f0c86a6c2",
         "idigbio:dateModified" : "2014-04-18T19:14:53.966Z"
      }
   ],
   "idigbio:itemCount" : "20"
}

The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:

   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/publishers?limit=1&offset=1"
   },

More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in iDigBio API Examples.

Back to contents


GET /v1/publishers/{UUID}

Description
Returns a full Publisher Record matching the specified iDigBio UUID. A publisher record includes links to all of the recordsets provided to iDigBio by the publisher as well as other information about each recordset.
Resource URL
http://api.idigbio.org/v1/publishers/{UUID}
Optional Parameters
parameter valid values detailed description
version Numeric values from 0 to maximum version of a particular record Publisher records may be updated over time. The "version" parameter is used to retrieve a previous version of a record. A value of "-1" returns the most recent version of a record. Omitting the "version" parameter returns the most recent version of a record.
Sample Usage
$ curl -s http://api.idigbio.org/v1/publishers/a9dfa037-425b-442b-8974-94487c29114e | json_pp
{
   "idigbio:uuid" : "a9dfa037-425b-442b-8974-94487c29114e",
   "idigbio:etag" : "e436abe5ac4015449f885f74443abd48cc2ff7f4",
   "idigbio:links" : {
      "recordset" : [
         "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd",
         "http://api.idigbio.org/v1/recordsets/b531ea59-025d-4c29-9d23-99ae75bcd55f",
         "http://api.idigbio.org/v1/recordsets/c569e530-7322-40b8-9b66-1e0ed96fefcb"
      ]
   },
   "idigbio:version" : 9,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
      "http://swbiodiversity.org/seinet/webservices/dwc/rss.xml",
      "http://swbiodiversity.org/seinet/"
   ],
   "idigbio:dateModified" : "2014-04-18T15:15:19.172Z",
   "idigbio:data" : {
      "auto_publish" : false,
      "rss_url" : "http://swbiodiversity.org/seinet/webservices/dwc/rss.xml",
      "publisher_type" : "symbiota",
      "base_url" : "http://swbiodiversity.org/seinet/",
      "name" : "SEINet Darwin Core Archive rss feed",
      "recordsets" : {
         "http://swbiodiversity.org/seinet/webservices/dwc/17a53c97-835b-409e-8a9a-c9a7307a4965" : {
            "link" : "http://swbiodiversity.org/seinet/collections/datasets/dwc/ASC_DwC-A.zip",
            "contacts" : [
               {
                  "email" : "seinetadmin@asu.edu",
                  "first_name" : "Edward Gilbert"
               },
               {
                  "email" : "tina.ayers@nau.edu & deaver.herbarium@nau.edu",
                  "first_name" : "Tina Ayers"
               }
            ],
            "ingest" : true,
            "collection_description" : "Number of Specimens: 105 000 Specialty: Colorado Plateau, especially northern Arizona; northeastern Mojave Desert; northern Arizona National Parks and Monuments; vascular plants of the San Francisco Peaks and Coconino National Forest. Important Collections: M. Baker; R. E. Collom; C. F. Deaver; D. Demaree; R. K. Gierisch; L. N. Goodding; G. Goodwin; H. D. Hammond; R. H. Hevly; M. E. Jones; T. H. Kearney; Max Licher; E. L. Little, Jr.; V. O. Mayes; A. M. Phillips; G. R. Rink; C. G. Schaack; J. J. Thornber; A. F. Whiting Incorporated Herbaria: FSLF (1000 specimens) in 1989. Notes: Name for Arizona State College changed to Northern Arizona University in 1966. ASC fungi transferred to MICH in 1998. ASC is temporarily housing NAVA, until the Navajo Natural Heritage builds a new building. Date Founded: 1930. Number of Specimens: 105 000 Specialty: Colorado Plateau, especially northern Arizona; northeastern Mojave Desert; northern Arizona National Parks and Monuments; vascular plants of the San Francisco Peaks and Coconino National Forest. Important Collections: M. Baker; R. E. Collom; C. F. Deaver; D. Demaree; R. K. Gierisch; L. N. Goodding; G. Goodwin; H. D. Hammond; R. H. Hevly; M. E. Jones; T. H. Kearney; Max Licher; E. L. Little, Jr.; V. O. Mayes; A. M. Phillips; G. R. Rink; C. G. Schaack; J. J. Thornber; A. F. Whiting Incorporated Herbaria: FSLF (1000 specimens) in 1989. Notes: Name for Arizona State College changed to Northern Arizona University in 1966. ASC fungi transferred to MICH in 1998. ASC is temporarily housing NAVA, until the Navajo Natural Heritage builds a new building. Date Founded: 1930.",
            "logo_url" : "http://swbiodiversity.org/seinet/images/collicons/nauplant.jpg",
            "collection_name" : "Deaver Herbarium (Northern Arizona University)",
            "institution_web_address" : "http://nau.edu/Merriam-Powell/Biodiversity-Center/Deaver-Herbarium/",
            "id" : "http://swbiodiversity.org/seinet/webservices/dwc/17a53c97-835b-409e-8a9a-c9a7307a4965",
            "other_guids" : [],
            "update" : "2014-04-15T01:00:00"
         },
         "http://swbiodiversity.org/seinet/webservices/dwc/a2e32c87-d320-4a01-bafd-a9182ae2e191" : {
            "link" : "http://swbiodiversity.org/seinet/collections/datasets/dwc/ASU-Plants_DwC-A.zip",
            "contacts" : [
               {
                  "email" : "seinetadmin@asu.edu",
                  "first_name" : "Edward Gilbert"
               },
               {
                  "email" : "les.landrum@asu.edu",
                  "first_name" : "Leslie Landrum"
               }
            ],
            "ingest" : true,
            "collection_description" : "The Arizona State University Vascular Plant Herbarium is the second largest in the Arid Southwest with over 285,000 specimens. Our collection of Cactaceae is one of the best in the world, being particularly rich in cytological vouchers. The Arizona State University Vascular Plant Herbarium is the second largest in the Arid Southwest with over 285,000 specimens. Our collection of Cactaceae is one of the best in the world, being particularly rich in cytological vouchers.",
            "logo_url" : "http://swbiodiversity.org/seinet/images/collicons/asu.jpg",
            "collection_name" : "Arizona State University Vascular Plant Herbarium",
            "institution_web_address" : "http://lifesciences.asu.edu/herbarium/",
            "id" : "http://swbiodiversity.org/seinet/webservices/dwc/a2e32c87-d320-4a01-bafd-a9182ae2e191",
            "other_guids" : [],
            "update" : "2014-04-15T01:00:00"
         },
         "http://swbiodiversity.org/seinet/webservices/dwc/edb9860c-c481-4d19-88cc-224a536ebcd4" : {
            "link" : "http://swbiodiversity.org/seinet/collections/datasets/dwc/DES_DwC-A.zip",
            "contacts" : [
               {
                  "email" : "seinetadmin@asu.edu",
                  "first_name" : "Edward Gilbert"
               },
               {
                  "email" : "asalywon@dbg.org",
                  "first_name" : "Andrew Salywon"
               }
            ],
            "ingest" : true,
            "collection_description" : "Approximately 75000 specimens in collection, with emphasis on plants of the Southwest and northern Mexico, Cactaceae and Agavaceae. <div style="margin-top:10px"><b>Curator:</b> Wendy C. Hodgson (whodgson<at>dbg.org) </div> <div style="margin-top:10px"><b>Assistant Curator:</b> Andrew Salywon </div> Approximately 75000 specimens in collection, with emphasis on plants of the Southwest and northern Mexico, Cactaceae and Agavaceae. <div style="margin-top:10px"><b>Curator:</b> Wendy C. Hodgson (whodgson<at>dbg.org) </div> <div style="margin-top:10px"><b>Assistant Curator:</b> Andrew Salywon </div>",
            "logo_url" : "http://swbiodiversity.org/seinet/images/collicons/des.jpg",
            "collection_name" : "Desert Botanical Garden Herbarium Collection",
            "institution_web_address" : "http://www.dbg.org/",
            "id" : "http://swbiodiversity.org/seinet/webservices/dwc/edb9860c-c481-4d19-88cc-224a536ebcd4",
            "other_guids" : [],
            "update" : "2014-04-15T01:00:00"
         }
      }
   }
}

Back to contents


GET /v1/publishers/{UUID}/recordsets

Description
Return a List of recordset iDigBio UUIDs that are associated with the Publisher of the specified iDigBio UUID (returns a list of recordsets that are published by a particular Publisher).
Resource URL
http://api.idigbio.org/v1/publishers/{UUID}/recordsets


Optional Parameters
parameter valid values detailed description
limit 0, 1, 2, ..., 10, ..., n Controls the number of items returned.
offset 0, 1, 2, ..., 10, ..., n Controls the starting offset for paging through the API.
Sample Usage
$ curl -s http://api.idigbio.org/v1/publishers/d347ee15-f16e-4650-930c-4e54d9ce549e/recordsets | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {},
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/271a9ce9-c6d3-4b63-a722-cb0adc48863f"
         },
         "idigbio:uuid" : "271a9ce9-c6d3-4b63-a722-cb0adc48863f"
      }
   ],
   "idigbio:itemCount" : "1"
}

Back to contents


GET /v1/recordsets

Description
Returns a List of recordset iDigBio UUIDs. A recordset is a group of published data.
Resource URL
http://api.idigbio.org/v1/recordsets
Optional Parameters
parameter valid values detailed description
limit 0, 1, 2, ..., 10, ..., n Controls the number of items returned.
offset 0, 1, 2, ..., 10, ..., n Controls the starting offset for paging through the API.
Sample Usage

Request a List of recordset iDigBio UUIDs (and in this usage example, limit the number of results to 3):

$ curl -s http://api.idigbio.org/v1/recordsets?limit=3 | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets?limit=3&offset=3"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/0072bf11-a354-4998-8730-c0cb4cfc9517"
         },
         "idigbio:uuid" : "0072bf11-a354-4998-8730-c0cb4cfc9517",
         "idigbio:version" : 2,
         "idigbio:etag" : "c6df1d0673b5452af4118caf96c5c066b498e095",
         "idigbio:dateModified" : "2014-04-18T17:54:38.751Z"
      },
      {
         "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/00d9fcc1-c8e2-4ef6-be64-9994ca6a32c3"
         },
         "idigbio:uuid" : "00d9fcc1-c8e2-4ef6-be64-9994ca6a32c3",
         "idigbio:version" : 3,
         "idigbio:etag" : "3d3c08b1155db3353048648fae23d05ca52e3a24",
         "idigbio:dateModified" : "2014-04-18T17:54:32.657Z"
      },
      {
         "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/02fceae6-c71c-4db9-8b2f-e235ced6624a"
         },
         "idigbio:uuid" : "02fceae6-c71c-4db9-8b2f-e235ced6624a",
         "idigbio:version" : 2,
         "idigbio:etag" : "28b6a174e77f4f81f22dbf9b463a89d3b6b479a9",
         "idigbio:dateModified" : "2014-04-18T17:54:50.955Z"
      }
   ],
   "idigbio:itemCount" : "255"
}

The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:

   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets?limit=3&offset=3"
   },

More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in iDigBio API Examples.

Back to contents


GET /v1/recordsets/{UUID}

Description
Returns the full Recordset record with the specified iDigBio UUID.
Resource URL
http://api.idigbio.org/v1/recordsets/{UUID}
Parameters


parameter valid values detailed description
version Integer values from 0 to maxium version of a particular record Recordset Records may be updated over time (changes submitted by data publishers). The "version" parameter is used to retrieve a previous version of a record. A value of "-1" returns the most recent version of a record. Omitting the "version" parameter returns the most recent version of a record.
Sample Usage
$ curl -s http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f | json_pp
{
   "idigbio:uuid" : "7a8d946d-083f-4d2a-9cc9-cd590398194f",
   "idigbio:etag" : "29105ddc719b92504fdc619d0be225c5fb6d3341",
   "idigbio:links" : {
      "mediarecord" : [
         "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/mediarecords"
      ],
      "owner" : [
         "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "record" : [
         "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/records"
      ],
      "publisher" : [
         "http://api.idigbio.org/v1/publishers/1c29be70-24e7-480b-aab1-61224ded0f34"
      ]
   },
   "idigbio:version" : 0,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
      "http://portal.neherbaria.org/portal/webservices/dwc/cedd578e-3475-4eb9-b6a9-c630f417ffc6"
   ],
   "idigbio:dateModified" : "2014-04-30T21:01:28.391Z",
   "idigbio:data" : {
      "link" : "http://portal.neherbaria.org/portal/collections/datasets/dwc/YPM-YU_DwC-A.zip",
      "contacts" : [
         {
            "email" : "patrick.sweeney@yale.edu",
            "first_name" : "General Administrator"
         },
         {
            "email" : "patrick.sweeney@yale.edu",
            "first_name" : "Patrick W. Sweeney"
         }
      ],
      "ingest" : true,
      "collection_description" : "Founded in 1864 by Daniel Cady Eaton from his personal library and plant collection, the Yale Herbarium is an internationally recognized repository with holdings of approximately 350,000 specimens from throughout the world. There are an estimated 5,000 type specimens. The collection is particularly rich in ferns, bryophytes and grasses, as well as in historically important materials from the early botanical collectors. In addition, it was the herbarium of record for the flora of southern New England from 1864 until 1955, when that function passed to the University of Connecticut at Storrs. Founded in 1864 by Daniel Cady Eaton from his personal library and plant collection, the Yale Herbarium is an internationally recognized repository with holdings of approximately 350,000 specimens from throughout the world. There are an estimated 5,000 type specimens. The collection is particularly rich in ferns, bryophytes and grasses, as well as in historically important materials from the early botanical collectors. In addition, it was the herbarium of record for the flora of southern New England from 1864 until 1955, when that function passed to the University of Connecticut at Storrs.",
      "logo_url" : "http://portal.neherbaria.org/portal/images/collicons/YU_logo_60.gif",
      "collection_name" : "Yale University Herbarium, Peabody Museum of Natural History",
      "institution_web_address" : "http://www.peabody.yale.edu/collections/bot/",
      "id" : "http://portal.neherbaria.org/portal/webservices/dwc/cedd578e-3475-4eb9-b6a9-c630f417ffc6",
      "other_guids" : [],
      "update" : "2014-04-17T01:00:00"
   }
}

Back to contents


GET /v1/recordsets/{UUID}/mediarecords

Description
Returns a List of Media Record iDigBio UUIDs that belong to the recordset of the specified iDigBio UUID.
Resource URL
http://api.idigbio.org/v1/recordsets/{UUID}/mediarecords
Optional Parameters
parameter valid values detailed description
limit 0, 1, 2, 10, ..., 100, ..., 1000, ..., n Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
offset 0, 1, 2, ... 100, ..., 1000, ..., n Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
Sample Usage

Return a List of mediarecord iDigBio UUIDs that belong to a particular recordset (and in this usage example, limit the number of results to 1):

$ curl -s http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/mediarecords?limit=1 | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/mediarecords?limit=1&offset=1"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/0002429e-28a5-46ee-8bce-c4a7bc3870d9"
         },
         "idigbio:uuid" : "0002429e-28a5-46ee-8bce-c4a7bc3870d9"
      }
   ],
   "idigbio:itemCount" : "14897"
}

The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:

   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/mediarecords?limit=1&offset=1"
   },

More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in iDigBio API Examples.

DO NOT expect to be able to page through the entire iDigBio data this way. See iDigBio API Performance if you find yourself trying to page through large amounts of data.

Back to contents


GET /v1/recordsets/{UUID}/records

Description
Returns a List of iDigBio UUIDs that belong to the recordset of the specified entity ID.
Resource URL
http://api.idigbio.org/v1/recordsets/{UUID}/records
Optional Parameters
parameter valid values detailed description
limit 0, 1, 2, 10, ..., 100, ..., 1000, ..., n Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
offset 0, 1, 2, ... 1000, ..., 10000, ..., n Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
Sample Usage

Return a list with a single record item that belongs to the recordset of the specified iDigBio UUID:

$ curl -s http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/records?limit=1 | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/records?limit=1&offset=1"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/0002b73f-9c48-477f-b90e-13c86733f1ab"
         },
         "idigbio:uuid" : "0002b73f-9c48-477f-b90e-13c86733f1ab"
      }
   ],
   "idigbio:itemCount" : "18889"
}


The next "page" of records can be requested by adding the "offset" parameter, which is already provided in the "links" section of the returned data:

   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/recordsets/7a8d946d-083f-4d2a-9cc9-cd590398194f/records?limit=1&offset=1"
   },

More thorough examples of using the nextPage and prevPage links as well as "offset" and "limit" are in iDigBio API Examples.

DO NOT expect to be able to page through the entire iDigBio data this way. See iDigBio API Performance if you find yourself trying to page through large amounts of data.

Back to contents


GET /v1/taxa

Description
Deprecated, do not use.

Back to contents


Search

Caution! Caution: Direct queries to the iDigBio Elasticsearch service are deprecated. The iDigBio API v2 / iDigBio Search API specification should be used instead. The public-facing interface to the iDigBio back-end Elasticsearch system will likely be disabled at some point in the future.


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

The query string is appended to the URL as a parameter named "q" and follows the following pattern:

http://search.idigbio.org/idigbio/records/_search?&q=term:value

The number of records returned can be adjusted with the "size" parameter.

Search examples that are specific to iDigBio are available in iDigBio API Examples.

In most cases, iDigBio Elasticsearch terms are generated by dropping the leading namespace and colon, then lowercasing the remaining portion. This was done for a number of reasons including the fact that Elasticsearch itself uses colons in the query syntax.

Some examples:

Definition DwC Term / iDigBio API Record Field iDigBio Elasticsearch Index Term
Scientific Name dwc:scientificName scientificname
Institution Code dwc:institutionCode institutioncode
iDigBio Record UUID idigbio:uuid uuid
... ... ...


Back to contents


Elasticsearch - Records

Caution! Caution: Direct queries to the iDigBio Elasticsearch service are deprecated. The iDigBio API v2 / iDigBio Search API specification should be used instead.


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.

Back to contents


Elasticsearch - Media Records

Caution! Caution: Direct queries to the iDigBio Elasticsearch service are deprecated. The iDigBio API v2 / iDigBio Search API specification should be used instead.


Media Records Query URL:

https://search.idigbio.org/idigbio/mediarecords/_search

The following terms are currently available in the index for Media Records type of queries to Elasticsearch:

recordset
uuid

See iDigBio API Examples page for more Elasticsearch examples that are specific to iDigBio.

Back to contents


Response and Error Codes

The API returns standard HTTP status codes. Errors will likely not return a JSON document so your code should handle the raw HTTP status codes.