IDigBio API v1 Examples: Difference between revisions

From iDigBio
Jump to navigation Jump to search
(add Elasticsearch uuid examples)
(change uuid to GUID, add some more notes)
Line 41: Line 41:




=== Three ways to fetch a specific record based on iDigBio UUID. ===
=== Three ways to fetch a specific record based on iDigBio GUID. ===


; 1. Use the API
; 1. Use the API


The most complete version of each record provided to iDigBio is stored in the API.
The complete record that was provided to iDigBio is stored in the API and can be retrieved by referencing the iDigBio GUID ("idigbio:uuid").


<pre>
<pre>
Line 113: Line 113:
; 2. Use the Elasticsearch URL interface with query parameter
; 2. Use the Elasticsearch URL interface with query parameter


The data provided by the Elasticsearch interface may differ slightly from the raw API record since the Elasticsearch data has been indexed for consumption by the portal.
The data provided by the Elasticsearch interface may differ from the raw API record since the Elasticsearch data has been normalized and indexed for consumption by the search portal.


<pre>
<pre>
Line 273: Line 273:
</pre>
</pre>


We get the same results in the data fields:
We get the same results in the data fields as the previous search:


<pre>
<pre>
Line 419: Line 419:
}
}
</pre>
</pre>


=== Fetch five MediaRecord IDs (endpoints) from the API ===
=== Fetch five MediaRecord IDs (endpoints) from the API ===

Revision as of 17:08, 8 May 2014

This document is a list of examples for using the iDigBio API but may not be comprehensive. See IDigBio API for full documentation on the API including all of the available endpoints.

Viewing JSON Output

A short JSON document is returned by the API when calling the GET method against the base URL: 

$ curl -s http://api.idigbio.org/
{"v1":"http://api.idigbio.org/v1/","v0":"http://api.idigbio.org/v0/","check":"http://api.idigbio.org/check"}

For best viewing of JSON results in a browser, one may wish to use the JSONView Extension for Chrome and Firefox.

JSONView Browser Extension Example

JSONView extension allows easier viewing in a web browser

If using a command-line tool (such as curl), you may wish to format the output of the JSON document using a "pretty printing" feature of some kind. This will make it more readable by humans and also allow it to be more easily filtered using tools such as grep.

This becomes easier to read when the output is piped through a formatter such as python's json.tool or the json_pp command-line Perl script (JSON::PP).

json.tool Example 

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

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


Three ways to fetch a specific record based on iDigBio GUID.

1. Use the API

The complete record that was provided to iDigBio is stored in the API and can be retrieved by referencing the iDigBio GUID ("idigbio:uuid"). 

$ curl -s -XGET 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"
   }
}
2. Use the Elasticsearch URL interface with query parameter

The data provided by the Elasticsearch interface may differ from the raw API record since the Elasticsearch data has been normalized and indexed for consumption by the search portal. 

$ curl -s -XGET 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",
               "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" : 14.695786,
            "_index" : "idigbio-1.0.0",
            "_id" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
            "_type" : "records"
         }
      ],
      "max_score" : 14.695786,
      "total" : 1
   },
   "timed_out" : false,
   "_shards" : {
      "failed" : 0,
      "successful" : 10,
      "total" : 10
   },
   "took" : 4
}
3. Use the Elasticsearch with json-formatted filter query in the message body

Given a json-formatted query body stored in a file named uuid.json: 

$ cat uuid.json
{
    "filter" : {
    "term"  :  { "uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430" }
    }
}

We get the same results in the data fields as the previous search: 

