Difference between revisions of "IDigBio API v1 Examples"

From iDigBio
Jump to: navigation, search
(add links to images Advanced Elasticsearch Examples)
(changing to search example Curculionidae Image Example)
Line 971: Line 971:
 
''Note that the final image URL should not be considered stable or permanent. Images can be moved around to various storage platforms. The Mediarecord has a UUID that will remain contstant but the containing data, including the image location, may be updated over time.''
 
''Note that the final image URL should not be considered stable or permanent. Images can be moved around to various storage platforms. The Mediarecord has a UUID that will remain contstant but the containing data, including the image location, may be updated over time.''
  
=== Curculionidae Image Example ===
+
=== Curculionidae Search 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 UUID:
+
Let us say we are looking for an image of a particular Curculionidae specimen (a family of weevils).  
 +
 
 +
If we already know the iDigBio UUID of the specimen we can simply use the /media endpoint for the record:
  
 
<code>
 
<code>
"idigbio:uuid" : "354210ae-4aa3-49d2-8a66-78a86b019c7b"
+
http://api.idigbio.org/v1/records/354210ae-4aa3-49d2-8a66-78a86b019c7b/media?quality=webview</code>
 
</code>
 
</code>
  
To retrieve a specimen record from v1 of the API with the above iDigBio UUID, we issue a GET HTTP request to the following endpoint:
+
But how did we find the proper iDigBio UUID for this specimen record in the first place?
  
<code>
 
http://api.idigbio.org/v1/records/354210ae-4aa3-49d2-8a66-78a86b019c7b
 
</code>
 
  
 
and receive the following JSON document from the API (in this case, formatted for readability):
 
and receive the following JSON document from the API (in this case, formatted for readability):
Line 1,040: Line 1,039:
 
}
 
}
 
</pre>
 
</pre>
 
 
This specimen record contains a link to a media record:
 
 
<code>
 
http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101
 
</code>
 
 
We can then display the image as a thumbnail by using the "media" endpoint and adding the "quality" parameter.
 
 
<code>
 
http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101/media?quality=webview
 
</code>
 
 
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 ===
 
=== Advanced Elasticsearch Examples ===

Revision as of 11:19, 23 May 2014


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

Most of the examples provided here will be shown using the curl command-line tool. The dollar sign $ is an indication of a command prompt where something is typed into a shell or terminal. To run the commands, the $ should be omitted.

Here are some of the more commonly used curl options in our examples (for descriptions and additional usage information, see the curl man page):

$ man curl
...
       -s, --silent
       -v, --verbose
       -d, --data <data>
...

Many of the examples will also include "pipes" to chain multiple commands together. The Wikipedia article on Unix software pipelines may be a useful reference.

Javascript Object Notation (JSON) Quick Intro

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.

A simple JSON document with two fields and two data values would look something like this:

{
    "field1" : "value_a",
    "field2" : "value_b"
}

If we were storing data about John Smith, age 50, we might represent it as the following JSON document:

{
    "lastName" : "Smith",
    "firstName" : "John",
    "age" : "50"
}


