Getting started with Videorooter API

Posted by on Feb 17, 2016 in Uncategorised

If you’re interested in playing with our data set and helping to see how we match images and videos with the blockhash algorithms, our API is a good start, despite it being in a rough state of development.

The current API supports a subset of the API calls the Elog.io API supports, at least enough such that the Elog.io browser extension for Chrome and Firefox can also work against the Videorooter API. You can have a look at the API specifications for Videorooter too, and follow this guide to learn how to use it. The end point for Videorooter’s development API is http://devc.commonsmachinery.se:8080/

For this guide, you’ll want to have downloaded and compiled the blockhash code with experimental video support. First thing you would want to do after that is fetch yourself an image or video to work on. The Videorooter API provides a way to get a random work from our database:

$ curl -L http://devc.commonsmachinery.se:8080/random

When called with /random, the API will find a random work and reply back with a Location HTTP redirect. Passing -L to curl makes it re-do the request and get the data from the random work. You can request a purely random work, or specifically an image or video:

$ curl -L http://devc.commonsmachinery.se:8080/random?type=image
 $ curl -L http://devc.commonsmachinery.se:8080/random?type=video

Let’s say this is the random work you retrieved. Most of the information about the work, such as the license and author, is delivered as Media Annotations conforming to the recommendations from the W3C’s Media Annotations Working Group, specifically the Ontology for Media Resources 1.0.

{"href": "http://devc.commonsmachinery.se:8080/works/36007",
 "media": [{
       "id": 36007,
       "href": "http://devc.commonsmachinery.se:8080/works/36007/media"}],
  "owner": {"org": {"id": 1, "href": "http://example.com"}},
  "description": "13 Amsterdamse baby's die de Hongerwinter overleefde.\n Wat doe je als
 je niet genoeg te eten hebt voor je kind? In het laatste jaar van de
 Tweede Wereldoorlog was er in Amsterdam gebrek aan van alles:
 brandstof, kleding, maar vooral eten. Dagelijks",

  "public": "true",
  "id": 36007,
  "added_at": "2015-02-21T11:11:12.685Z",
  "annotations": [
     {"language": "en",
      "titleLabel": "Het Babyhuis",
      "propertyName":"title"},
     {"identifierLink": "https://commons.wikimedia.org/wiki/File:Het Babyhuis.webm",
      "propertyName": "identifier"},
     {"propertyName": "locator",
      "locatorLink": "https://upload.wikimedia.org/wikipedia/commons/b/be/Het_Babyhuis.webm"},
     {"statementLabel": "CC BY 3.0",
      "propertName": "policy",
      "statementLink": "http://creativecommons.org/licenses/by/3.0",
      "typeLabel": "license",
      "typeLink": "http://www.w3.org/1999/xhtml/vocab#license"},
     {"collectionLink": "http://commons.wikimedia.org", "propertyName": "collection"},
     {"propertyName": "creator", "creatorLabel": "Amsterdam Museum"},
     {"propertyName": "copyright", "holderLabel": "Amsterdam Museum"}]}

Let’s get the video and calculate its blockhash:

$ curl -O https://upload.wikimedia.org/wikipedia/commons/b/be/Het_Babyhuis.webm
$ build/blockhash_video Het_Babyhuis.webm
0000000000000000545c40f672e07e043133133337213d18003c243c04000000 Het_Babyhuis.webm

This gives us the 256 bit blockhash of the video file. If Videorooter works as expected, we should now be able to use the blockhash to look up the work in reverse:

$ curl http://devc.commonsmachinery.se:8080/lookup/video?hash=0000000000000000545c40f672e07e043133133337213d18003c243c04000000
[{"href": "http://devc.commonsmachinery.se:8080/works/36007", "distance": 0}]

It works! We get to know that we matched the work perfectly, with a distance of 0 bits (it allows a maximum deviation of 10 bits currently). If you want to search for images, you can hit the /lookup/blockhash endpoint with the same parameter.

The return from the lookup functions is an array with references to all works matched. You can then make subsequent calls to get more information about them:

$ curl http://devc.commonsmachinery.se:8080/works/36007

Happy hacking!

Leave a Reply