IDigBio API v1 Examples

From iDigBio
Revision as of 13:57, 23 May 2014 by Dstoner (Talk | contribs)

Jump to: navigation, search


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

A complete record that was provided to iDigBio is stored in the API and can be retrieved by referencing the iDigBio UUID ("idigbio:uuid") at the appropriate endpoint.

We issue an HTTP "GET" request to the /v1/records/{UUID} endpoint with curl:

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

Note that under normal circumstances if one has the iDigBio UUID then there is no reason to use Elasticsearch; the full record is available at the API endpoint.

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 gives 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 may be sourced from 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 Record

Consider an iDigBio Media Record that is identified by:

"idigbio:uuid" : "ff5fd841-6bc6-4241-80d3-def7e1b6d5e8"

This record has been updated over time so there are multiple revisions of the record preserved in the API. We can find that the most recent (e.g. "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 the "version" 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 single entity record (as opposed to a List).

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.

Fetch a list of five MediaRecord IDs

The "mediarecords" endpoint returns a 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

Display a thumbnail image for a specimen record

Let's say that we wish to display a thumbnail image for a particular specimen record.

We can look at the full record:

$ curl -s "http://api.idigbio.org/v1/records/182c9260-0151-454a-a648-4d58ddf51bd8" | json_pp
{
   "idigbio:uuid" : "182c9260-0151-454a-a648-4d58ddf51bd8",
   "idigbio:etag" : "bb5ee46e2730948c946c178e8da85dedee4bea80",
   "idigbio:links" : {
      "mediarecord" : [
         "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca"
      ],
      "owner" : [
         "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "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:7d0d4400-7c6c-4bb4-b2ad-7b1f6e776755"
   ],
   "idigbio:dateModified" : "2014-05-03T14:27:40.596Z",
   "idigbio:data" : {
      "idigbio:recordId" : "urn:uuid:7d0d4400-7c6c-4bb4-b2ad-7b1f6e776755",
      "dwc:catalogNumber" : "CBS.038533",
      "dwc:specificEpithet" : "novae-angliae",
      "dwc:occurrenceID" : "272024",
      "dwc:year" : "0",
      "dwc:recordedBy" : "Hugh S. Clark",
      "dwc:scientificName" : "Symphyotrichum novae-angliae",
      "dwc:basisOfRecord" : "PreservedSpecimen",
      "dwc:family" : "Asteraceae",
      "symbiotaverbatimScientificName" : "Symphyotrichum novae-angliae",
      "dwc:collectionCode" : "CBS",
      "dcterms:modified" : "2012-03-14 00:00:00",
      "dwc:decimalLongitude" : "-72.6834",
      "dwc:country" : "USA",
      "dcterms:references" : "http://portal.neherbaria.org/portal/collections/individual/index.php?occid=272024",
      "dwc:municipality" : "Hartford",
      "dwc:scientificNameAuthorship" : "(L.) G.L. Nesom",
      "dwc:month" : "0",
      "dwc:rights" : "http://hdl.handle.net/10079/8931zqj",
      "dwc:geodeticDatum" : "WGS84",
      "dwc:rightsHolder" : "Peabody Museum of Natural History, Yale University",
      "dwc:stateProvince" : "Connecticut",
      "dwc:genus" : "Symphyotrichum",
      "dwc:coordinateUncertaintyInMeters" : "5419",
      "dwc:decimalLatitude" : "41.766",
      "dwc:accessRights" : "http://hdl.handle.net/10079/8931zqj",
      "dwc:institutionCode" : "YPM",
      "dwc:county" : "Hartford County"
   }
}

At this point we have a couple of options to get to the thumbnail. The easiest is to use the /media endpoint for this record's iDigBio UUID and add the "quality" parameter with "thumbnail" as the value:

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

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

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

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


The /media endpoint of a specimen record is kind of shortcut to avoid having to walk through the relationship to a mediarecord and then to an image file.

Alternatively, if we actually wanted to look at media metadata, we could use the link to the mediarecord in the "idigbio:links" section:

   "idigbio:links" : {
      "mediarecord" : [
         "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca"
      ],

which also has a /media endpoint that can lead to the same thumbnail image.

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

Advanced Elasticsearch Examples

Search using Locality Data

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.


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

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

Mapping Example

This Mapping example is really just another Elasticsearch example. To generate a map, we basically want to do an Elasticsearch query to choose our specimens of interest and then put the points for those specimens on a map.

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>

Deeper integration of iDigBio mapping requires understanding of geohashes and would be a more significant undertaking. If your project wishes advanced integration, please contact iDigBio. https://www.idigbio.org/contact

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.