A short JSON document is returned by the iDigBio API when calling the HTTP "GET" method (curl's default) against the base URL (http://api.idigbio.org):

{
   "v1" : "http://api.idigbio.org/v1/",
   "check" : "http://api.idigbio.org/check",
   "v0" : "http://api.idigbio.org/v0/"
}

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 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 API base URL:

JSONView extension allows easier viewing in a web browser

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.

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 UUID

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. Each record that is added to iDigBio is assigned a Globally Unique Identifier (GUID) of the UUID type.

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.

Regardless of whether the record's data is retrieved by using the API or by using Elasticsearch, the piece of information used to identify a record is the iDigBio UUID.

For these three examples, consider the specimen record identified by the following iDigBio UUID:

"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 UUID ("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 UUID ("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 UUID 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 UUID 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" that has been updated over time so there are 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. Version 0 of a record is considered the "original" version of a record. 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 | grep version
   "idigbio:version" : "0",

The "version" parameter is available for any endpoint that returns a full entity record.

Fetch a list of five MediaRecord IDs

The "mediarecords" endpoint returns collection (list) of Media Record IDs.

Example URL:

http://api.idigbio.org/v1/mediarecords?limit=5&offset=5


Example Results:

$ curl -s "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5" | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=10",
      "idigbio:prevPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=0"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00001478-c150-4faf-a617-439a838d4377"
         },
         "idigbio:uuid" : "00001478-c150-4faf-a617-439a838d4377",
         "idigbio:version" : 1,
         "idigbio:etag" : "30f602e4eb47ebb2ceb265f64217e3cf5664f517",
         "idigbio:dateModified" : "2014-03-21T23:09:39.752Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00001a91-189b-4002-b56e-a770a55951a0"
         },
         "idigbio:uuid" : "00001a91-189b-4002-b56e-a770a55951a0",
         "idigbio:version" : 0,
         "idigbio:etag" : "647e82d17ee435fb14f0f8607dabe88dfc3a1944",
         "idigbio:dateModified" : "2014-04-25T04:49:32.359Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca"
         },
         "idigbio:uuid" : "00002091-4fb3-410a-9307-bd3e917dfcca",
         "idigbio:version" : 0,
         "idigbio:etag" : "90d98d48d9e7e07eab9064bd9b6e22ce6502c07f",
         "idigbio:dateModified" : "2014-05-03T18:45:47.112Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002c32-ae3a-41ed-9bd9-f6c50d3e35fb"
         },
         "idigbio:uuid" : "00002c32-ae3a-41ed-9bd9-f6c50d3e35fb",
         "idigbio:version" : 3,
         "idigbio:etag" : "d1ded90d06e93876b1badd01222905add93e8806",
         "idigbio:dateModified" : "2014-04-19T00:25:59.471Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002dbd-6415-463b-8cae-38f548415ffa"
         },
         "idigbio:uuid" : "00002dbd-6415-463b-8cae-38f548415ffa",
         "idigbio:version" : 2,
         "idigbio:etag" : "4e298045b496146f5c51e331c9887fd7afde4deb",
         "idigbio:dateModified" : "2014-04-21T20:29:39.531Z"
      }
   ],
   "idigbio:itemCount" : "2342880"
}


Screenshot of Results:

Screenshot jsonview idigbio api mediarecords limit offset.png

Paging through the API

Endpoints that return a list of entities may have more total items than are able to be "fit" in a single request. For example, trying to fetch the list of all records in iDigBio will surely timeout in the browser before it is completed (and would put undue load on the server infrastructure).


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"
}


The next "page" of records can be requested by adding the "offset" paramenter.

A link that includes the offset to the next page is provided in the results:

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

Request the next "page" of entity ids by starting at offset 5.

$ curl -s "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5" | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=10",
      "idigbio:prevPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=0"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00001478-c150-4faf-a617-439a838d4377"
         },
         "idigbio:uuid" : "00001478-c150-4faf-a617-439a838d4377",
         "idigbio:version" : 1,
         "idigbio:etag" : "30f602e4eb47ebb2ceb265f64217e3cf5664f517",
         "idigbio:dateModified" : "2014-03-21T23:09:39.752Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00001a91-189b-4002-b56e-a770a55951a0"
         },
         "idigbio:uuid" : "00001a91-189b-4002-b56e-a770a55951a0",
         "idigbio:version" : 0,
         "idigbio:etag" : "647e82d17ee435fb14f0f8607dabe88dfc3a1944",
         "idigbio:dateModified" : "2014-04-25T04:49:32.359Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca"
         },
         "idigbio:uuid" : "00002091-4fb3-410a-9307-bd3e917dfcca",
         "idigbio:version" : 0,
         "idigbio:etag" : "90d98d48d9e7e07eab9064bd9b6e22ce6502c07f",
         "idigbio:dateModified" : "2014-05-03T18:45:47.112Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002c32-ae3a-41ed-9bd9-f6c50d3e35fb"
         },
         "idigbio:uuid" : "00002c32-ae3a-41ed-9bd9-f6c50d3e35fb",
         "idigbio:version" : 3,
         "idigbio:etag" : "d1ded90d06e93876b1badd01222905add93e8806",
         "idigbio:dateModified" : "2014-04-19T00:25:59.471Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002dbd-6415-463b-8cae-38f548415ffa"
         },
         "idigbio:uuid" : "00002dbd-6415-463b-8cae-38f548415ffa",
         "idigbio:version" : 2,
         "idigbio:etag" : "4e298045b496146f5c51e331c9887fd7afde4deb",
         "idigbio:dateModified" : "2014-04-21T20:29:39.531Z"
      }
   ],
   "idigbio:itemCount" : "2342880"
}

