IDigBio API v1 Examples
Jump to navigation
Jump to search
This document is a list of examples for using the iDigBio API but may not be comprehensive. See IDigBio API for full documentation on the API including all of the available endpoints and parameters.
Viewing JSON Output
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 GET method (curl's default) against the base URL:
$ curl -s -i http://api.idigbio.org/
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 108
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: airVCXBxEpZm/Wl/DU6tXw==
Date: Fri, 09 May 2014 19:34:26 GMT
Server: restify
Request-Id: ee775220-d7b0-11e3-8828-37453f55c1c8
Response-Time: 2
{"v1":"http://api.idigbio.org/v1/","v0":"http://api.idigbio.org/v0/","check":"http://api.idigbio.org/check"}
It may be useful to format the output of the JSON document 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 or the json_pp command-line Perl script (JSON::PP). These tools can receive input from a pipe in the normal Unix fashion to chain multiple commands together.
json.tool
$ 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
$ 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/"
}
For best viewing of JSON results in a browser, one may wish to use the JSONView Extension for Chrome and Firefox.
JSONView Browser Extension
simplejson
Some older systems may not include json_pp or python's json.tool. The python simplejson package may solve this problem. 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 also to provide a brief introduction to the URL syntax of the APIs.
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.
$ 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"
}
}
Use the Elasticsearch URL interface with query parameter
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.
The record 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.
$ 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 URL interface with json-formatted filter query in the message body
A JSON query document can be specified on the command-line. Searching for the iDigBio GUID in the "uuid" term would look like the following:
$ curl -s https://search.idigbio.org/idigbio/records/_search -d'
{
"filter" : {
"term" : { "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" : 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" }
}
}
is this correct?
To convince curl to use the GET HTTP method instead of POST HTTP method when invoked with the -d option, we add the additional -X option and specify the GET method. We get the same results in the data fields as the previous search:
$ 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
More 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
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.