IDigBio API v1 Examples: Difference between revisions

From iDigBio
Jump to navigation Jump to search
(add screenshot of jsonview extension)
(fix auto-gen table of contents location, add some code tags, other minor tweaks)
Line 1: Line 1:
See [[IDigBio API]] for full documentation on the API including all of the available endpoints.
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.


For best sampling of JSON results in a browser, you may wish to use the JSONView Extension for Chrome and Firefox.
=== Viewing JSON Output ===


In most cases for these examples we format the output of the JSON document using a "pretty printing" feature of some kind in order to make this document more readable by humans.
A short JSON document is returned by the API when calling the GET method against the base URL:
 
For example, this is the raw JSON returned by the base URL of the API:


<pre>
<pre>
Line 12: Line 10:
</pre>
</pre>


This becomes easier to read if we pipe the output through a formatter such as python's json.tool or the json_pp command-line Perl script (JSON::PP).
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'''
 
[[File:JSONView_browser_extension_example.png|border|JSONView extension allows easier viewing in a web browser]]
 
If using a command-line tool (such as <code>curl</code>), 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 <code>grep</code>.
 
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'''
'''json.tool Example'''
Line 34: Line 40:
</pre>
</pre>


'''JSONView Browser Extension Example'''
[[File:JSONView_browser_extension_example.png|border|JSONView extension allows easier viewing in a web browser]]


=== Fetch A Single Record from the API ===
=== Fetch A Single Record from the API ===

Revision as of 15:44, 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/"
}


Fetch A Single Record from the API

Example URL:

http://api.idigbio.org/v1/records/c93ebbee-64b5-4452-9e80-93bbfb11b815


In this example we use the curl command-line utility to fetch a single record from the API using the record's iDigBio uuid, then pipe the output to a JSON pretty printing program for human readability.


Example API Results: 

$ curl -s http://api.idigbio.org/v1/records/c93ebbee-64b5-4452-9e80-93bbfb11b815 | json_pp
{
   "idigbio:uuid" : "c93ebbee-64b5-4452-9e80-93bbfb11b815",
   "idigbio:etag" : "9c1eb0e2c0b94543f69dad5005f700d77f118ff7",
   "idigbio:links" : {
      "owner" : [
         "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "recordset" : [
         "http://api.idigbio.org/v1/recordsets/6bb853ab-e8ea-43b1-bd83-47318fc4c345"
      ]
   },
   "idigbio:version" : 10,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
      "6bb853ab-e8ea-43b1-bd83-47318fc4c345\\6CB7D2F5-C76E-43FD-BACD-097EC550BA18"
   ],
   "idigbio:dateModified" : "2014-04-01T23:17:14.780Z",
   "idigbio:data" : {
      "dwc:catalogNumber" : "125191-Mollusca",
      "dwc:specificEpithet" : "gibberulus",
      "dwc:class" : "Gastropoda",
      "dwc:occurrenceID" : "6CB7D2F5-C76E-43FD-BACD-097EC550BA18",
      "dwc:infraspecificEpithet" : "gibbosus",
      "dwc:recordedBy" : "Kohr, H. H.",
      "dwc:scientificName" : "Strombus gibberulus",
      "dwc:family" : "Strombidae",
      "dwc:basisOfRecord" : "PreservedSpecimen",
      "dwc:collectionCode" : "Invertebrate Zoology",
      "dcterms:modified" : "03/21/2014",
      "dwc:decimalLongitude" : "144.8",
      "dwc:country" : "USA",
      "dwc:scientificNameAuthorship" : "Röding",
      "dwc:locationID" : "ZZZ-072834",
      "dwc:stateProvince" : "Mariana Islands",
      "dwc:genus" : "Strombus",
      "dwc:decimalLatitude" : "13.5",
      "dwc:institutionCode" : "FLMNH",
      "dwc:order" : "Mesogastropoda",
      "dwc:county" : "Guam Island"
   }
}


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=9535"