IDigBio API v1 Examples: Difference between revisions

Jump to navigation Jump to search

IDigBio API v1 Examples (view source)

Revision as of 18:09, 9 July 2018

5,921 bytes added ,  9 July 2018
no edit summary
No edit summary
 
(32 intermediate revisions by 2 users not shown)
Line 2: Line 2:
[[Category:API]]
[[Category:API]]
[[Category:Documentation]]
[[Category:Documentation]]
{{Caution|The v1 API has been superseded by [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API]. API users should migrate to using the most recent version of the API. This page remains for historical reference.}}


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.
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.
Line 124: Line 126:
=== Three ways to fetch a specific record based on iDigBio UUID ===
=== 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 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.
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.
Line 138: Line 140:
==== Use the API ====
==== 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.
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.
 
Let us say that we have already located the specimen record for a particular Curculionidae specimen (a family of weevils). The specimen record for our particular example is identified by the following iDigBio GUID:
 
<code>
"idigbio:uuid" : "354210ae-4aa3-49d2-8a66-78a86b019c7b"
</code>
 
To retrieve a specimen record from v1 of the API with the above iDigBio UUID, we issue an HTTP "GET" request to the /v1/records/{UUID} endpoint with curl:
 
<code>
http://api.idigbio.org/v1/records/354210ae-4aa3-49d2-8a66-78a86b019c7b
</code>


The following command sends the query as an HTTP <code> GET </code> request:
and receive the following JSON document from the API (in this case, formatted for readability):


