Table of Contents:
Frequently Asked Questions

What is the Bounce API?
The Bounce API is a very simple way to integrate Bounce MixedResults into your own website or application. The API accepts simple REST requests, and returns an RSS or JSON feed.

What is Bounce MixedResults?
Bounce MixedResults is a search service which combines and sorts the results from multiple search engines, just like the "Find Stuff" search on the BounceBase sidebar. There are a number of search groups, each of which has an underlying set of search sources. For example, a MixedResults search using the jobs group provides job listings from Monster, SimplyHired, Craigslist, and more.

What is the MixedResults AJAX API?
The MixedResults AJAX API is a Javascript library which makes it super-simple to grab and display results from the main MixedResults API on your own webpage. It uses AJAX requests so you don't even need to reload the page to show the results.

Can I make money using the MixedResults?
Good question, I'm glad you frequently asked. For certain search groups (those that bring in revenue for Bounce), there is an opportunity for you to make a bit of cash. If you register as an affiliate, you'll get a monthly sum which is based on the amount of paying traffic your site generates.

Do you have a SOAP API?
SOAP!? That's crazy talk. Don't make me wash your mouth out with REST.

What are the available search groups?
So far we have eight search types, but we have plans to add more over time:

blogs Searches across blogs, using search engines such as Technorati, BlogLines, BlogDiger, etc.
feedfinder Searches for RSS/Atom feeds using services such as Syndic8.
internet A web search using Google, Yahoo, MSN, etc.
internet and blogs A hybrid of the above Internet and Blog searches, resulting in a basic web search which has a slight preference for bloggy results.
local jobs Searches Monster, Google Base, SimplyHired, etc. Requires a US postal code.
local shopping Finds items for sale in a local community, including results from Craigslist, MS Expo, Oodle, etc. Requires a US postal code.
shopping Finds items for sale online, including Amazon, eBay, Google Base, etc.
video Searches for online videos across YouTube, DailyMotion, Google Video, etc.


What search groups do you intend to add in the future?
We have a number of new groups planned, but we don't want to let the cat out of the bag too soon. If you have any suggestions for new search groups, feel free to contact us.

How fresh is the data from MixedResults?
This varies depending on a number of factors, but generally speaking the results will be no more than four hours old.
Bounce MixedResults API

The Bounce MixedResults API accepts GET or POST HTTP requests, including a number of parameters which vary depending on the search type. If you need to make more than 100 API requests per day, you'll need to become an affiliate and send your affiliate ID as part of the request (see below).

Simple example:

http://search.bouncebase.com/?group=bounce-shopping&Keywords=digital+voice+recorder

Big nasty example:

http://search.bouncebase.com/?group=bounce-local-jobs&Keywords=php+programmer&Postal=84057&Exclude=exciting&aid=jobsite&sort=price:asc:1&npp=15&page=1&output=json&notsrc[]=simplyHired&notsrc[]=jobsDotCom


Required Parameters

Every MixedResults search requires two parameters:


group Possible values: bounce-blogs, bounce-feedfinder, bounce-internet, bounce-internet-and-blogs, bounce-local-jobs, bounce-local-shopping, bounce-shopping, bounce-video
Keywords One or more search keywords

For "local" searches, an additional parameter is required:


Postal A five-digit US ZIP code


Optional Parameters

A number of other parameters can be included which may be helpful:


Exclude Words which should be excluded from results. For example, if you are searching for "Mercury" automobiles, you can improve results by excluding "planet element".
aid Your Bounce affiliate ID.
npp Number of results per page. Can be used to simply limit the number of results returned, or can be used in conjunction with 'page' parameter to request results a page at a time. Default is '0', which returns all results.
page Used together with 'npp', this parameter allows you to request results a page at a time. Default is '1'.
sort-by The name of the field to sort entries by.

Possible values: score, date, title, author, price
sort-dir Sort direction.

Possible values: asc, desc
sort-mode Specifies whether the given sort should be executed numerically or alphabetically. A "1" indicates numeric, an "a" indicates alphabetic.

