From Freebase

Overview

Freebase Suggest is a jQuery plugin that adds Freebase topic autocomplete to search boxes on your site. Start typing text and the widget suggests relevant matches from the millions of topics on Freebase.com or any subset of types like People, Locations or Animals. Topic flyouts help the user select the correct item which is uniquely identified with a Freebase id..

Features

• Cross browser - based on jQuery, tested on IE7+, FF2+, Safari 3+ and Chrome (min jquery version is 1.4.4)
• Cross-domain. No proxy servers required thanks to JSONP.
• Hosted by Google on gstatic.com
• Free! (The standard Freebase ToS apply.)

Try it out!

Add to your site

It's easy to add Freebase Suggest to your web page. Just include this html in your document head:

<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/freebase/suggest/3_1/suggest.min.css" />
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.js"></script>
<script type="text/javascript" src="https://www.gstatic.com/freebase/suggest/3_1/suggest.min.js"></script>
<script type="text/javascript">
$(function() {
  $("#myinput").suggest({filter:'(all type:/film/director)'});
});
</script>

Assuming this text input in the document body:

<input type="text" id="myinput"/>

You need to obtain an api key in order to make Suggest requests. The widget will work for very limited testing purposes without a key. To obtain a key, follow the instructions here: http://wiki.freebase.com/wiki/API#API_Keys

Once you obtain a key, you can pass it to suggest like this:

$(function() {
  $("#myinput").suggest({ "key" : "<your api key>"});
});

Why do I want Freebase Suggest for my data application?

• With autocomplete, your users type less to enter more data
• Data entry is fun and accurate!
• Reduce the cognitive load on your users thanks to the images and descriptions in the topic flyouts
• Use strong identifiers rather than text keywords. The name "Sting" is ambiguous, but the Freebase IDs /en/sting and /en/sting_1959 are not.
• Avoid duplicate names for the same entity. Puff Daddy, P. Diddy, Sean Combs all refer to /en/sean_combs

Questions?

Questions, bug reports and feedback very welcome on the Freebase Developers Mailing List or the Issues List (choose Search/Suggest component).

Configuration options

CSS classes

The default CSS classes used by the suggest widget can be overidden by passing in a map of new the class names using the css configuration option.

For example:

$("#myinput").suggest({
  "css": {
    "pane": "custom-pane-class",
    "list": "custom-list-class"
  }
});

Events

Freebase Suggest triggers the following events within the context of the input that it is initialized with.

fb-select - When an item is selected from the suggest list. The event is accompanied by a data object where data.name and data.id represent the name and id of the item that was selected.

$("#myinput").suggest().bind("fb-select", function(e, data) { ... });

fb-select-new - When the suggest_new option is enabled, this event is triggered when the suggest_new item is selected. The event is accompanied by the input value.

$("#myinput").suggest({'suggest_new': 'This is the suggest new text'}).bind("fb-select-new", function(e, val) { ... });

Examples

Basic usage

$("#example1")
 .suggest()
 .bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
});

Try it out!

Suggest new

$("#example2")
 .suggest({
   "suggest_new": "Click on me if you don't see anything in the list"
 })
 .bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
 })
 .bind("fb-select-new", function(e, val) {
   alert("Suggest new: " + val);
 });

Try it out!

Constraining suggestions using a filter

Suggest films directed by Steven Spielberg.

$("#example5")
.suggest({
   "filter": "(all type:/film/film contributor:\"Steven Spielberg #directed_by\")"
})
.bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
});

Try it out!

Filtering from the textbox

It is possible to filter the results by typing any of the filter constraints directly into the suggest box, e.g. to search for books on gardening:

gardening type:/book/book
gardening type:book

Freebase Suggest in the wild

Sites which are known to use Freebase Suggest:

• WSJ Book reviews
• ContentTagger.org - tagging demo from the Guardian Newspaper
• c0sm.org - add celebrities to the c0sm.
• Famous.io - find celebrity news
• geolocation.ws - freebase suggest is used to tag photos to Freebase entities

FAQs

I've just created a new topic, but it isn't showing up in Suggest - what's going on?

Freebase Suggest uses the search API to provide its results, and that is updated in near-real-time. New topics usually appear within a minute or so, but this can be longer if the system is under high load.

• Freebase Suggest Recipes - share your tips on using Suggest here