which includes links to the previous page and next page:

      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=10",
      "idigbio:prevPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=0"

With current results starting at offset 5 and a limit of 5, the previous page and a next page offsets are 0 and 10 respectively (offset +- limit).

TO DO One more paging to help differentiate these multiples of 5.

Display a thumbnail image for a mediarecord

Let's say we wish to display a thumbnail image for the 3rd mediarecord of the previous example (highlighted in the previous screenshot).

Not necessary, but we can look at the full mediarecord:

$ curl -s "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca" | json_pp 
{
   "idigbio:uuid" : "00002091-4fb3-410a-9307-bd3e917dfcca",
   "idigbio:etag" : "90d98d48d9e7e07eab9064bd9b6e22ce6502c07f",
   "idigbio:links" : {
      "owner" : [
         "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "record" : [
         "http://api.idigbio.org/v1/records/182c9260-0151-454a-a648-4d58ddf51bd8"
      ],
      "recordset" : [
         "http://api.idigbio.org/v1/recordsets/09edf7d2-e68e-4a42-93da-762f86bb814f"
      ]
   },
   "idigbio:version" : 0,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
      "urn:uuid:2b6faee7-9f1d-47f3-97b2-fdcfd522ea9b"
   ],
   "idigbio:dateModified" : "2014-05-03T14:45:47.112Z",
   "idigbio:data" : {
      "ac:accessURI" : "http://deliver.odai.yale.edu/content/repository/YPM/id/100973/format/3",
      "ac:metadataLanguage" : "en",
      "ac:subtype" : "Photograph",
      "dwc:occurrenceID" : "272024",
      "xmpRights:WebStatement" : "http://hdl.handle.net/10079/8931zqj",
      "dcterms:type" : "StillImage",
      "xmp:MetadataDate" : "2012-10-08 20:53:21",
      "xmpRights:UsageTerms" : "Yale Peabody Museum of Natural History",
      "xmpRights:Owner" : "Peabody Museum of Natural History, Yale University",
      "dcterms:rights" : "http://hdl.handle.net/10079/8931zqj",
      "ac:providerManagedID" : "urn:uuid:2b6faee7-9f1d-47f3-97b2-fdcfd522ea9b",
      "ac:associatedSpecimenReference" : "http://portal.neherbaria.org/portal/collections/individual/index.php?occid=272024"
   }
}


We will use the "media" endpoint for that mediarecord's iDigBio UUID and add the "quality" parameter with "thumbnail" as the value:

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

Accessing that URL results in a number of HTTP Redirects to the target thumbnail image, illustrated here with the Chrome Developer Tools visible:

File:Screenshot thumbnail 00002091-4fb3-410a-9307-bd3e917dfcca.png

Note that the final image URL should not be considered stable or permanent. Images can be moved around to various storage platforms. The Mediarecord has a UUID that will remain contstant but the containing data, including the image location, may be updated over time.

Curculionidae Search Example

Let us say we are looking for an image of a particular Curculionidae specimen (a family of weevils).

If we already know the iDigBio UUID of the specimen we can simply use the /media endpoint for the record:

http://api.idigbio.org/v1/records/354210ae-4aa3-49d2-8a66-78a86b019c7b/media?quality=webview </code>

But how did we find the proper iDigBio UUID for this specimen record in the first place?


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"
   }
}

Advanced Elasticsearch Examples

The iDigBio Elasticsearch documentation should be considered required reading for these advanced Elasticsearch examples.

1. Find all specimen records that meet the following criteria
  • 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):

  1. "hasImage" is true
  2. "county" is either "Hocking" or "Fairfield"
  3. "stateprovince" is "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 (note we must lowercase the values):