<pre>
<pre>
$ curl -s https://api.idigbio.org/v1/records/0cec43d8-9ad5-478a-bea1-397ab5cc4430 | json_pp
{
{
   "idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
   "idigbio:uuid" : "354210ae-4aa3-49d2-8a66-78a86b019c7b",
   "idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
   "idigbio:etag" : "02736fd7318eafed62a4a5ff35175a27fa63983e",
   "idigbio:links" : {
   "idigbio:links" : {
       "mediarecord" : [
       "mediarecord" : [
         "http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
         "http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101"
       ],
       ],
       "owner" : [
       "owner" : [
Line 155: Line 168:
       ],
       ],
       "recordset" : [
       "recordset" : [
         "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
         "http://api.idigbio.org/v1/recordsets/69037495-438d-4dba-bf0f-4878073766f1"
       ]
       ]
   },
   },
   "idigbio:version" : 1,
   "idigbio:version" : 2,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
   "idigbio:recordIds" : [
       "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
       "urn:uuid:b036a012-ba1e-41e0-a39a-76fc253640cf"
   ],
   ],
   "idigbio:dateModified" : "2014-04-20T23:11:09.437Z",
   "idigbio:dateModified" : "2014-04-22T07:33:16.129Z",
   "idigbio:data" : {
   "idigbio:data" : {
       "dwc:catalogNumber" : "ASU0000166",
      "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:basisOfRecord" : "PreservedSpecimen",
       "symbiotaverbatimScientificName" : "Abies",
      "dwc:family" : "Curculionidae",
       "dwc:collectionCode" : "Plants",
       "symbiotaverbatimScientificName" : "Curculionidae",
       "dwc:decimalLongitude" : "-105.859665870667",
       "dwc:collectionCode" : "NAUF",
       "dcterms:references" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=784316",
      "dcterms:modified" : "2013-12-20 13:00:36",
       "dwc:scientificNameAuthorship" : "P. Mill.",
       "dwc:country" : "USA",
       "dwc:collectionID" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
       "dcterms:references" : "http://symbiota4.acis.ufl.edu/scan/portal/collections/individual/index.php?occid=1063507",
       "dwc:minimumElevationInMeters" : "2316",
      "dwc:eventDate" : "1967-08-16",
       "dwc:georeferenceSources" : "georef batch tool 2013-05-10",
       "dwc:scientificNameAuthorship" : "Latreille, 1802",
       "dwc:georeferenceVerificationStatus" : "reviewed - high confidence",
       "dwc:collectionID" : "urn:uuid:c87a0756-fdd7-4cb6-9921-ca5774f8330e",
      "dwc:occurrenceRemarks" : "Tree to 4 m;  occasional in N-facing barranca",
       "dwc:minimumElevationInMeters" : "1524",
       "dwc:otherCatalogNumbers" : "153418",
       "dwc:verbatimElevation" : "5000'",
       "dwc:startDayOfYear" : "228",
       "dwc:month" : "8",
       "dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
       "dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
      "dwc:decimalLatitude" : "23.5821004818154",
       "dwc:stateProvince" : "Arizona",
      "dwc:day" : "14",
       "dwc:genus" : "Curculionidae",
      "idigbio:recordId" : "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a",
       "dwc:institutionCode" : "NAU",
      "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:county" : "Pima"
      "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"
   }
   }
}
}
Line 209: Line 213:


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 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]].
The list of available terms in the iDigBio index is available at [[IDigBio_API#Elasticsearch_-_Records]].
Line 214: Line 220:
===== Use the Elasticsearch URI Search =====
===== Use the Elasticsearch URI Search =====


The following command sends the query as an HTTP <code> GET </code> request:
The following command sends the query as an HTTP "GET" request:


<pre>
<pre>
Line 362: Line 368:
A JSON query document can be specified on the command-line. Again we are searching for the iDigBio UUID in the "uuid" term.
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 <code> POST </code> request:
The following command sends the query as an HTTP "POST" request:


<pre>
<pre>
Line 374: Line 380:
</pre>
</pre>


and give the following result:
and gives the following result:


<pre>
<pre>
Line 517: Line 523:
</pre>
</pre>


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


<pre>
<pre>
Line 675: Line 681:
</pre>
</pre>


=== Fetch an Older Version of a Particular Media Record ===
=== Fetch an Older Version of a Particular 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.
Consider an iDigBio Media Record that is identified by:
 
<pre>
"idigbio:uuid" : "ff5fd841-6bc6-4241-80d3-def7e1b6d5e8"
</pre>
 
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:


<pre>
<pre>
Line 684: Line 696:
</pre>
</pre>


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 <code>?version=0</code> as a parameter to the URL.
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:


<pre>
<pre>
Line 691: Line 703:
</pre>
</pre>


The "version" parameter is available for any endpoint that returns a full entity record.
The "version" parameter is available for any most of the endpoints that return a single entity record (as opposed to a List).
 
=== 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:
 
<pre>
$ 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"
}
</pre>
 
 
Screenshot of Results:
 
[[File:Screenshot_jsonview_idigbio_api_mediarecords_limit_offset.png]]


=== Paging through the API ===
=== Paging through the API ===
Line 915: Line 852:
;TO DO One more paging to help differentiate these multiples of 5.
;TO DO One more paging to help differentiate these multiples of 5.


=== Display a thumbnail image for a mediarecord ===
=== Fetch a list of five MediaRecord IDs ===


Let's say we wish to display a thumbnail image for the 3rd mediarecord of the previous example (highlighted in the previous screenshot).
The "mediarecords" endpoint returns a List of Media Record IDs.


Not necessary, but we can look at the full mediarecord:
Example URL:
 
http://api.idigbio.org/v1/mediarecords?limit=5&offset=5
 
 
Example Results:


<pre>
<pre>
$ curl -s "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca" | json_pp  
$ curl -s "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5" | json_pp
{
{
   "idigbio:uuid" : "00002091-4fb3-410a-9307-bd3e917dfcca",
   "idigbio:errors" : [],
  "idigbio:etag" : "90d98d48d9e7e07eab9064bd9b6e22ce6502c07f",
   "idigbio:links" : {
   "idigbio:links" : {
       "owner" : [
       "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=10",
        "872733a2-67a3-4c54-aa76-862735a5f334"
       "idigbio:prevPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=0"
      ],
      "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:items" : [
  "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
      {
  "idigbio:recordIds" : [
        "idigbio:links" : {
       "urn:uuid:2b6faee7-9f1d-47f3-97b2-fdcfd522ea9b"
            "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:dateModified" : "2014-05-03T14:45:47.112Z",
   "idigbio:itemCount" : "2342880"
  "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"
  }
}
}
</pre>
</pre>




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


http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca/media?quality=thumbnail
[[File:Screenshot_jsonview_idigbio_api_mediarecords_limit_offset.png]]
 
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 Image Example ===
 
Let us say we have already located the specimen record for a particular Curculionidae specimen (a family of weevils). The speciment record for our particular example is identified by the following iDigBio UUID:
 
<code>
"idigbio:uuid" : "354210ae-4aa3-49d2-8a66-78a86b019c7b"
</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:
=== Display a thumbnail image for a specimen record ===


<code>
Let's say that we wish to display a thumbnail image for a particular specimen record.
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):
We can look at the full record:


<pre>
<pre>
$ curl -s "http://api.idigbio.org/v1/records/182c9260-0151-454a-a648-4d58ddf51bd8" | json_pp
{
{
   "idigbio:uuid" : "354210ae-4aa3-49d2-8a66-78a86b019c7b",
   "idigbio:uuid" : "182c9260-0151-454a-a648-4d58ddf51bd8",
   "idigbio:etag" : "02736fd7318eafed62a4a5ff35175a27fa63983e",
   "idigbio:etag" : "bb5ee46e2730948c946c178e8da85dedee4bea80",
   "idigbio:links" : {
   "idigbio:links" : {
       "mediarecord" : [
       "mediarecord" : [
         "http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101"
         "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca"
       ],
       ],
       "owner" : [
       "owner" : [
Line 999: Line 946:
       ],
       ],
       "recordset" : [
       "recordset" : [
         "http://api.idigbio.org/v1/recordsets/69037495-438d-4dba-bf0f-4878073766f1"
         "http://api.idigbio.org/v1/recordsets/09edf7d2-e68e-4a42-93da-762f86bb814f"
       ]
       ]
   },
   },
   "idigbio:version" : 2,
   "idigbio:version" : 0,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
   "idigbio:recordIds" : [
       "urn:uuid:b036a012-ba1e-41e0-a39a-76fc253640cf"
       "urn:uuid:7d0d4400-7c6c-4bb4-b2ad-7b1f6e776755"
   ],
   ],
   "idigbio:dateModified" : "2014-04-22T07:33:16.129Z",
   "idigbio:dateModified" : "2014-05-03T14:27:40.596Z",
   "idigbio:data" : {
   "idigbio:data" : {
      "dwc:day" : "16",
       "idigbio:recordId" : "urn:uuid:7d0d4400-7c6c-4bb4-b2ad-7b1f6e776755",
      "dwc:identifiedBy" : "CPMAB",
       "dwc:catalogNumber" : "CBS.038533",
       "idigbio:recordId" : "urn:uuid:b036a012-ba1e-41e0-a39a-76fc253640cf",
       "dwc:specificEpithet" : "novae-angliae",
       "dwc:catalogNumber" : "NAUF4A0013309",
       "dwc:occurrenceID" : "272024",
       "dwc:locality" : "Box Cyn. Santa Rita Mts.",
       "dwc:year" : "0",
       "dwc:occurrenceID" : "1063507",
       "dwc:recordedBy" : "Hugh S. Clark",
       "dwc:year" : "1967",
       "dwc:scientificName" : "Symphyotrichum novae-angliae",
       "dwc:recordedBy" : "C.D. Johnson",
       "dwc:scientificName" : "Curculionidae",
       "dwc:basisOfRecord" : "PreservedSpecimen",
       "dwc:basisOfRecord" : "PreservedSpecimen",
       "dwc:family" : "Curculionidae",
       "dwc:family" : "Asteraceae",
       "symbiotaverbatimScientificName" : "Curculionidae",
       "symbiotaverbatimScientificName" : "Symphyotrichum novae-angliae",
       "dwc:collectionCode" : "NAUF",
       "dwc:collectionCode" : "CBS",
       "dcterms:modified" : "2013-12-20 13:00:36",
       "dcterms:modified" : "2012-03-14 00:00:00",
      "dwc:decimalLongitude" : "-72.6834",
       "dwc:country" : "USA",
       "dwc:country" : "USA",
       "dcterms:references" : "http://symbiota4.acis.ufl.edu/scan/portal/collections/individual/index.php?occid=1063507",
       "dcterms:references" : "http://portal.neherbaria.org/portal/collections/individual/index.php?occid=272024",
       "dwc:eventDate" : "1967-08-16",
       "dwc:municipality" : "Hartford",
       "dwc:scientificNameAuthorship" : "Latreille, 1802",
       "dwc:scientificNameAuthorship" : "(L.) G.L. Nesom",
       "dwc:collectionID" : "urn:uuid:c87a0756-fdd7-4cb6-9921-ca5774f8330e",
      "dwc:month" : "0",
       "dwc:minimumElevationInMeters" : "1524",
       "dwc:rights" : "http://hdl.handle.net/10079/8931zqj",
       "dwc:verbatimElevation" : "5000'",
       "dwc:geodeticDatum" : "WGS84",
       "dwc:startDayOfYear" : "228",
       "dwc:rightsHolder" : "Peabody Museum of Natural History, Yale University",
       "dwc:month" : "8",
       "dwc:stateProvince" : "Connecticut",
       "dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
       "dwc:genus" : "Symphyotrichum",
       "dwc:stateProvince" : "Arizona",
       "dwc:coordinateUncertaintyInMeters" : "5419",
       "dwc:genus" : "Curculionidae",
       "dwc:decimalLatitude" : "41.766",
       "dwc:institutionCode" : "NAU",
       "dwc:accessRights" : "http://hdl.handle.net/10079/8931zqj",
       "dwc:county" : "Pima"
       "dwc:institutionCode" : "YPM",
       "dwc:county" : "Hartford County"
   }
   }
}
}
</pre>
</pre>


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:


This specimen record contains a link to a media record:
http://api.idigbio.org/v1/records/182c9260-0151-454a-a648-4d58ddf51bd8/media?quality=thumbnail


<code>
which results in a number of HTTP Redirects to the target thumbnail image, illustrated here with the Chrome Developer Tools visible:
http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101
 
</code>
[[File: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.


We can then display the image as a thumbnail by using the "media" endpoint and adding the "quality" parameter.
Alternatively, if we actually wanted to look at media metadata, we could use the link to the mediarecord in the <code>"idigbio:links"</code> section:


<code>
<pre>
http://api.idigbio.org/v1/mediarecords/59141135-813a-4db1-a527-009ae6d17101/media?quality=webview
  "idigbio:links" : {
</code>
      "mediarecord" : [
        "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca"
      ],
</pre>


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).
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 ===
=== Advanced Elasticsearch Examples ===
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''}}
==== Search using Locality Data ====


The [[IDigBio API v1 Specification#Search|iDigBio Elasticsearch]] documentation should be considered required reading for these advanced Elasticsearch examples.
The [[IDigBio API v1 Specification#Search|iDigBio Elasticsearch]] documentation should be considered required reading for these advanced Elasticsearch examples.
Line 1,097: Line 1,058:
...
...


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.
Note that we did not specify any sorting in the Elasticsearch query and we did restrict the result count by using the "size" parameter. If the same query is run at a later time the specific records returned could be different.
 
Note also that the above query is for an exact match on the county name which will perform fairly well. Unfortunately, the data includes many variations in the county field for these counties such as:
 
<pre>
"Fairfield"
"Fairfield County"
"Hocking"
"Hocking Co."
"Hocking County"
"Hocking Hills"
</pre>
 
To find these related records, a wildcard query may be useful.  In the following case the size is also increased to 3000 to retrieve a larger sample.
 
<pre>
$ curl -s 'http://search.idigbio.org/idigbio/records/_search?from=0&size=3000&q=hasImage:true+AND+county:(fairfield*+OR+hocking*)+AND+stateprovince:ohio' | json_pp
</pre>
 
==== Family: Curculionidae - Search Example ====
 
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''}}


; 2. We plan to continue adding examples to this page...
Let us say we are looking for images associated with specimen records for Family Curculionidae (a family of weevils).  
 
If we already know the iDigBio UUID of a specimen we can simply use the <code>/media</code> endpoint for the record:
 
<code>
http://api.idigbio.org/v1/records/c2e34bda-0405-48ea-b7b2-76f893777f20/media?quality=webview
</code>
 
Giving us an image from the iDigBio API that looks something like this:
 
[[File:Curculionidae_example_Acallodes_ventricosus.jpg]]
 
 
But how did we find the proper iDigBio UUID for this specimen record in the first place?
 
The [https://www.idigbio.org/portal/search iDigBio Portal Search] is of course built just for this purpose.
 
If on the other hand we wanted to search for these specimens via a software program, we could use the iDigBio Elasticsearch interface.
 
I happen to know that this specimen was collected in New Jersey, so we search for records of Family Curculionidae in New Jersey that have associated images. Note the special encoding of the query string (space becomes %20, quotation becomes %22) required when using curl vs. a browser (the browser would do this encoding for you).
 
'''''The following example may not be correct yet...'''''
<pre>$ curl -s 'http://search.idigbio.org/idigbio/records/_search?q=hasImage:true+AND+family:curculionidae+AND+stateprovince:%22new%20jersey%22'</pre>


=== Mapping Example ===
=== Mapping Example ===
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''}}
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 API v1 Specification#Search|iDigBio Elasticsearch]] documentation should be considered required reading before attempting to integrate this code into one's site.
The [[IDigBio API v1 Specification#Search|iDigBio Elasticsearch]] documentation should be considered required reading before attempting to integrate this code into one's site.
Line 1,130: Line 1,138:
             * This example provided by iDigBio.    www.idigbio.org
             * This example provided by iDigBio.    www.idigbio.org
             *
             *
             * Terms that can be used by requesting site:
             * The list of available terms is available at
             * uuid, scientificname, institutioncode, collectioncode, kingdom, phylum, class, order, family, genus,
            * https://www.idigbio.org/wiki/index.php/IDigBio_API_v1_Specification#Search
             * specificepithet, infraspecificepithet, highertaxon, continent, country, stateprovince, county,
            *
            * municipality, waterbody, locality, verbatimlocality, geopoint, minelevation, maxelevation, mindepth,
            * Some Example Terms:
            * maxdepth, datecollected, institutionname, institutionid, collectionname, collectionid, occurenceid,  
             * uuid, scientificname, institutioncode, collectioncode, genus,
            * barcodevalue,catalognumber, fieldnumber, typestatus, collector
             * country, stateprovince, county, occurenceid, barcodevalue, catalognumber
             *****/
             *****/
             var terms = [
             var terms = [
Line 1,201: Line 1,209:
     </body>
     </body>
</html>
</html>
</pre>
The above html page would render as follows (captured in a screenshot) in a browser:
[[File:Idigbio_api_mapping_search_example.png]]
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
=== idigbio:links and the 20 Item List ===
Compare the idigbio:links section of the following two Publisher records:
http://api.idigbio.org/v1/publishers/076c0ff6-65e9-48a5-8e4b-2447936f9a1c
http://api.idigbio.org/v1/publishers/4e1beef9-d7c0-4ac0-87df-065bc5a55361
The first Publisher record returns a JSON document containing "idigbio:links" and a List of recordsets (or to be more precise, a List of API urls that can be used to access individual Recordset records by iDigBio UUID). Since the number of recordsets is less than 20, they are included in the Publisher record output.
<pre>
$ curl -s http://api.idigbio.org/v1/publishers/076c0ff6-65e9-48a5-8e4b-2447936f9a1c | json_pp
{
  "idigbio:uuid" : "076c0ff6-65e9-48a5-8e4b-2447936f9a1c",
  "idigbio:etag" : "31b115d5a307027f757554441c93d8e5b8ac8fab",
  "idigbio:links" : {
      "recordset" : [
        "http://api.idigbio.org/v1/recordsets/197f7bb8-213d-4fae-b536-652dd91e56dc",
        "http://api.idigbio.org/v1/recordsets/31c140bc-e6f1-4acc-beaf-b825cf288ad9",
        "http://api.idigbio.org/v1/recordsets/5aac25d2-bcfb-4084-a700-584311ea539d",
        "http://api.idigbio.org/v1/recordsets/5e893602-84ca-4c8c-bac1-99111c777582",
        "http://api.idigbio.org/v1/recordsets/6539877e-82dc-485c-ad3d-038f383d5431",
        "http://api.idigbio.org/v1/recordsets/69037495-438d-4dba-bf0f-4878073766f1",
        "http://api.idigbio.org/v1/recordsets/7fcdca8e-7469-480c-8516-cce4e24c37c9",
        "http://api.idigbio.org/v1/recordsets/82541f90-fe8e-4d66-84d8-4fe515dc5533",
        "http://api.idigbio.org/v1/recordsets/89eb1ad0-ae60-4e8a-bf34-a53d0423bc80",
        "http://api.idigbio.org/v1/recordsets/92dd8c8e-c048-4f0a-9b5d-2ee627d2f553",
        "http://api.idigbio.org/v1/recordsets/9ace4c05-d930-45c7-8d2d-0cadff1ea32b",
        "http://api.idigbio.org/v1/recordsets/9bd4ff72-1cb2-431f-bf7b-b5d47e08cc02",
        "http://api.idigbio.org/v1/recordsets/a3b77120-3770-46dd-ba47-6941eff848b3",
        "http://api.idigbio.org/v1/recordsets/ab4b6a2b-a90a-44ce-95a1-2c44c911fcc6",
        "http://api.idigbio.org/v1/recordsets/cb65cf5e-07b8-4d53-a91a-7dce9b8ccf80",
        "http://api.idigbio.org/v1/recordsets/d315c4a3-0bee-49d1-8d03-726358937cde",
        "http://api.idigbio.org/v1/recordsets/d767f759-af64-4464-8614-c77ca44cad8d",
        "http://api.idigbio.org/v1/recordsets/f83517ea-7b9f-443d-9371-d11a05ebc0a7",
        "http://api.idigbio.org/v1/recordsets/ff111763-e72d-4f24-8914-b5b2dd94908c"
      ]
  },
...
</pre>
The second link returns a JSON document containing "idigbio:links" and a single recordset link rather than a List.  To get to the List of recordsets for this Publisher record, this intermediate link needs to be followed.
<pre>
$ curl -s http://api.idigbio.org/v1/publishers/4e1beef9-d7c0-4ac0-87df-065bc5a55361 | json_pp
{
  "idigbio:uuid" : "4e1beef9-d7c0-4ac0-87df-065bc5a55361",
  "idigbio:etag" : "01c8eabbf9e8fe7f5af86349b04cad55b3ddee8e",
  "idigbio:links" : {
      "recordset" : [
        "http://api.idigbio.org/v1/publishers/4e1beef9-d7c0-4ac0-87df-065bc5a55361/recordsets"
      ]
  },
...
</pre>
As suspected, the list of Recordsets includes more than 20 items (in this case, 51 recordset items) which is why they were not displayed with the Publisher record.
<pre>
$ curl -s http://api.idigbio.org/v1/publishers/4e1beef9-d7c0-4ac0-87df-065bc5a55361/recordsets | json_pp | grep recordset | wc -l
51
$ curl -s http://api.idigbio.org/v1/publishers/4e1beef9-d7c0-4ac0-87df-065bc5a55361/recordsets | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {},
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/0072bf11-a354-4998-8730-c0cb4cfc9517"
        },
        "idigbio:uuid" : "0072bf11-a354-4998-8730-c0cb4cfc9517"
      },
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/00d9fcc1-c8e2-4ef6-be64-9994ca6a32c3"
        },
        "idigbio:uuid" : "00d9fcc1-c8e2-4ef6-be64-9994ca6a32c3"
      },
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/0dd7c8dd-412c-4a13-a1d3-47e1e1af5455"
        },
        "idigbio:uuid" : "0dd7c8dd-412c-4a13-a1d3-47e1e1af5455"
      },
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/181352ea-3598-4f32-b919-c8f6097f4c65"
        },
        "idigbio:uuid" : "181352ea-3598-4f32-b919-c8f6097f4c65"
      },
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/196bb137-2f82-40d5-b294-e730af29749f"
        },
        "idigbio:uuid" : "196bb137-2f82-40d5-b294-e730af29749f"
      },
...
</pre>
</pre>


Mcollins
82

edits

Retrieved from "http://www.idigbio.org/wiki/index.php/Special:MobileDiff/10116...27653"

Navigation menu