Developer Documentation

Developer Tools

Query Editor App Editor Schema Explorer

Freebase Suggest

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.

Try it out:

Features:

  • Cross browser - based on jQuery, tested on IE7+, FF2+, Safari 3+ and Chrome
  • 33KB Minified (+ 19KB for jQuery)
  • Cross-domain. No proxy servers required thanks to JSONP.
  • Hosted on freebaselibs.com
  • Free! (The standard Freebase ToS apply.)

Add to your site

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

<link type="text/css" rel="stylesheet" href="http://freebaselibs.com/static/suggest/1.0.1/suggest.min.css" />
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
<script type="text/javascript" src="http://freebaselibs.com/static/suggest/1.0.1/suggest.min.js"></script>
<script type="text/javascript">
$(function() {
  $("#myinput").suggest({type:'/film/director'});
});
</script>

Assuming this text input in the document body:

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

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 Google Code Issues List.

Examples

Example 1. Basic usage

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

Try it out here:

Example 2. 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 here:

Example 3. Required

$("#example3")
.suggest({
  "required": "always"
})
.bind("fb-select", function(e, data) {
  alert(data.name + ", " + data.id);
})
.bind("fb-required", function(e) {
  alert("This is required");
});

Try it out here:

Example 4. Constraining suggestions by type and type_strict

Constrain suggestions by countries or US States. 

$("#example4")
.suggest({
  "type": ["/location/country", "/location/us_state"],
  "type_strict": "any"
})
.bind("fb-select", function(e, data) {
  alert(data.name + ", " + data.id);
});

Try it out here:

Example 5. Constraining suggestions by mql_filter

Suggest films directed by Steven Spielberg 

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

Try it out here:

Example 6. Search box behavior

Add suggest to your search box. 

$("#example6")
.suggest({
  "type": "/film/film",
  "soft": true
})
.bind("fb-select", function(e, data) {
  alert(data.name + ", " + data.id);
});
Try it out here:

Plugins

The Freebase Suggest core library is extensible to create your own custom suggestions. The core library can be thought as a drop down list that appears below a text input and handles keyboard and mouse interactions with the list like up and down arrow keys and selecting. Here are some plugins that are an extension of the core Freebase Suggest library.

Freebase Suggest API

Options

type String, Array Default: null

Searches may be made more specific by matching against the type(s) of topics by passing one or more type value(s). Type value may be ids, guids or names of types. More than one type can be passed in by using the type parameter as an array (i.e., ["/people/person", "film actor"]).

type_strict String Default: "any"

This parameter makes it possible to control how specific the type matches must be. A value of
"should" gives preference to matches by boosting their query score but doesn't require any,
"any" requests that at least one type value matches and
"all" requires that all types match.

mql_filter Object, String (JSON) Default: null

This parameter may be used to specify a topic-rooted MQL query to use against full text index matches.

When using mql_filter, one should be careful to front-load as many as possible of the overall query constraints to the full text queries. For example, it is much faster to constrain a query on type via the type parameter than a type clause in a MQL filter.

Note that the mql_filter query cannot have a constrained id clause since it receives an extra guid|= clause containing the guids of matches to pass through the filter. Having these clauses together is not supported by MQL.

flyout Boolean, "bottom" Default: true

Whether or not to show a flyout description on hover. If "bottom", show flyout at the bottom of the suggest list. If the suggest list is displayed above the input box, the flyout will be displayed on top of the list. If TRUE, suggest will do it's best to show the flyout either on the left or right side of the list.

required Boolean, "always" Default: false

This can be used to help with input validation. Values can be true, false or 'always'. If true, an 'fb-required' event will be triggered if nothing is selected and the input value is NOT empty. If 'always', 'fb-required' will be triggered if no selection is made even if the input value is empty.

suggest_new String Default: null

This can be any text to be shown below the suggestion list. On selection, an 'fb-select-new' will be triggered.

css Object

You can overwrite default css class names used for the various suggest elements

pane The outer container of the suggest list. Default: 'fbs-pane'
list The suggest list. Default: 'fbs-list'
item The suggest list items. Default: 'fbs-item'.
item_name The element containing the the name of the item. Default: 'fbs-item-name'
selected The current highlighted/selected item. Default: 'fbs-selected'.
flyoutpane The flyout outer container. Default: 'fbs-flyoutpane'.
css_prefix String Default: null

You can specify a prefix to be pre-pended to the class names of the the suggest elements. For example if css_prefix is "foo-" the container names will be "foo-fbs-pane" and "foo-fbs-flyoutpane".

soft Boolean Default: false

Carry over from previous freebaseSuggest to enable search box behavior without forcing a selection from the suggest list. If true, DO NOT auto-select first item on ENTER key. Otherwise, select first item.

service_url String Default: "http://www.freebase.com"

This is the base url for the suggest service.

service_path String Default: "/private/suggest"

service_url + service_path = url to the suggest service.

flyout_service_url String Default: null

The base url for the flyout service. If null, defaults to service_url.

flyout_service_path String Default: "/private/flyout"

flyout_service_url + flyout_service_path = url to flyout service.

align String Default: null

The suggest list is aligned to the "left" or "right" of the input box depending on it's position in the document. To override this behavior you can set align to "left" or "right" of the input box.

status Array[3](String) Default: ["Start typing to get suggestions...", "Searching...", "Select an item from the list:"]

Status messages that appear at the 3 different stages of suggest; [0] When input box is empty and gets focus. [1] when retrieving results, [2] when displaying the results. You can override these default status messages by passing in a different Array of string corresponding to the 3 different stages.

parent String (jQuery selector) Default: null

By default, the suggest list is appended to the document body and positioned absolutely. You can specify a different parent and the list will not be absolutely positioned.

animate Boolean Default: false

If true, the showing of the suggest list will be animated using jQuery slideDown effect.

xhr_delay Integer (ms) Default: 200

This is mostly useful in the case where mql_filters are complex and suggest service might take more or similar time to answer than the hardcoded delay, causing a somewhat degraded user experience and unnecessary load.

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) { ... });

fb-required - When required is set to true or 'always', this event will be triggered when an item is NOT selected from the suggest list and the input loses focus. 


$("#myinput").suggest({'required': 'always'}).bind("fb-required", function(e) { ... });