Manual

Interface to the Yahoo! Search API. The package provides an object oriented model to communicate with Yahoo's services via their REST-based XML interface.

Introduction

Introduction – Introduction to Services_Yahoo

Overview

The package provides an object oriented model to communicate with Yahoo's web services via their REST-based XML interface.

Currently the package only supports the Yahoo! Search Web Services, which is natural because Yahoo! does not expose other services via their API at the moment. Due to the modular layout of the package it is easy to add support for other services at a later point though. More information about the design of the package is available in a separate section.

Setup

Requirements

Services_Yahoo requires PHP 5 and a bunch of PEAR packages. For a complete list of dependencies please see the download page.

Installation

The Services_Yahoo package can be installed using the PEAR installer command pear install Services_Yahoo. If the installation fails due to missing dependencies, one either needs to install them manually or can make the installer fetch all dependencies automatically: pear install -a Services_Yahoo.

Alternative installation methods for situations where one has no access to the pear installer command can be found in the general installation chapter.

Uninstallation

Uninstalling the package can be done with pear uninstall Services_Yahoo.

Examples

Examples – Using Services_Yahoo

About the examples

The following sections provide you with examples of using the different feature sets of Services_Yahoo. Currently this includes documentation for the interfaces to Yahoo! Search and Content Analysis.

All public methods in Services_Yahoo have in common that exceptions will be raised when something goes wrong. This is why try { ... } catch { } blocks are wrapped around all examples.

The examples are designed to be run from a command line shell. If you would like to test them in a web browser you should replace \n with <br /> for better readability.

Speaking to Yahoo! Search

The following examples will communicate with Yahoo! Search.

Web search: Listing results

This snippet issues a search query for the term Steve Fossett to Yahoo! Search. For each result in the returned result set the title is printed.

<?php
require_once "Services/Yahoo/Search.php";

try {
    $client = Services_Yahoo_Search::factory("web");
    $results = $client->searchFor("Steve Fossett");

    echo "Number of results: " . $results->getTotalResultsReturned() . "\n\n";

    foreach ($results as $result) {
        echo $result['Title'] . "\n";
    }

} catch (Services_Yahoo_Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";

    foreach ($e->getErrors() as $error) {
        echo "* " . $error . "\n";
    }
}
?>

By default 10 results are returned per request. This number can be modified using the method setResultNumber():

<?php
require_once "Services/Yahoo/Search.php";

try {
    $client = Services_Yahoo_Search::factory("web");

    // Get 20 results per query
    $results = $client->withResults(20)->searchFor("Steve Fossett");

    /* ... */
?>

Web search: Result details

This code again queries Yahoo! Search for Steve Fossett, but this time the details of the first result in the result set are printed.

<?php
require_once "Services/Yahoo/Search.php";

try {
    $client = Services_Yahoo_Search::factory("web");
    $results = $client->searchFor("Steve Fossett");

    if ($results->getTotalResultsReturned() > 0) {
        $info = $results->current();

        echo "Title: " . $info['Title'] . "\n";
        echo "Summary: " . $info['Summary'] . "\n";
        echo "URL: " . $info['Url'] . "\n";
        echo "clickable URL: " . $info['ClickUrl'] . "\n";
        echo "Modification date: " . $info['ModificationDate'] . "\n";
        echo "Mime type: " . $info['MimeType'] . "\n";
    }
    
} catch (Services_Yahoo_Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";

    foreach ($e->getErrors() as $error) {
        echo "* " . $error . "\n";
    }
}
?>

Web search: Paginating results

In this example the "paginating" capabilities of Services_Yahoo are shown. Paginating means that the search results are split up into chunks of e.g. 20, which are displayed together with links to jump back and forth to other result chunks. Basically this mimicks the functionality from the bottom of official Yahoo Search Page.

TBD

In order to query the Image, News, Video or Local search, one only needs to replace the argument "web" in the call of the factory() method with one of "image", "news", "video", or "local".

Using the Yahoo! Content Analysis services

The following examples will show you how to use the Content Analysis Services provided by Yahoo!.

Term Extraction Service

The Term Extraction service provides a list of significant words or phrases extracted from a larger content.

<?php
require_once "Services/Yahoo/ContentAnalysis.php";

try {
    $search = Services_Yahoo_ContentAnalysis::factory("termExtraction");
    $search->setContext("Italian sculptors and painters of the "
        . "renaissance favored the Virgin Mary for inspiration.");
    $search->setQuery("madonna");

    $results = $search->submit();

    foreach ($results as $result) {
        echo $result . "\n";
    }

} catch (Services_Yahoo_Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";

    foreach ($e->getErrors() as $error) {
        echo "* " . $error . "\n";
    }
}
?>

It is possible to skip the call to setQuery(). The parameter set by this method is intended to help the engine with the extraction process, but it is not stricly required.

Spelling Suggestion Service

The Spelling Suggestion service provides a suggested spelling correction for a given term.

The following code queries Yahoo for a spelling suggestion for the term "madnna". The service will return exactly one result, but currently there is no way to avoid looping through the $results.

<?php
require_once "Services/Yahoo/ContentAnalysis.php";

try {
    $search = Services_Yahoo_ContentAnalysis::factory("spellingSuggestion");
    $search->setQuery("madnna");

    $results = $search->submit();

    foreach ($results as $result) {
        echo $result . "\n";
    }
} catch (Services_Yahoo_Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";

    foreach ($e->getErrors() as $error) {
        echo "* " . $error . "\n";
    }
}
?>

Design

Design – Services_Yahoo's design

Overview

Services_Yahoo is split up into chunks that group similar functionality. Currently there are chunks for the interfaces to Yahoo Search and to the Content Analysis functions.

Each chunk basically contains two top-level element in the source tree: A .php file and a directory that holds the implementation of the chunk. The file is a class that contains only one method which implements that factory pattern. This method dynamically loads the right file from the related directory and returns an instance of the class that implements the desired function.

Due to this modular layout Services_Yahoo can easily be extended when Yahoo adds new functions to their API.

More information

If you would like to study the code of the package, you can do so by either downloading a release from the package homepage or by browsing the code in SVN.

Also the automatically generated API documentation should help you.