PHP Classes
elePHPant
Icontem

Yahoo Search API Client (BOSS): Perform Web searches using the Yahoo BOSS API

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Info   View files View files (20)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings  
2010-10-14 (4 years ago) RSS 2.0 feedNot enough user ratingsTotal: 748 This week: 2All time: 4,195 This week: 602Up
Version License PHP version Categories  
ybc 1.0BSD License5.3PHP 5, Searching, Cache, Web services
Description Author  

This package can be used to perform Web searches using the Yahoo BOSS (Build your Own Search Service) API.

It can send HTTP requests to the Yahoo BOSS API Web server to perform searches for Web pages, images and news.

The class can cache the results in local files to avoid the overhead of sending requests to perform previously made searches.

Picture of Fabian Schmengler
Name: Fabian Schmengler is available for providing paid consulting. Contact Fabian Schmengler .
Classes: 6 packages by
Country: Germany Germany
Age: 32
All time rank: 109071 in Germany Germany
Week rank: 262 Up9 in Germany Germany Up
Innovation award
Innovation award
Nominee: 4x

Details provided by the author  
+-----------------------------------------------------------------------------+
|                            Yahoo BOSS Client                                |
+-----------------------------------------------------------------------------+

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

Synopsis
--------
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.


Requirements
------------
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:

	http://developer.yahoo.com/boss


Files
-----
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: http://developer.yahoo.com/boss)

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):

	$webQuery->setLimit(0,5);

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()

	$webQuery->setStrictLang(true);

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

	$webQuery->setSites(array('github.com', 'phpclasses.org');
	$webQuery->addSite('sgh-it.eu');

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

	$webQuery->setRawStyle(true);

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:
	$webQuery->setLongAbstract(true);
	// include number of saves in delicious:
	$webQuery->setDeliciousSavesView(true);

	// get only news from the last 2 days:
	$newsQuery->setAge('2d');
	// order news results by date:
	$newsQuery->setOrderBy(YBC\NewsQuery::ORDERBY_DATE);

	// get only images of wallpaper sizes:
	$imagesQuery->setDimensions(YBC\ImagesQuery::DIMENSIONS_WALLPAPER);
	// deactivate filter for offensive content:
	$imagesQuery->setFilter(false);

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

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

	http://developer.yahoo.com/search/boss/boss_guide/index.html

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

	$webQuery->setLimit(10,10)->setLongAbstract(true);

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
<div>
	<h2>$result->title</h2>
	<p>$result->abstract</p>
	<p><a href="$result->clickurl">$result->url</a></p>
	<p>$result->date</p>
</div>
EOT;
	}

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.

	http://developer.yahoo.com/search/boss/boss_guide/index.html

Now just go and try it out :-)


Extending
---------

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!
  Files folder image Files  
File Role Description
Files folder imageYBC (15 files)
Files folder imagecache (1 file)
Plain text file LICENSE.TXT Lic. BSD License
Accessible without login Plain text file README.TXT Doc. Documentation
Accessible without login Plain text file example.php Example simple demonstration
Plain text file YBC.lib.php Aux. library loader, include this file to use the package

  Files folder image Files  /  YBC  
File Role Description
  Plain text file Client.php Class Main class
  Plain text file AbstractQuery.php Class base class for queries
  Plain text file AbstractResult.php Class base class for result
  Plain text file Cache.php Class cache interface
  Plain text file CacheException.php Class cache exception
  Plain text file FileCache.php Class a filesystem based implementation of cache
  Plain text file ImagesQuery.php Class class for image search queries
  Plain text file ImagesResult.php Class class for image search results
  Plain text file NewsQuery.php Class class for news search queries
  Plain text file NewsResult.php Class class for news search results
  Plain text file NullCache.php Class dummy implementation of cache
  Plain text file Query.php Class query interface
  Plain text file ResultSet.php Class class for the whole result
  Plain text file WebQuery.php Class class for web search queries
  Plain text file WebResult.php Class class for web search results

  Files folder image Files  /  cache  
File Role Description
  Plain text file EMPTY Data make this directory writeable for php

 Version Control Unique User Downloads Download Rankings  
 0%Total:748All time:4,195
 This week:2This week:602Up