IDigBio API v1 Examples

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

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.