Home › Ookaboo API ›

Ookaboo Semantic API Documentation

Submitted by staff on Tue, 08/17/2010 - 15:27

Making a request

You make a request to the Ookaboo Semantic API by performing an HTTP GET request to the following URL:

http://api.ookaboo.com/api1/lookup_picture?api_key={key}&query_uri={uri}

Where {key} is your API Key (it looks like "NDc3N2JiNzM5") and {uri} is a urlencoded URI from a URI space that Ookaboo supports. Currently Ookaboo supports the following URI spaces:

Interpreting the results

A query with the following query_uri

http://ookaboo.com/o/pictures/topic/79986/Aalborg

could return the following JSON code

{
   "version":"1.0",
   "success":true,
   "calls_left":998,
   "seconds_left":10
   "result":{
     
      "topic":{
         "covered":true,
         "out_of_scope":false,
         "title":"Aalborg",
         "ookaboo_uri":"http:\/\/naoko.ookaboo.com\/o\/pictures\/topic\/79986\/Aalborg"},
          aka":[
             {"uri":"http:\/\/dbpedia.org\/resource\/Aalborg"},
             {"uri":"http:\/\/en.wikipedia.org\/wiki\/Aalborg"},
             {"uri":"http:\/\/rdf.freebase.com\/ns\/guid.9202a8c04000641f8000000000ca532d"},
             {"uri":"http:\/\/rdf.freebase.com\/ns\/en.aalborg"}
         ],
         "pictures":[
            {
               "ookaboo_uri": 
                  "http:\/\/naoko.ookaboo.com\/o\/pictures\/picture\/79987\/Aalborghus_Castle_2008",

               "license":"cc-by-sa\/3.0", 
               "source_uri":
                  "http:\/\/commons.wikimedia.org\/wiki\/File:Aalborghus_Slot,_29_april_2008,_billede_6.jpg",
               "images":[
                  {
                     "size_code":"o",
                     "img_uri":                          "http:\/\/images.ookaboo.com\/photo\/o\/Aalborghus_Slot_2C_29_april_2008_2C_billede_6_2_o.jpg",
                     "height":"2472",
                     "width":"3296",
                     "bytes":"1136063",
                     "sha1":"a0b71f3ccb519e4c951b983cc6699c587f721856"
                 }
                 , ... additional "image" records for sizes l,m,s,t and sq ...
        },
        "sources":[
           {"type":"creator",
             "title":"V\u00e4stg\u00f6ten from Wikimedia Commons",                  
             "ookaboo_uri":     "http:\/\/naoko.ookaboo.com\/o\/pictures\/source\/79988\/V\u00e4stg\u00f6ten",
             "source_uri": "http:\/\/commons.wikimedia.org\/wiki\/User:V\u00e4stg\u00f6t"
        }]
   }, ... additional picture records ...
}

API Envelope Parameters

"version" is the current version of the Ookaboo API.

The variable "success" is true if a request is successful and false otherwise.

If a request is successful, the Ookaboo API returns a "result" object, otherwise, it returns an "errors" collection that contains both coded and human-readable error messages.

Ookaboo's rate limiting is on the basis of hourly periods. "calls_left" is the number of API calls that you have left in the current period, and "seconds_left" is the number of seconds left in the current period.

Information about the topic

To ensure correct identification of a topic, the Ookaboo API returns information about the topic being queried:

covered: This is true if the topic is covered, that is, contained, in Ookaboo. It is possible that the API is aware that a topic exists, but that topic is not currently covered in Ookaboo. "covered" has open-world semantics... Just because a topic is not covered doesn't mean that it may not be covered in the future.

out_of_scope: An out-of-scope topic is a topic that is known to be inappropriate for Ookaboo, that is, not depictable. out_of_scope supports closed world reasoning: something that is "out_of_scope" will never be "covered".

title: an English-language name for the topic. This is not guaranteed to be unique and may change over time.

aka: an array of "aka" or "also-known-as" records. These are links to external resources that are substantially the same as the topic. We consider the "aka" relationship to be similar, but not quite the same, as "owl:sameAs"

ookaboo_uri: this is the URI that represents the topic in ookaboo. The ookaboo_uri of a topic may change over time, but will always be accepted as a query_uri and, upon http GET request, will be 301 redirected to the current URI.

Picture information

The "pictures" array contains a list of pictures related to the topic. It contains the following fields

ookaboo_uri: this URI represents the picture in Ookaboo. The ookaboo_uri of a picture may change over time, but if changed, will always be 301 redirected to the current URI.

license this is the URI of the page on the Creative Commons web site that describes the license of the image: typically this looks like http://creativecommons.org/licenses/by-sa/2.0/

source_uri: if the image was imported from an external collection, this is the URI of a page that contains metadata about an image: for example, http://commons.wikimedia.org/wiki/File:Aivazovsky,_Ivan_-_The_Ninth_Wave... or http://www.flickr.com/photos/paul_houle/4097748571/

images: An "image" is a specific rendition of a "picture" at a specific size. Image sizes in Ookaboo are, currently, based on the image sizes used in flickr. The format of an image description is described below.

sources: A "source" is a link in the provenance chain of an image. The "sources" array is in chronological order and describes known steps in the processing and acquisition of an image. Currently, the "creator" is the only the source that is consistently available. the format of a source is described below

Image Information

size_code: An alphanumeric code that names the size of an image: These are currently "sq" (square), "t" (thumbnail), "s" (small), "m" (medium), "l" (large) and "o" (original). We reserve the right to add more and the future and note that all sizes may not be available for all images.

img_uri: A GET request to this URI will retrieve the image. This URI is permanent unless the image is removed from Ookaboo. Users of the Ookaboo API are allowed to hotlink this URI (use it as the subject of an <A HREF>) on an HTML page that also contains a hyperlink to the ookaboo_uri of the photo.

height: Image height in pixels

width: Image width in pixels

bytes: Size of image in bytes

sha1: hex-encoded SHA1 hash of image

Source Information

type: type of source... Currently this is "creator" but it could be a comma separated list of roles such as "creator,photographer,uploader"

title: human-readable name of source, localized to English if possible

ookaboo_uri: Linked data URI for the source in the Ookaboo system

source_uri: If available, this is a URI for the source in an external system, for instance http://www.flickr.com/photos/paul_houle/