IDigBio API v1 Examples

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.

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.

For example, this is the raw JSON returned by the base URL of the API:

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

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).

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

JSONView Browser Extension Example

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.