$ curl -s -XGET https://search.idigbio.org/idigbio/records/_search -d@uuid.json | json_pp
{
   "hits" : {
      "hits" : [
         {
            "_source" : {
               "collectioncode" : "plants",
               "datecollected" : "1985-03-14",
               "uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
               "geopoint_geohash_6" : "9shwph",
               "locality" : "ca. 1 mi n of hwy 40 between villa union and cd. durango, and ca. 5 mi w of durango state border.",
               "minelevation" : 231,
               "collectionid" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
               "datecollected_rejected" : false,
               "datemodified_rejected" : false,
               "geopoint_geohash_5" : "9shwp",
               "recordset" : "40250f4d-7aa6-4fcc-ac38-2868fa4846bd",
               "geopoint_rejected" : false,
               "hasImage" : true,
               "data" : {
                  "idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
                  "idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
                  "idigbio:links" : {
                     "mediarecord" : [
                        "http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
                     ],
                     "owner" : [
                        "872733a2-67a3-4c54-aa76-862735a5f334"
                     ],
                     "recordset" : [
                        "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
                     ]
                  },
                  "idigbio:version" : 1,
                  "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
                  "idigbio:recordIds" : [
                     "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
                  ],
                  "idigbio:data" : {
                     "dwc:catalogNumber" : "ASU0000166",
                     "dwc:basisOfRecord" : "PreservedSpecimen",
                     "symbiotaverbatimScientificName" : "Abies",
                     "idigbio:links" : {
                        "mediarecord" : [
                           "http://api.idigbio.org/v1/mediarecords/db38f86b-99f5-4dc4-b4a6-a045a9c35323"
                        ],
                        "owner" : [
                           "872733a2-67a3-4c54-aa76-862735a5f334"
                        ],
                        "recordset" : [
                           "http://api.idigbio.org/v1/recordsets/40250f4d-7aa6-4fcc-ac38-2868fa4846bd"
                        ]
                     },
                     "dwc:collectionCode" : "Plants",
                     "dwc:decimalLongitude" : "-105.859665870667",
                     "dcterms:references" : "http://swbiodiversity.org/seinet/collections/individual/index.php?occid=784316",
                     "dwc:scientificNameAuthorship" : "P. Mill.",
                     "dwc:collectionID" : "urn:uuid:a2e32c87-d320-4a01-bafd-a9182ae2e191",
                     "dwc:minimumElevationInMeters" : "2316",
                     "dwc:georeferenceSources" : "georef batch tool 2013-05-10",
                     "dwc:georeferenceVerificationStatus" : "reviewed - high confidence",
                     "dwc:occurrenceRemarks" : "Tree to 4 m;  occasional in N-facing barranca",
                     "dwc:otherCatalogNumbers" : "153418",
                     "dwc:rights" : "http://creativecommons.org/licenses/by-nc-sa/3.0/",
                     "idigbio:version" : 1,
                     "idigbio:recordIds" : [
                        "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a"
                     ],
                     "dwc:decimalLatitude" : "23.5821004818154",
                     "dwc:day" : "14",
                     "idigbio:recordId" : "urn:uuid:5f5e476f-ee39-41c9-8b25-c929f85a773a",
                     "dwc:locality" : "Ca. 1 mi N of Hwy 40 between Villa Union and Cd. Durango, and ca. 5 mi W of Durango state border.",
                     "dwc:occurrenceID" : "784316",
                     "idigbio:etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
                     "dwc:year" : "1985",
                     "dwc:recordedBy" : "T. F. Daniel; ",
                     "dwc:recordNumber" : "4031",
                     "dwc:georeferencedBy" : "cjsdavis",
                     "dwc:scientificName" : "Abies",
                     "dwc:family" : "Pinaceae",
                     "dcterms:modified" : "2013-05-10 13:39:12",
                     "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
                     "dwc:country" : "Mexico",
                     "idigbio:dateModified" : "2014-04-20T23:11:09.437Z",
                     "dwc:eventDate" : "1985-03-14",
                     "dwc:verbatimElevation" : "7600ft",
                     "idigbio:uuid" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
                     "dwc:startDayOfYear" : "73",
                     "dwc:habitat" : "Pine-oak forest, in N-facing barranca.",
                     "dwc:dynamicProperties" : "Tree to 4 m;  occasional in N-facing barranca",
                     "dwc:month" : "3",
                     "dwc:stateProvince" : "Sinaloa",
                     "dwc:genus" : "Abies",
                     "dwc:coordinateUncertaintyInMeters" : "1000",
                     "dwc:institutionCode" : "ASU"
                  },
                  "idigbio:dateModified" : "2014-04-20T23:11:09.437Z"
               },
               "scientificname" : "abies",
               "minelevation_rejected" : false,
               "etag" : "2682a8f2fb77d59d50442925a80fe58a2ad51e9c",
               "maxdepth_rejected" : false,
               "family" : "pinaceae",
               "institutioncode" : "asu",
               "geopoint" : {
                  "lat" : 23.5821004818154,
                  "lon" : -105.859665870667
               },
               "fieldnumber" : "4031",
               "geopoint_geohash_2" : "9s",
               "stateprovince" : "sinaloa",
               "mediarecords" : [
                  "db38f86b-99f5-4dc4-b4a6-a045a9c35323"
               ],
               "country" : "mexico",
               "collector" : "t. f. daniel;",
               "geopoint_geohash_4" : "9shw",
               "version" : 1,
               "genus" : "abies",
               "geopoint_geohash_3" : "9sh",
               "datemodified" : "2014-04-20",
               "catalognumber" : "asu0000166",
               "mindepth_rejected" : false,
               "maxelevation_rejected" : false
            },
            "_score" : 1,
            "_index" : "idigbio-1.0.0",
            "_id" : "0cec43d8-9ad5-478a-bea1-397ab5cc4430",
            "_type" : "records"
         }
      ],
      "max_score" : 1,
      "total" : 1
   },
   "timed_out" : false,
   "_shards" : {
      "failed" : 0,
      "successful" : 10,
      "total" : 10
   },
   "took" : 64
}

