IDigBio API v1 Examples
This document is a list of examples for using the IDigBio API but may not be comprehensive to cover every feature of the API. See iDigBio API v1 Specification for full documentation on the API including all of the available endpoints and parameters.
Viewing JSON Output
Javascript Object Notation (JSON), is an open standard format that uses human-readable text to transmit data objects consisting of attribute–value pairs. JSON has become a common format for interchanging data via APIs and especially modern Web Services. Effective use of the iDigBio API will require some understanding of JSON.
Most of the examples provided here will be shown using the curl command-line tool. Here are some of the more commonly used curl options (for descriptions and additional usage information, see the curl man page):
$ man curl
...
-s, --silent
-i, --include
-v, --verbose
-X, --request <command>
-d, --data <data>
...
A short JSON document is returned by the API when calling the HTTP "GET" method (curl's default) against the base URL:
$ curl http://api.idigbio.org/
{"v1":"http://api.idigbio.org/v1/","v0":"http://api.idigbio.org/v0/","check":"http://api.idigbio.org/check"}
It may be useful to inspect the API's JSON document outputs using a "pretty printing" feature of some kind. This will make it more readable by humans and also allow it to be more easily filtered using tools such as grep. Two common tools for this available on Unix/Linux are python's json.tool module or the json_pp command-line Perl script (JSON::PP). In typical Unix fashion, these tools can receive input from a pipe and be used to chain multiple commands together.
There are also ways of viewing JSON inside of a web browser.
Most of our examples in this document will include piping the JSON document into json_pp.
JSONView Web Browser Extension
For best viewing of JSON results in a browser, one may wish to use the JSONView Extension which is available for Firefox and Chrome.
Here is a screenshot of the output using the JSONView extension after requesting the same API base URL:
json.tool (Python)
Current installations of Python typically include a json module in the standard installed libraries.
$ curl -s http://api.idigbio.org/ | python -m json.tool
{
"check": "http://api.idigbio.org/check",
"v0": "http://api.idigbio.org/v0/",
"v1": "http://api.idigbio.org/v1/"
}
json_pp (Perl)
Similarly, modern Perl installations typically include the json_pp script or it can be aquired from CPAN.
$ 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/"
}
simplejson.tool (Python)
If a Python installation is misssing the json standard library, the separate simplejson package may solve the problem.
Install the Python simplejson module on Debian / Ubuntu Linux with:
$ sudo apt-get install python-simplejson
Install the Python simplejson on Red Hat / CentOS Linux with:
$ # log in as root or use sudo $ yum install python-simplejson
The simplejson.tool module can be invoked in the same way as json.tool:
$ curl -s http://api.idigbio.org/ | python -m simplejson.tool
{
"check": "http://api.idigbio.org/check",
"v0": "http://api.idigbio.org/v0/",
"v1": "http://api.idigbio.org/v1/"
}
Older versions of python also may require a more complicated syntax to invoke the module from the command line.
$ curl -s http://api.idigbio.org/ | python -c'from simplejson.tool import main; main()'
{
"check": "http://api.idigbio.org/check",
"v0": "http://api.idigbio.org/v0/",
"v1": "http://api.idigbio.org/v1/"
}
Three ways to fetch a specific record based on iDigBio GUID
The following three examples intend to illustrate the various methods for looking up a unique record in iDigBio and how the output may differ for the same record.
The data returned by the Elasticsearch interface may differ from the raw API record, especially with regards to field names, since the Elasticsearch data has been normalized and indexed for consumption by the search portal.
For these three examples, consider the iDigBio specimen record identified by the following GUID:
"idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430"
Use the API
The complete record that was provided to iDigBio is stored in the API and can be retrieved by referencing the iDigBio GUID ("idigbio:uuid") as the entity ID at the '/records/{ID}' endpoint.
The following command sends the query as an HTTP GET request:
$ curl -s https://api.idigbio.org/v1/records/0cec43d8-9ad5-478a-bea1-397ab5cc4430 | json_pp
{
"idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"idigbio:links" : {
"mediarecord" : [
"http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
]
},
"idigbio:version" : 1,
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"idigbio:recordIds" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"idigbio:dateModified" : "2014-04-20T23:11:09.437Z",
"idigbio:data" : {
"dwc:catalogNumber" : "ASU0000166",
"dwc:basisOfRecord" : "PreservedSpecimen",
"symbiotaverbatimScientificName" : "Abies",
"dwc:collectionCode" : "Plants",
"dwc:decimalLongitude" : "-105.859665870667",
"dcterms:references" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=784316",
"dwc:scientificNameAuthorship" : "P. Mill.",
"dwc:collectionID" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
"dwc:minimumElevationInMeters" : "2316",
"dwc:georeferenceSources" : "georef batch tool 2013-05-10",
"dwc:georeferenceVerificationStatus" : "reviewed - high confidence",
"dwc:occurrenceRemarks" : "Tree to 4 m; occasional in N-facing barranca",
"dwc:otherCatalogNumbers" : "153418",
"dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"dwc:decimalLatitude" : "23.5821004818154",
"dwc:day" : "14",
"idigbio:recordId" : "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a",
"dwc:locality" : "Ca. 1 mi N of Hwy 40 between Villa Union and Cd. Durango, and ca. 5 mi W of Durango state border.",
"dwc:occurrenceID" : "784316",
"dwc:year" : "1985",
"dwc:recordedBy" : "T. F. Daniel; ",
"dwc:family" : "Pinaceae",
"dwc:scientificName" : "Abies",
"dwc:georeferencedBy" : "cjsdavis",
"dwc:recordNumber" : "4031",
"dcterms:modified" : "2013-05-10 13:39:12",
"dwc:country" : "Mexico",
"dwc:eventDate" : "1985-03-14",
"dwc:verbatimElevation" : "7600ft",
"dwc:startDayOfYear" : "73",
"dwc:habitat" : "Pine-oak forest, in N-facing barranca.",
"dwc:dynamicProperties" : "Tree to 4 m; occasional in N-facing barranca",
"dwc:month" : "3",
"dwc:stateProvince" : "Sinaloa",
"dwc:genus" : "Abies",
"dwc:coordinateUncertaintyInMeters" : "1000",
"dwc:institutionCode" : "ASU"
}
}
Elasticsearch
The normalized and indexed record that is stored in Elasticsearch can be retrieved by referencing the iDigBio GUID ("uuid") as the term provided to the query string parameter.
The list of available terms in the iDigBio index is available at IDigBio_API#Elasticsearch_-_Records.
Use the Elasticsearch URI Search
The following command sends the query as an HTTP GET request:
$ curl -s "https://search.idigbio.org/idigbio/records/_search?q=uuid:0cec43d8-9ad5-478a-bea1-397ab5cc4430" | json_pp
{
"hits" : {
"hits" : [
{
"_source" : {
"collectioncode" : "plants",
"datecollected" : "1985-03-14",
"recordids" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"geopoint" : {
"lat" : 23.5821004818154,
"lon" : -105.859665870667
},
"uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"locality" : "ca. 1 mi n of hwy 40 between villa union and cd. durango, and ca. 5 mi w of durango state border.",
"minelevation" : 2316,
"collectionid" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
"datecollected_rejected" : false,
"datemodified_rejected" : false,
"recordset" : "40250f4d-7aa6-4fcc-ac38-2868fa4846bd",
"mediarecords" : [
"db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"stateprovince" : "sinaloa",
"country" : "mexico",
"collector" : "t. f. daniel;",
"geopoint_rejected" : false,
"hasImage" : true,
"genus" : "abies",
"data" : {
"idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"idigbio:links" : {
"mediarecord" : [
"http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
]
},
"idigbio:version" : 1,
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"idigbio:recordIds" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"idigbio:data" : {
"dwc:catalogNumber" : "ASU0000166",
"dwc:basisOfRecord" : "PreservedSpecimen",
"symbiotaverbatimScientificName" : "Abies",
"idigbio:links" : {
"mediarecord" : [
"http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
]
},
"dwc:collectionCode" : "Plants",
"dwc:decimalLongitude" : "-105.859665870667",
"dcterms:references" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=784316",
"dwc:scientificNameAuthorship" : "P. Mill.",
"dwc:collectionID" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
"dwc:minimumElevationInMeters" : "2316",
"dwc:georeferenceSources" : "georef batch tool 2013-05-10",
"dwc:georeferenceVerificationStatus" : "reviewed - high confidence",
"dwc:occurrenceRemarks" : "Tree to 4 m; occasional in N-facing barranca",
"dwc:otherCatalogNumbers" : "153418",
"dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"idigbio:version" : 1,
"idigbio:recordIds" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"dwc:decimalLatitude" : "23.5821004818154",
"dwc:day" : "14",
"idigbio:recordId" : "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a",
"dwc:locality" : "Ca. 1 mi N of Hwy 40 between Villa Union and Cd. Durango, and ca. 5 mi W of Durango state border.",
"dwc:occurrenceID" : "784316",
"idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"dwc:year" : "1985",
"dwc:recordedBy" : "T. F. Daniel; ",
"dwc:recordNumber" : "4031",
"dwc:georeferencedBy" : "cjsdavis",
"dwc:scientificName" : "Abies",
"dwc:family" : "Pinaceae",
"dcterms:modified" : "2013-05-10 13:39:12",
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"dwc:country" : "Mexico",
"idigbio:dateModified" : "2014-04-20T23:11:09.437Z",
"dwc:eventDate" : "1985-03-14",
"dwc:verbatimElevation" : "7600ft",
"idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"dwc:startDayOfYear" : "73",
"dwc:habitat" : "Pine-oak forest, in N-facing barranca.",
"dwc:dynamicProperties" : "Tree to 4 m; occasional in N-facing barranca",
"dwc:month" : "3",
"dwc:stateProvince" : "Sinaloa",
"dwc:genus" : "Abies",
"dwc:coordinateUncertaintyInMeters" : "1000",
"dwc:institutionCode" : "ASU"
},
"idigbio:dateModified" : "2014-04-20T23:11:09.437Z"
},
"datemodified" : "2014-04-20",
"scientificname" : "abies",
"minelevation_rejected" : false,
"catalognumber" : "asu0000166",
"etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"mindepth_rejected" : false,
"maxelevation_rejected" : false,
"maxdepth_rejected" : false,
"recordnumber" : "4031",
"family" : "pinaceae",
"institutioncode" : "asu"
},
"_score" : 14.687269,
"_index" : "idigbio-1.1.0",
"_id" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"_type" : "records"
}
],
"max_score" : 14.687269,
"total" : 1
},
"timed_out" : false,
"_shards" : {
"failed" : 0,
"successful" : 10,
"total" : 10
},
"took" : 5
}
Use the Elasticsearch Request Body Search
A JSON query document can be specified on the command-line. Again we are searching for the iDigBio GUID in the "uuid" term.
The following command sends the query as an HTTP POST request:
$ curl -s https://search.idigbio.org/idigbio/records/_search -d'
{
"filter" : {
"term" : { "uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430" }
}
}
' | json_pp
and give the following result:
{
"hits" : {
"hits" : [
{
"_source" : {
"collectioncode" : "plants",
"datecollected" : "1985-03-14",
"recordids" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"geopoint" : {
"lat" : 23.5821004818154,
"lon" : -105.859665870667
},
"uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"locality" : "ca. 1 mi n of hwy 40 between villa union and cd. durango, and ca. 5 mi w of durango state border.",
"minelevation" : 2316,
"collectionid" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
"datecollected_rejected" : false,
"datemodified_rejected" : false,
"recordset" : "40250f4d-7aa6-4fcc-ac38-2868fa4846bd",
"mediarecords" : [
"db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"stateprovince" : "sinaloa",
"country" : "mexico",
"collector" : "t. f. daniel;",
"geopoint_rejected" : false,
"hasImage" : true,
"genus" : "abies",
"data" : {
"idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"idigbio:links" : {
"mediarecord" : [
"http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
]
},
"idigbio:version" : 1,
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"idigbio:recordIds" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"idigbio:data" : {
"dwc:catalogNumber" : "ASU0000166",
"dwc:basisOfRecord" : "PreservedSpecimen",
"symbiotaverbatimScientificName" : "Abies",
"idigbio:links" : {
"mediarecord" : [
"http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
]
},
"dwc:collectionCode" : "Plants",
"dwc:decimalLongitude" : "-105.859665870667",
"dcterms:references" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=784316",
"dwc:scientificNameAuthorship" : "P. Mill.",
"dwc:collectionID" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
"dwc:minimumElevationInMeters" : "2316",
"dwc:georeferenceSources" : "georef batch tool 2013-05-10",
"dwc:georeferenceVerificationStatus" : "reviewed - high confidence",
"dwc:occurrenceRemarks" : "Tree to 4 m; occasional in N-facing barranca",
"dwc:otherCatalogNumbers" : "153418",
"dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"idigbio:version" : 1,
"idigbio:recordIds" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"dwc:decimalLatitude" : "23.5821004818154",
"dwc:day" : "14",
"idigbio:recordId" : "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a",
"dwc:locality" : "Ca. 1 mi N of Hwy 40 between Villa Union and Cd. Durango, and ca. 5 mi W of Durango state border.",
"dwc:occurrenceID" : "784316",
"idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"dwc:year" : "1985",
"dwc:recordedBy" : "T. F. Daniel; ",
"dwc:recordNumber" : "4031",
"dwc:georeferencedBy" : "cjsdavis",
"dwc:scientificName" : "Abies",
"dwc:family" : "Pinaceae",
"dcterms:modified" : "2013-05-10 13:39:12",
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"dwc:country" : "Mexico",
"idigbio:dateModified" : "2014-04-20T23:11:09.437Z",
"dwc:eventDate" : "1985-03-14",
"dwc:verbatimElevation" : "7600ft",
"idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"dwc:startDayOfYear" : "73",
"dwc:habitat" : "Pine-oak forest, in N-facing barranca.",
"dwc:dynamicProperties" : "Tree to 4 m; occasional in N-facing barranca",
"dwc:month" : "3",
"dwc:stateProvince" : "Sinaloa",
"dwc:genus" : "Abies",
"dwc:coordinateUncertaintyInMeters" : "1000",
"dwc:institutionCode" : "ASU"
},
"idigbio:dateModified" : "2014-04-20T23:11:09.437Z"
},
"datemodified" : "2014-04-20",
"scientificname" : "abies",
"minelevation_rejected" : false,
"catalognumber" : "asu0000166",
"etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"mindepth_rejected" : false,
"maxelevation_rejected" : false,
"maxdepth_rejected" : false,
"recordnumber" : "4031",
"family" : "pinaceae",
"institutioncode" : "asu"
},
"_score" : 1,
"_index" : "idigbio-1.1.0",
"_id" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"_type" : "records"
}
],
"max_score" : 1,
"total" : 1
},
"timed_out" : false,
"_shards" : {
"failed" : 0,
"successful" : 10,
"total" : 10
},
"took" : 37
}
Alternatively, the JSON-formatted query body can be stored in a file. In this example, the file is named uuid.json and contains the iDigBio GUID in the "uuid" term as before:
$ cat uuid.json
{
"filter" : {
"term" : { "uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430" }
}
}
We tell curl to use the file as the source of the data with the at '@' sign.
$ curl -s -XGET https://search.idigbio.org/idigbio/records/_search -d@uuid.json | json_pp
{
"hits" : {
"hits" : [
{
"_source" : {
"collectioncode" : "plants",
"datecollected" : "1985-03-14",
"uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"geopoint_geohash_6" : "9shwph",
"locality" : "ca. 1 mi n of hwy 40 between villa union and cd. durango, and ca. 5 mi w of durango state border.",
"minelevation" : 231,
"collectionid" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
"datecollected_rejected" : false,
"datemodified_rejected" : false,
"geopoint_geohash_5" : "9shwp",
"recordset" : "40250f4d-7aa6-4fcc-ac38-2868fa4846bd",
"geopoint_rejected" : false,
"hasImage" : true,
"data" : {
"idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"idigbio:links" : {
"mediarecord" : [
"http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
]
},
"idigbio:version" : 1,
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"idigbio:recordIds" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"idigbio:data" : {
"dwc:catalogNumber" : "ASU0000166",
"dwc:basisOfRecord" : "PreservedSpecimen",
"symbiotaverbatimScientificName" : "Abies",
"idigbio:links" : {
"mediarecord" : [
"http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
]
},
"dwc:collectionCode" : "Plants",
"dwc:decimalLongitude" : "-105.859665870667",
"dcterms:references" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=784316",
"dwc:scientificNameAuthorship" : "P. Mill.",
"dwc:collectionID" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
"dwc:minimumElevationInMeters" : "2316",
"dwc:georeferenceSources" : "georef batch tool 2013-05-10",
"dwc:georeferenceVerificationStatus" : "reviewed - high confidence",
"dwc:occurrenceRemarks" : "Tree to 4 m; occasional in N-facing barranca",
"dwc:otherCatalogNumbers" : "153418",
"dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"idigbio:version" : 1,
"idigbio:recordIds" : [
"urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
],
"dwc:decimalLatitude" : "23.5821004818154",
"dwc:day" : "14",
"idigbio:recordId" : "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a",
"dwc:locality" : "Ca. 1 mi N of Hwy 40 between Villa Union and Cd. Durango, and ca. 5 mi W of Durango state border.",
"dwc:occurrenceID" : "784316",
"idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"dwc:year" : "1985",
"dwc:recordedBy" : "T. F. Daniel; ",
"dwc:recordNumber" : "4031",
"dwc:georeferencedBy" : "cjsdavis",
"dwc:scientificName" : "Abies",
"dwc:family" : "Pinaceae",
"dcterms:modified" : "2013-05-10 13:39:12",
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"dwc:country" : "Mexico",
"idigbio:dateModified" : "2014-04-20T23:11:09.437Z",
"dwc:eventDate" : "1985-03-14",
"dwc:verbatimElevation" : "7600ft",
"idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"dwc:startDayOfYear" : "73",
"dwc:habitat" : "Pine-oak forest, in N-facing barranca.",
"dwc:dynamicProperties" : "Tree to 4 m; occasional in N-facing barranca",
"dwc:month" : "3",
"dwc:stateProvince" : "Sinaloa",
"dwc:genus" : "Abies",
"dwc:coordinateUncertaintyInMeters" : "1000",
"dwc:institutionCode" : "ASU"
},
"idigbio:dateModified" : "2014-04-20T23:11:09.437Z"
},
"scientificname" : "abies",
"minelevation_rejected" : false,
"etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
"maxdepth_rejected" : false,
"family" : "pinaceae",
"institutioncode" : "asu",
"geopoint" : {
"lat" : 23.5821004818154,
"lon" : -105.859665870667
},
"fieldnumber" : "4031",
"geopoint_geohash_2" : "9s",
"stateprovince" : "sinaloa",
"mediarecords" : [
"db38f86b-99f5-4dc4-b4a6-a045a9c35323"
],
"country" : "mexico",
"collector" : "t. f. daniel;",
"geopoint_geohash_4" : "9shw",
"version" : 1,
"genus" : "abies",
"geopoint_geohash_3" : "9sh",
"datemodified" : "2014-04-20",
"catalognumber" : "asu0000166",
"mindepth_rejected" : false,
"maxelevation_rejected" : false
},
"_score" : 1,
"_index" : "idigbio-1.0.0",
"_id" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
"_type" : "records"
}
],
"max_score" : 1,
"total" : 1
},
"timed_out" : false,
"_shards" : {
"failed" : 0,
"successful" : 10,
"total" : 10
},
"took" : 64
}
Fetch an Older Version of a Particular Media Record
Consider an iDigBio Media Record "idigbio:uuid" : "ff5fd841-6bc6-4241-80d3-def7e1b6d5e8" with multiple revisions of the record. The API shows that the current version of this particular record is version 1.
$ curl -s http://api.idigbio.org/v1/mediarecords/ff5fd841-6bc6-4241-80d3-def7e1b6d5e8 | json_pp | grep version "idigbio:version" : 1,
We would like to look at the previous version (version 0) to see what has changed. We do this by adding ?version=0 as a parameter to the URL.
$ curl -s http://api.idigbio.org/v1/mediarecords/ff5fd841-6bc6-4241-80d3-def7e1b6d5e8?version=0 | json_pp
{
"idigbio:uuid" : "ff5fd841-6bc6-4241-80d3-def7e1b6d5e8",
"idigbio:etag" : "0a9effd5fc2803e87e4236e03a33ba3d00c3b305",
"idigbio:links" : {
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"record" : [
"http://api.idigbio.org/v1/records/aebc99d6-3ba8-4d55-9434-83364b98d9b6"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/e70af26a-fb9e-43ab-96a0-d62a2df37e6d"
]
},
"idigbio:version" : "0",
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"idigbio:recordIds" : [
"e70af26a-fb9e-43ab-96a0-d62a2df37e6d\\media\\urn:catalog:UConn:CONN:Image:CONN00175018"
],
"idigbio:dateModified" : "2014-03-05T23:38:31.326Z",
"idigbio:data" : {
"ac:licenseLogoURL" : "http://mirrors.creativecommons.org/presskit/buttons/80x15/png/by-nc-sa.png",
"ac:metadataLanguage" : "eng",
"dwc:occurrenceID" : "urn:catalog:UConn:CONN:CONN00175018",
"xmpRights:WebStatement" : "http://creativecommons.org/licenses/by-nc-sa/4.0/",
"ac:bestQualityAccessURI" : "http://bgbaseserver.eeb.uconn.edu/DATABASEIMAGES/CONN00175018.JPG",
"ac:bestQualityFormat" : "image/jpeg",
"dcterms:creator" : "CONN",
"dcterms:type" : "StillImage",
"xmpRights:Owner" : "G. S. Torrey Herbarium, University of Connecticut",
"dcterms:rights" : "© 2003 University of Connecticut",
"dcterms:title" : "specimen image",
"dcterms:identifier" : "urn:catalog:UConn:CONN:Image:CONN00175018"
}
}
Fetch five MediaRecord IDs (endpoints) from the API
Example URL:
http://api.idigbio.org/v1/mediarecords?limit=5
Example API Results:
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" : 2,
"idigbio:etag" : "c13b10675b4a83031b1dc7a24c1f5c4e443b1939",
"idigbio:dateModified" : "2014-04-03T17:43:18.145Z"
},
{
"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" : 0,
"idigbio:etag" : "0357f74dada8b21a69281b042a52f47a172fa33b",
"idigbio:dateModified" : "2014-01-20T20:19:29.754Z"
}
],
"idigbio:itemCount" : "2199334"
}
To Do: Provide examples of displaying multiple images accessed via the mediarecord API endpoint.
[broken at this time due to point to symbiota4 in url... check back later, might get fixed]
https://api.idigbio.org/v1/records/4e98d066-f35f-4cc0-ad7c-b5b5f2175521/media?quality=thumbnail
https://api.idigbio.org/v1/mediarecords/4c4c5008-5444-4348-85f5-34112b46169b/media?quality=webview
Curculionidae Image Example
Let us say we have already located the specimen record for a particular Curculionidae specimen (a family of weevils). The speciment record for our particular example is identified by the following iDigBio GUID:
"idigbio:uuid" : "354210ae-4aa3-49d2-8a66-78a86b019c7b"
To retrieve a specimen record from v1 of the API with the above iDigBio GUID, we issue a GET HTTP request to the following endpoint:
http://api.idigbio.org/v1/records/354210ae-4aa3-49d2-8a66-78a86b019c7b
and receive the following JSON document from the API (in this case, formatted for readability):
{
"idigbio:uuid" : "354210ae-4aa3-49d2-8a66-78a86b019c7b",
"idigbio:etag" : "02736fd7318eafed62a4a5ff35175a27fa63983e",
"idigbio:links" : {
"mediarecord" : [
"http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101"
],
"owner" : [
"872733a2-67a3-4c54-aa76-862735a5f334"
],
"recordset" : [
"http://api.idigbio.org/v1/recordsets/69037495-438d-4dba-bf0f-4878073766f1"
]
},
"idigbio:version" : 2,
"idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
"idigbio:recordIds" : [
"urn:uuid:b036a012-ba1e-41e0-a39a-76fc253640cf"
],
"idigbio:dateModified" : "2014-04-22T07:33:16.129Z",
"idigbio:data" : {
"dwc:day" : "16",
"dwc:identifiedBy" : "CPMAB",
"idigbio:recordId" : "urn:uuid:b036a012-ba1e-41e0-a39a-76fc253640cf",
"dwc:catalogNumber" : "NAUF4A0013309",
"dwc:locality" : "Box Cyn. Santa Rita Mts.",
"dwc:occurrenceID" : "1063507",
"dwc:year" : "1967",
"dwc:recordedBy" : "C.D. Johnson",
"dwc:scientificName" : "Curculionidae",
"dwc:basisOfRecord" : "PreservedSpecimen",
"dwc:family" : "Curculionidae",
"symbiotaverbatimScientificName" : "Curculionidae",
"dwc:collectionCode" : "NAUF",
"dcterms:modified" : "2013-12-20 13:00:36",
"dwc:country" : "USA",
"dcterms:references" : "http://symbiota4.acis.ufl.edu/scan/portal/collections/individual/index.php?occid=1063507",
"dwc:eventDate" : "1967-08-16",
"dwc:scientificNameAuthorship" : "Latreille, 1802",
"dwc:collectionID" : "urn:uuid:c87a0756-fdd7-4cb6-9921-ca5774f8330e",
"dwc:minimumElevationInMeters" : "1524",
"dwc:verbatimElevation" : "5000'",
"dwc:startDayOfYear" : "228",
"dwc:month" : "8",
"dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"dwc:stateProvince" : "Arizona",
"dwc:genus" : "Curculionidae",
"dwc:institutionCode" : "NAU",
"dwc:county" : "Pima"
}
}
This specimen record contains a link to a media record:
http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101
We can then display the image as a thumbnail by using the "media" endpoint and adding the "quality" parameter.
http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101/media?quality=webview
which when visited in a browser will lead (via one or more HTTP redirects) to an image. Note that the final image URL should not be considered permanent as image locations can change over time (but the mediarecord ID will remain the same).
Advanced Elasticsearch Examples
- 1. Find all specimen records that meet the following criteia
- Has an image (mediarecord) associated with the specimen record
- Is from Hocking County, Ohio or Fairfield County, Ohio.
Note that we are not using georeference data here, we are using the "county" and "stateprovince" fields.
To resolve this criteria, we need the following (expressed in pseudocode):
- "hasImage" is true
- "county" is either "Hocking" or "Fairfield"
- "stateprovince" is equal to "Ohio" (there are multiple Fairfield counties throughout the world so we need to restrict the geography by state)
The essential query parameter string will look something like this:
?q=hasImage:true+AND+county:(fairfield+OR+hocking)+AND+stateprovince:ohio
In addition, it is possible to request more or fewer records at a time using the "from" and "size" parameters. Below is the full curl example requesting only the first 3 records and grep'ing out only the iDigBio GUID field. Note that we put the URL in quotes to keep the shell from trying to interpret it.
$ curl -s "http://search.idigbio.org/idigbio/records/_search?from=0&size=3&q=hasImage:true+AND+county:(fairfield+OR+hocking)+AND+stateprovince:ohio" | json_pp | egrep "\"uuid\""
"uuid" : "20ad60a8-4126-4cc0-9378-411a9a640005",
"uuid" : "ecf14f53-d225-4eb5-89e6-66379b360781",
"uuid" : "ff69483e-ab19-4fa7-9ca3-d99089280af6",
- 2. Search for scientific name
# HERE GOES THE EXAMPLE
Mapping Example
- coming soon
API Performance
For large numbers of records or bulk data aquisition, please use the Download features available in the Portal. https://www.idigbio.org/portal
See also iDigBio API Performance.