yboss - a JavaScript wrapper for Yahoo's BOSS API

Why a wrapper library?

Whilst BOSS comes with great documentation it can be a bit daunting to use, especially seeing that some of the requirements to display information are hard to find.

BOSS gives you a lot of power and comes with a lot of options, but most of the time all you want to do is to do a simple search, get some information back and display it. This is exactly what this wrapper library does and it is built purely in JavaScript with no server-side dependencies.

Example

Code


<div id="results"></div>
<script type="text/javascript" src="yboss-lib.js">
</script>
<script type="text/javascript">
YBOSS.get(
{
  searches:'search,news',
  query:'obama',
  count:10,
  callback:seedpics
}
);
function seedpics(o){
 var all = '<h4>Web Sites</h4>' + o.webHTML + 
           '<h4>News</h4>' + o.newsHTML;
 var out = document.getElementById('results');
 out.innerHTML = all;
}
</script>
                    

Output

Using the library

Using the library is dead easy: simply add it to your document:

<script type="text/javascript" src="yboss-lib.js"></script>

The library has an own developer key, however to ensure that it works for everyone and get information on your usage as a developer I'd strongly encourage you to get an own developer key and override the in-built one thus:

<script type="text/javascript" src="yboss-lib.js"></script>
YBOSS.appId = your_app_id;

Once all that is done, you have access to YBOSS.get() which is a method to retrieve search data from Yahoo images, news and search in one go. You can use all the parameters defined BOSS documentation and you need some more.

Say for example you want to get the first 10 images, web sites and news about "obama", you do the following:


YBOSS.get(
 {
   searches:'news,images,search',
   query:'obama',
   count:10,
   callback:foo
 }
);
function foo(o){
  alert(o);
}
       

The important thing here is "searches", which is a comma separated string of what you want to retrieve and "callback" which is the function that gets called when the data was successfully retrieved.

Output formats

Once the library has done all its magic, it'll send you the data from BOSS just in the most necessary format. The object that gets sent to the callback function has properties for all the searches you did:

JSON

The JSON output for the searches are object.web, object.images and object.news and all of them are arrays.

Each entry of the arrays has different properties depending on the format:

web
abstract
Description of the link
title
Text of the link
url
URL of the link
displayurl
Link in a nice display format
news
abstract
Description of the news item
title
Title of the news item
url
URL of the news item
language
Language of the news item
source
Name of the news agency
sourceurl
URL of the news agency
images
abstract
Description of the image
title
Title of the image
url
URL of the image
page
URL of the page containing the image (with click tracking)
pagedisplay
Readable URL of the page containing the image
shorturl
Forty character version of the page URL (as per terms and conditions of image search)
filename
Image filename
imageurl
Image URL (without clicktracking)
thumbnail
Thumbnail URL
thumbnaildimensions
Thumbnail dimensions (array of width and height)
dimensions
Image dimensions (array of width and height)
format
Image dimensions format

HTML

The HTML outputs are there for the really lazy people. Instead of having to convert and assemble your own HTML from the JSON data you can use object.webHTML, object.imagesHTML and object.newsHTML to get HTML lists to put into a container as innerHTML.

The formats are lists <ul></ul> with list items for each result:

web

<li><a href="{clickurl}">{title}</a>
  <p>{abstract}</p>
</li>
          
images

<li>
  <a href="{clickurl}">
    {title}
  </a>
  <a href="{url}">
    <img src="{thumbnail}" 
    width="{thumbnailwidth}"
    height="{thumbnailheight}">
  </a>
  <p>{shortened url}</p>
<li>
news
    
<li lang="{language}">
  <a href="{clickurl}">{title}</a>
  <p>{abstract} ({source})</p>
</li>
    
  

You can override these presets by changing YBOSS.config.webItemHTML, YBOSS.config.newsItemHTML and YBOSS.config.imageItemHTML using the {parameter} syntax shown here. Right now, you can only change the order of things, in the next version I might add all parameters in the HTML output.

Download

Bla bla bla, BSD license, open source, use commercially and have fun and so on...

Written by Chris Heilmann, powered by BOSS

This is not an official Yahoo! site and not endorsed by the company.