PHP Classes


Recommend this page to a friend!
  Classes of Fabian Schmengler  >  Yahoo Search API Client (BOSS)  >  README.TXT  >  Download  
Role: Documentation
Content type: text/plain
Description: Documentation
Class: Yahoo Search API Client (BOSS)
Perform Web searches using the Yahoo BOSS API
Author: By
Last change:
Date: 11 years ago
Size: 6,237 bytes


Class file image Download
|                            Yahoo BOSS Client                                |

- Synopsis
- Requirements
- Files
- Step-by-Step Usage
- Extending

Yahoo BOSS (Build your Own Search Service) is a free search API. This package
can retrieve results of web, news and image search and also cache them.

The package requires PHP 5.3.0 or later with ini setting allow_url_fopen.

To use the package, just include YBC.lib.php

You will need a BOSS AppId from Yahoo. Get one for free at:

readme.txt - the file you are reading right now
license.txt - BSD license
YBC.lib.php - library loader, include this file to use the package
example.php - example: simple demonstration
YBC/AbstractQuery.php - class file: base class for queries
YBC/AbstractResult.php - class file: base class for result
YBC/Cache.php - class file: cache interface
YBC/CacheException.php - class file: cache exception
YBC/Client.php - class file: main class
YBC/FileCache.php - class file: a filesystem based implementation of cache
YBC/ImagesQuery.php - class file: class for image search queries
YBC/ImagesResult.php - class file: class for image search results
YBC/NewsQuery.php - class file: class for news search queries
YBC/NewsResult.php - class file: class for news search results
YBC/NullCache.php - class file: dummy implementation of cache
YBC/Query.php - class file: query interface
YBC/ResultSet.php - class file: class for the whole result
YBC/WebQuery.php - class file: class for web search queries
YBC/WebResult.php - class file: class for web search results

Step-by-Step Usage

To initialize the client write

	$ybc = new YBC\Client(APPID);

where APPID is your BOSS AppId (see:

If you want to use the cache, instantiate a cache object and provide it to the
client constructor

	$dir = '/tmp/ybc-cache';
	$cache = new YBC\FileCache($dir);
	$ybc = new YBC\Client(APPID, $cache);

$dir must be the absolute path to an existing writable directory. By default it
is '../cache' relative to the YBC class directory. You can also use your own
caching mechanism (see: Extending)

A query is generated like this:

	$webQuery = new YBC\WebQuery('search term');
	$newsQuery = new YBC\NewsQuery('search term');
	$imagesQuery = new YBC\ImagesQuery('search term');

To determine how many result are shown and beginning from which offset, use
setLimit(), for example to retrieve the first five results (preset is 0,10):


To determine a region and language, use setLocale(), which allows different
parameters (preset is 'us-en'):

a) single key:

	$webQuery->setLocale('de'); // region 'de', language 'de'

b) combined key:

	$webQuery->setLocale('us-en'); // region 'us', language 'en'

c) class constant:

	$webQuery->setLocale(YBC\AbstractQuery::LOCALE_HONG_KONG // region 'hk', language 'tzh'

Additionaly you can enforce strict language checking with setStrictLang()


To search only selected sites, use setSites() or addSite():

	$webQuery->setSites(array('', '');

By default, the search term gets surrounded with <b>-Tags in title and
description of the result. To turn this off, use setRawStyle():


These options are available in all query objects (web, news, images). But there
are many more options for each query type, for example:

	// longer preview text:
	// include number of saves in delicious:

	// get only news from the last 2 days:
	// order news results by date:

	// get only images of wallpaper sizes:
	// deactivate filter for offensive content:

For all the options see phpDoc comments of YBC\WebQuery, YBC\ImagesQuery and

It is also useful to read the BOSS API Guide to see what is possible within BOSS

Tip: The query object has a fluent interface, you also can write something like:


After instantiating and if necessary configuring the query object you can
execute the query like so:

	$resultSet = $ybc->query($webQuery);

The returned YBC\ResultSet object is an iterator over YBC\WebResult and provides
some additional infos, for example the total number of hits and a query object
for the next page:

	$totalHits = $resultSet->getTotalhits();
	$nextQuery = $resultSet->getNextpageQuery(); 

To iterate over the results, just use foreach. The result attributes can be
accessed directly:

	foreach($resultSet as $result) {
		echo <<<EOT
	<p><a href="$result->clickurl">$result->url</a></p>

For a complete reference about the result classes see phpDoc comments of
YBC\ResultSet, YBC\WebResult, YBC\ImagesResult and YBC\NewsResult. Also -again-
it may be helpful to read the BOSS API Guide.

Now just go and try it out :-)


As mentioned above, you can easily implement your own caching mechanisms, i.e.
a MySQL based cache. Just implement the YBC\Cache interface (see YBC/Cache.php)

Note that the get() and delete() methods expect Query objects as parameters. In
the FileCache implementation a hash of the object is used as identifier, which
should work out pretty good:

	$id = md5(serialize($query));

The spl_object_hash() function is NOT appliable here because it only hashes the
object id to identify an object at runtime!
For more information send a message to info at phpclasses dot org.