NAME

VERSION

version 1.11.3 Yahoo::Search::Response -- Container object for the result set of one query to the Yahoo! Search API. (This package is included in, and automatically loaded by, the Yahoo::Search package.)

Package Use

You never need to use this package directly -- it is loaded automatically by Yahoo::Search.

Object Creation

Response objects are created by the Fetch() method of a Request (Yahoo::Search::Request) object, e.g. by

  my $Response = Yahoo::Search->new(...)->Request()->Fetch();

or by shortcuts to the same, such as:

  my $Response = Yahoo::Search->Query(...);

Methods

A Response object has the following methods:

$Response->Count()

Returns the number of Result objects available in this Response. See Yahoo::Search::Result for details on Result objects.

$Response->FirstOrdinal([ separator ])

Returns the index of the first Result object (e.g. the "30" of results 30 through 40 out of 5,329). This is the same as the Start arg of the Request that generated this Response.

If an optional argument is given and is true, it is used as a separator every three digits. In the US, one would use

   $Response->FirstOrdinal(',')

to return, say, "1,230" instead of the "1230" that

   $Response->FirstOrdinal()

might return.

$Response->CountAvail([ separator ])

Returns an approximate number of total search results available, were you to ask for them all (e.g. the "5329" of the results 30 through 40 out of 5329).

If an optional argument is given and is true, it is used as a separator every three digits. In the US, one would use

   $Response->CountAvail(',')

to return, say, "5,329" instead of the "5329" that

   $Response->CountAvail()

might return.

$Response->Links()

Returns a list of links from the response (one link per result):

  use Yahoo::Search;
  if (my $Response = Yahoo::Search->Query(Doc => 'Britney'))
  {
      for my $link ($Response->Links) {
          print "<br>$link\n";
      }
  }

This prints one

  <br><a href="...">title of the link</a>

line per result returned from the query.

(Not appropriate for Spell and Related search results)

$Response->Terms()

(Appropriate for Spell and Related search results)

Returns a list of text terms.

$Response->Results()

Returns a list of Yahoo::Search::Result Result objects representing all the results held in this Response. For example:

  use Yahoo::Search;
  if (my $Response = Yahoo::Search->Query(Doc => 'Britney'))
  {
      for my $Result ($Response->Results) {
         printf "%d: %s\n", $Result->I, $Result->Url;
      }
  }

This is not valid for Spell and Related searches.

$Response->NextResult(options)

Returns a Result object, or nothing. (On error, returns nothing and sets $@.)

The first time NextResult is called for a given Response object, it returns the Result object for the first result in the set. Returns subsequent Result objects for subsequent calls, until there are none left, at which point what is returned depends upon whether the auto-continuation feature is turned on (more on that in a moment).

The following produces the same results as the Results() example above:

 use Yahoo::Search;
 if (my $Response = Yahoo::Search->Query(Doc => 'Britney')) {
     while (my $Result = $Response->NextResult) {
         printf "%d: %s\n", $Result->I, $Result->Url;
     }
 }

Auto-Continuation

If auto-continuation is turned on, then upon reaching the end of the result set, NextResult automatically fetches the next set of results and returns its first result.

This can be convenient, but can be very dangerous, as it means that a loop which calls NextResult, unless otherwise exited, will fetch results from Yahoo! until there are no more results for the query, or until you have exhausted your access limits.

Auto-continuation can be turned on in several ways:

• On a per NextResult basis by calling as

   $Response->NextResult(AutoContinue => 1)

  as with this example

   use Yahoo::Search;
   ##
   ## WARNING:   DANGEROUS DANGEROUS DANGEROUS
   ##
   if (my $Response = Yahoo::Search->Query(Doc => 'Britney')) {
       while (my $Result = $Response->NextResult(AutoContinue => 1)) {
           printf "%d: %s\n", $Result->I, $Result->Url;
       }
   }

• By using

    AutoContinue => 1

  when creating the request (e.g. in a Yahoo::Search->Query call), as with this example:

   use Yahoo::Search;
   ##
   ## WARNING:   DANGEROUS DANGEROUS DANGEROUS
   ##
   if (my $Response = Yahoo::Search->Query(Doc => 'Britney',
                                                AutoContinue => 1))
   {
       while (my $Result = $Response->NextResult) {
          printf "%d: %s\n", $Result->I, $Result->Url;
       }
   }

• By creating a query via a search-engine object created with

    AutoContinue => 1

  as with this example:

   use Yahoo::Search;
   ##
   ## WARNING:   DANGEROUS DANGEROUS DANGEROUS
   ##
   my $SearchEngine = Yahoo::Search->new(AutoContinue => 1);
  
   if (my $Response = $SearchEngine->Query(Doc => 'Britney')) {
       while (my $Result = $Response->NextResult) {
          printf "%d: %s\n", $Result->I, $Result->Url;
       }
   }

• By creating a query when Yahoo::Search had been loaded via:

   use Yahoo::Search AutoContinue => 1;

  as with this example:

   use Yahoo::Search AutoContinue => 1;
   ##
   ## WARNING:   DANGEROUS DANGEROUS DANGEROUS
   ##
   if (my $Response = Yahoo::Search->Query(Doc => 'Britney')) {
       while (my $Result = $Response->NextResult) {
           printf "%d: %s\n", $Result->I, $Result->Url;
       }
   }

All these examples are dangerous because they loop through results, fetching more and more, until either all results that Yahoo! has for the query at hand have been fetched, or the Yahoo! Search server access limits have been reached and further access is denied. So, be sure to rate-limit the accesses, or explicitly break out of the loop at some appropriate point.

$Response->Reset()

Rests the iterator so that the next NextResult returns the first of the Response object's Result objects.

$Response->Request()

Returns the Request object from which this Response object was derived.

$Response->NextRequest()

Returns a Request object which will fetch the subsequent set of results (e.g. if the current Response object represents the first 10 query results, NextRequest() returns a Request object that represents a query for the next 10 results.)

Returns nothing if there were no results in the current Response object (thereby eliminating the possibility of there being a next result set). On error, sets $@ and returns nothing.

$Response->NextResponse()

Like NextRequest, but goes ahead and calls the Request object's Fetch method to return the Result object for the next set of results.

$Response->Uri()

Returns the URI::http object that was fetched to create this response. It is the same as:

  $Response->Request->Uri()

$Response->Url()

Returns the url that was fetched to create this response. It is the same as:

  $Response->Request->Url()

$Response->RawXml()

Returns a string holding the raw xml returned from the Yahoo! Search servers.

$Response->MapUrl()

Valid only for a Local search, returns a url to a map showing all results. (This is the same as each Result object's AllMapUrl method.)

$Response->RelatedRequest

$Response->RelatedResponse

Perform a Related request for search terms related to the query phrase of the current request, returning the new Request or Response object, respectively.

Both return nothing if the current request is already for a Related search.

For example:

  print "Did you mean ", join(" or ", $Response->RelatedResponse->Terms()), "?";

$Response->SpellRequest

$Response->SpellResponse

Perform a Spell request for a search term that may reflect proper spelling of the query phrase of the current request, returning the new Request or Response object, respectively.

Both return nothing if the current request is already for a Spell search.

Author

Jeffrey Friedl (jfriedl@yahoo.com)