1,554
edits
IDigBio API v1 Examples: Difference between revisions
move Curculionidae Search Example, mapping add contact, other tweaks
(changing to search example →Curculionidae Image Example) |
(move Curculionidae Search Example, mapping add contact, other tweaks) |
||
| 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 Search Example === | === Advanced Elasticsearch Examples === | ||
==== Search using Locality Data ==== | |||
The [[IDigBio API v1 Specification#Search|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): | |||
# "hasImage" is true | |||
# "county" is either "Hocking" or "Fairfield" | |||
# "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): | |||
<pre> | |||
?q=hasImage:true+AND+county:(fairfield+OR+hocking)+AND+stateprovince:ohio | |||
</pre> | |||
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. | |||
<pre> | |||
$ 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", | |||
</pre> | |||
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). | Let us say we are looking for an image of a particular Curculionidae specimen (a family of weevils). | ||
| Line 1,040: | Line 1,085: | ||
</pre> | </pre> | ||
=== 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 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,185: | Line 1,190: | ||
</html> | </html> | ||
</pre> | </pre> | ||
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 === | === API Performance === | ||