Possible values: 1, a
sort A shorthand way of specifying the sort parameters, formatted as sort-by:sort-dir:sort-mode. Example: "sort=price:asc:1"
src[] The ID of a search source you wish to include in the query. When this parameter is provided, the search will include only the specified sources, even if new sources are added to a search behind-the-scenes. Should not be used in conjunction with the notsrc[] parameter.

Multiple sources can be specified by sending the parameter multiple times. Example: "src[]=ebay&src[]=amazon"

See the individual MixedResults source IDs in the search types documentation for valid values.
notsrc[] The ID of a search source you wish to disinclude from the query. When this parameter is provided, the search will include all sources except the specified sources. Should not be used in conjunction with the src[] parameter.

Multiple sources can be specified by sending the parameter multiple times. Example: "notsrc[]=googleBase&notsrc[]=ebay"

See the individual MixedResults source IDs in the search types documentation for valid values.
as The format to use in the response data. Default is "xml".

Possible values: xml, json

Bounce MixedResults AJAX API

Perhaps the most useful way to learn about the AJAX API is to see the code in action, which you can do here. You can use your browser's View Source feature to see the underlying code.

To access the Bounce MixedResults AJAX API, you must include two javascript files in the <head> section of your webpage (in this order):

<script type="text/javascript" src="http://feeds.bounceisfree.com/api/bounce-lib.js"></script>
<script type="text/javascript" src="http://feeds.bounceisfree.com/api/bounce-ajax-feed-api.js"></script>

This will allow you to create the Bounce.MixedResultsSearch object within your own javascript code:

var apiSearch = new Bounce.MixedResultsSearch();

With this object, you can build a Bounce API search by setting the configuration variables. For all searches, group and keywords are required. For 'local' searches, zip is also required. To get an affiliate ID, you'll need to register as an affiliate.

apiSearch.group = 'bounce-local-jobs';
apiSearch.keywords = 'api documentation writer';
apiSearch.exclude = 'ajax';
apiSearch.zip = '90210';
apiSearch.numPerPage = 10;
apiSearch.pageNum = 1;
apiSearch.affiliateID = 'my-affiliate-id';

You may also optionally specify sources you wish to disinclude, using the source IDs as listed in the search types documentation:

apiSearch.skipSource('jobsDotCom');
apiSearch.skipSource('hotJobs');

To start the API search, call the object's get() function, providing the name of one of your own functions it should call once the results are ready (more on this below):

apiSearch.get(showResults);

The Feed object sent to your custom function has a few basic properties:

title The title of the results feed.
date The date that the feed was last updated.
image The icon representing the search type (16x16).
xmlLink The URL to the XML/RSS representation of the results feed.
error The error that occurred while fetching the results (if any).
entries An array of search result objects.

Each of the entries items contains:

title The title of the individual result.
link The destination URL for the search result.
author The author of the individual item (usually the website name).
content The long description of the item, HTML included.
snippet A short version of the content, HTML removed.
date The date that the item was created.
icon The icon representing the originating website (16x16).
price The item price (for 'shopping' items only, when available).
score The search rank of the item, where '1' is the most relevant item.

Your custom function which handles the results should accept a single argument, a Feed object. It can then do whatever it will with the feed properties and the included entries:

function showResults (feedObject) {
   var resultsArea = document.getElementById('results');
   resultsArea.innerHTML = feedObject.title;

   for (var i=0; i < feedObject.entries.length; i++) {
      resultsArea.innerHTML+= feedObject.entries[i].title;
   }
}

The Feed object also offers a function to sort the entries as needed, which should only be called before looping through them (the default sort is score, SORT_NUMERIC, SORT_ASCENDING).

The function takes three arguments: sort field, sort type, and sort direction. sort type can be SORT_ALPHABETIC or SORT_NUMERIC, and sort direction can be SORT_ASCENDING or SORT_DESCENDING.

feedObject.sortEntries('date', SORT_NUMERIC, SORT_DESCENDING);

For further insights and examples, see the simple sample script here. Just use View Source to get to the guts.