Fetch five MediaRecord IDs (endpoints) from the API

Example URL:

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

Example API Results: 

 curl -s http://api.idigbio.org/v1/mediarecords?limit=5 | json_pp
{
   "idigbio:errors" : [],
   "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5"
   },
   "idigbio:items" : [
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000003cd-0cca-421b-8f26-f557a26b0393"
         },
         "idigbio:uuid" : "000003cd-0cca-421b-8f26-f557a26b0393",
         "idigbio:version" : 1,
         "idigbio:etag" : "ce3e2f7272ec996bb479c87549ba90c15ba96426",
         "idigbio:dateModified" : "2014-04-21T22:19:27.436Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00000728-ffb3-4a68-9f93-137f19961121"
         },
         "idigbio:uuid" : "00000728-ffb3-4a68-9f93-137f19961121",
         "idigbio:version" : 2,
         "idigbio:etag" : "c13b10675b4a83031b1dc7a24c1f5c4e443b1939",
         "idigbio:dateModified" : "2014-04-03T17:43:18.145Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00000b03-e208-4d22-983b-506ad2842f7c"
         },
         "idigbio:uuid" : "00000b03-e208-4d22-983b-506ad2842f7c",
         "idigbio:version" : 2,
         "idigbio:etag" : "bc118a7ea53e004c82ab9b7e813e1010ae5f8e17",
         "idigbio:dateModified" : "2014-04-20T05:16:20.389Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000010bc-a4d4-483d-b71d-0dbdd4fd2d5a"
         },
         "idigbio:uuid" : "000010bc-a4d4-483d-b71d-0dbdd4fd2d5a",
         "idigbio:version" : 0,
         "idigbio:etag" : "68c441bd3c49507bf930f3b278f2c58f9cb792ec",
         "idigbio:dateModified" : "2014-04-20T21:38:46.679Z"
      },
      {
         "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000012f9-d288-4a14-b898-77430e0a137a"
         },
         "idigbio:uuid" : "000012f9-d288-4a14-b898-77430e0a137a",
         "idigbio:version" : 0,
         "idigbio:etag" : "0357f74dada8b21a69281b042a52f47a172fa33b",
         "idigbio:dateModified" : "2014-01-20T20:19:29.754Z"
      }
   ],
   "idigbio:itemCount" : "2199334"
}



To Do: Provide examples of displaying multiple images accessed via the mediarecord API endpoint.

https://api.idigbio.org/v1/records/4e98d066-f35f-4cc0-ad7c-b5b5f2175521/media?quality=thumbnail

https://api.idigbio.org/v1/mediarecords/4c4c5008-5444-4348-85f5-34112b46169b/media?quality=web


Elasticsearch Examples

TBD

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.

Retrieved from "http://www.idigbio.org/wiki/index.php?title=IDigBio_API_v1_Examples&oldid=9539"