IDigBio API v1 Specification

API Version Information

This is the specification for v1 of the iDigBio API. Previous versions of the API continue to exist but should be considered deprecated. API users should migrate to using the current version of the API. This document supercedes iDigBio API v0 Specification.

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, successful responses from the API will return a JSON-formatted document.

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.

There are two major types of API enpoints:

• 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 endpoint properties section for more information on properties returned.

• 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.

Examples:

collection:
"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"

Back to contents

---

GET /

Description

Returns a list of top-level api_version 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 collection (list) of Media Record entities.

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 entities returned by a collection url. 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 entity 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 5 media record entities:

$ 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. A Media Record contains metadata about 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 an image file (JPEG) or (one or more) HTTP Redirects to an image file 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"	Specifiy the quality of the image returned from the API. Omitting quality will return the full-size original image. The values "thumbnail" and "webview" return derivative images of width 260 and 600 pixels respectively.

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:

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 collection (list) of Specimen Record entities

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 entities returned by a collection url. 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 entity 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 5 specimen record entity ids:

$ 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 Specimen Record matching the specific iDigBio UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field.

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 an image file (JPEG) associated with the specific iDigBio UUID (via the relationship to a mediarecord). If multiple mediarecords are associated with a specimen record, the particular image returned in non-deterministic.

Resource URL

http://api.idigbio.org/v1/records/{UUID}/media

Optional Parameters

parameter	valid values	detailed description
quality	"thumbnail" "webview"	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.

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:

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 collection (list) of publisher entities.

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 entities returned.
offset	0, 1, 2, ..., 10, ..., n	Controls the starting entity 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 that matches 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.

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/recordsets

Description

Returns a list of recordset entities.

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 entities returned.
offset	0, 1, 2, ..., 10, ..., n	Controls the starting entity offset for paging through the API.

Sample Usage

Request 3 recordset entities:

$ 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 record about a recordset 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 mediarecord IDs that belong to the particular 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 entities returned by a collection url. 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 entity 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 mediarecord that belongs to a particular recordset.

$ 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 record IDs 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 entities returned by a collection url. 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 entity 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

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.

• Elasticsearch Query Domain Specific Language (DSL)
• URI Search

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

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

Back to contents

---

Elasticsearch - Records

Specimen Records Query URL:

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

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

"barcodevalue"
"catalognumber"
"class"
"collectioncode"
"collectionid"
"collectionname"
"collector"
"commonname"
"continent"
"country"
"county"
"datecollected"
"datemodified"
"etag"
"family"
"fieldnumber"
"genus"
"geopoint"
"hasImage"
"highertaxon"
"infraspecificepithet"
"institutioncode"
"institutionid"
"institutionname"
"kingdom"
"locality"
"maxdepth"
"maxelevation"
"mediarecords"
"mindepth"
"minelevation"
"municipality"
"occurenceid"
"order"
"phylum"
"recordset"
"scientificname"
"specificepithet"
"stateprovince"
"typestatus"
"uuid"
"verbatimlocality"
"version"
"waterbody"

The values stored in these terms are converted to lowercase, so searches based on terms should use the all-lowercase version of the string.

For example, searching for "Arkansas" in stateprovince will return no records.

$ curl -s "http://search.idigbio.org/idigbio/records/_search?q=stateprovince:Arkansas" | json_pp | grep scientificname | wc -l
0

Searching for "arkansas" will return multiple records.

$ curl -s "http://search.idigbio.org/idigbio/records/_search?q=stateprovince:arkansas" | json_pp | grep scientificname | wc -l
10

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

Back to contents

---

Elasticsearch - Media Records

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

---