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

• Download yboss (source and test file as a zip)

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