?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 using grep on the output to filter everything except the iDigBio UUID field. Note that we quote the full URL to keep the shell from trying to interpret the special characters.

$ 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" : "ecf14f53-d225-4eb5-89e6-66379b360781",
               "uuid" : "e45071cd-40eb-41e7-9105-0e35234025f5",
               "uuid" : "20ad60a8-4126-4cc0-9378-411a9a640005",

Now that we have iDigBio UUIDs, we could retrieve images for these specimens by iterating over the /media endpoints for each of those uuids in the API.

http://api.idigbio.org/v1/records/ecf14f53-d225-4eb5-89e6-66379b360781/media?quality=webview

http://api.idigbio.org/v1/records/e45071cd-40eb-41e7-9105-0e35234025f5/media?quality=webview

...

Note that we did not specify any sorting in the Elasticsearch query and restricted the result count using the "size" parameter. If the same query is run at a later time the specific records returned could be different.

2. We plan to continue adding examples to this page...

Mapping Example

The iDigBio Elasticsearch documentation should be considered required reading before attempting to integrate this code into one's site.

This example displays a map that includes specimen data points that match the criteria of Scientific Name (dwc:scientificName) is "Abietinella abietina" and Institution Code (dwc:institutionCode) is "DUKE".

The Elasticsearch terms for this query are:

scientificname" : "abietinella abietina"
institutioncode": "duke"

The following is a full HTML page with javascript code that displays a small specimen map containing iDigBio data points.

To customize the map search results, modify the var terms = [ ... section with the terms of your choice.

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>iDigBio Map</title>
        <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.css" />
        <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
        <script src="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.js"></script>
        <script type="text/javascript">
            /*
            * This example provided by iDigBio.     www.idigbio.org
            *
            * Terms that can be used by requesting site:
            * uuid, scientificname, institutioncode, collectioncode, kingdom, phylum, class, order, family, genus,
            * specificepithet, infraspecificepithet, highertaxon, continent, country, stateprovince, county, 
            * municipality, waterbody, locality, verbatimlocality, geopoint, minelevation, maxelevation, mindepth, 
            * maxdepth, datecollected, institutionname, institutionid, collectionname, collectionid, occurenceid, 
            * barcodevalue,catalognumber, fieldnumber, typestatus, collector
            *****/
            var terms = [
                {"term"  :  { "scientificname" : "abietinella abietina"}},
                {"term"  :  { "institutioncode": "duke"}}
            ];

            $(document).ready(function(){
                var query = {
                    "size": 10000,
                    "from": 0,
                    "query":{
                        "filtered":{
                            "filter":{
                                "and":[]
                            }
                        }
                    },
                    "sort":{
                        "scientificname":{"order":"asc"}
                    }
                };
                /*
                *Build query params and outlink
                ***/
                var link=[];
                $.each(terms,function(ind,item){
                    query.query.filtered.filter.and.push(item);
                    $.each(item.term,function(key,val){
                        link.push(key+'='+ val.toLowerCase());
                    });
                });
                var link_href = 'https://www.idigbio.org/portal/search?'+link.join('&');
                var link_string = '<br>Map point data provided by iDigBio. <a id="link" href="' + link_href + '">View on iDigBio</a>';
                var base = L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',{
                    attribution: 'Map data © OpenStreetMap contributors; ' + link_string,
                    minZoom: 0, 
                    maxZoom: 18,
                    reuseTiles: true
                });
                map = L.map('map',{
                    center: [0,0],
                    zoom: 0,
                    layers: [base],
                    scrollWheelZoom: true,
                    boxZoom: false
                });
                /*
                *Make request to iDigBio search server
                ***/
                $.post('https://search.idigbio.org/idigbio/records/_search', JSON.stringify(query),function(resp){
                    $(resp.hits.hits).each(function(ind,item){
                        var source = item._source;
                        if(typeof source.geopoint !== 'undefined'){
                            var c = new L.Circle([source.geopoint.lat,source.geopoint.lon],1,{color:'#E90A0A',opacity:1,fillopacity:1});
                            c.addTo(map);
                        }
                    });
                });
            });
        </script>
    </head>
    <body>
        <div id="map" style="height:250px;width:330px;"></div>
    </body>
</html>

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.