CloudSearch REST API

Search API

The cloudsearch does an online lookup in different databases, wraps and combines the results for easy consumption.

  http://profile.vtt.fi/api/cloudsearch

    GET
      - q: the query string
      - lang: (optional) preferred UI language (en,fi,sv...)
      - limit: (optional) limit results to this max amount (default 30)
      - freebase: (optional) freebase restricitions
      - dbpedia: (optional) dbpedia restricitions
      - geonames: (optional) geonames restricitions
      - koko: (optional) koko restricitions
      - onki: (optional) onki restricitions
   
    The restrictions are determined from the 3rd party services. 
    A general query could use something like
    
         freebase={type : ["/people/person", "/music/genre", "/music/musical_group", "/film/film", "/film/film_genre", "/book/book", "/book/literary_genre", "/sports/sport", "/sports/sports_team", "/sports/sports_league", "/olympics/olympic_sport", "/tv", "/tv/tv_genre", "/tv/tv_program", "/tv/tv_genre/programs", "/media_common/media_genre", "/broadcast/genre", "/theater/play", "/theater/theater_production", "/cvg/computer_videogame", "/cvg/cvg_genre", "/architecture/building", "/architecture/architectural_style", "/architecture/structure", "/travel/tourist_attraction"]}
         geonames={}
         onki={"ontology": "koko"}

    @return 200 OK on success - the data is JSON or XML depending on client request
  

autocompleteVTT widget

The cloudsearch can be used e.g. with the autocompleteVTT jQuery widget.

The default language in the widget is set by checking the lang attribute of the document's html element.

Ex1: autocomplete with handler function

Add in input field to your page. Give it an id, and optionally a lang attribute. Then use jQuery("#inputid").autocompleteVTT(); to make it a semantic widget.

Ex1:

  <input type="text" id="interests" name="interests" autofocus="autofocus"
         placeholder="Your interests" size="50" lang="fi" />

  <script>
  jQuery(document).ready(function() {
    function myHandler(input, ui) { alert("HELLO " + ui.item.label + 
                                          " <" + ui.item.uri + ">"); }
    jQuery("#interests").autocompleteVTT({url: "http://profile.vtt.fi/api/cloudsearch",
                                          handleAddition: myHandler});
  </script>
  

Above we added an input element, set the preferred language of the search results to Finnish (lang="fi") and created a small handler function that will put up an alert whenever an term is selected by the user.

Ex2: tuple-value input using aria-controls

Ex2 shows a way to handle dual inputs, to store both the label and the uri of the user's hometown.

Ex2:

  <input type="text" name="hometown" id="hometown" 
         placeholder="Your hometown" aria-controls="hometownURI"/> →
  <input type="text" name="hometownURI" id="hometownURI"
         placeholder="Your hometown URI" aria-owns="hometown"
         readonly="readonly" size="50"/>

  <script>
  jQuery(document).ready(function() {
    jQuery("#hometown").autocompleteVTT({url: "http://profile.vtt.fi/api/cloudsearch",
                                         handleAddition: null,
                                         restriction: "places"});
  });
  </script>
  

Above two input fields are defined. (The second is not hidden for demonstration purposes.) The element whose id is hometown is made a semantic widget, with no handler function, defaulting to the restrictions enforced by the option "places" which is shown in a select in the autocomplete widget search suggestions. Using aria-controls we define which element should get the "value" of the selected autosuggest value. To modify that list, alter widget.restrictions to suit your needs.

Ex3: custom restrictions

For fine tuning you can also alter the available options. This shouldn't normally be necessary.

Ex3:

    <input type="text" id="sports" name="sports"
           placeholder="Olymic Sports" size="50" lang="en" />
  
    <script>
    jQuery("#sports").autocompleteVTT({url: "http://profile.vtt.fi/api/cloudsearch",
                                       handleAddition: null,
                                       restriction: "olymic_sports"})
      .data("autocompleteVTT").restrictions.push(
        { name : "olymic_sports",
          label : "OLYMPIC SPORTS",
          value : {
          'freebase': '{"filter" : "(any type:/olympics/olympic_sport)"}'
          }
        });
    </script>