search.pm

Yahoo！search API. 用于搜索引擎接口

1;
__END__

=head1 NAME

Yahoo::Search - Perl interface to the Yahoo! Search public API.

The following search spaces are supported:

=over 3

=item Doc

Common web search for documents (html, pdf, doc, ...), including Y!Q
contextual search.

=item Image

Image search (jpeg, png, gif, ...)

=item Video

Video file search (avi, mpeg, realmedia, ...)

=item News

News article search

=item Local

Yahoo! Local area (ZIP-code-based Yellow-Page like search)

=item Terms

A pseudo-search to report the important search terms from the provided
content or content+query.

=item Spell

A pseudo-search to fetch a "did you mean?" spelling suggestion for a search term.

=item Related

A pseudo-search to fetch "also try" related-searches for a search term.

=back

(Note: what this Perl API calls "Doc" Search is what Yahoo! calls "Web"
Search. But gee, aren't all web searches "Web" search, including
Image/News/Video/etc?)

Yahoo!'s raw API, which this package uses, is described at:

  http://developer.yahoo.net/

=head1 DOCS

The full documentation for this suite of classes is spread among these packages:

   Yahoo::Search
   Yahoo::Search::Request
   Yahoo::Search::Response
   Yahoo::Search::Result

However, you need C<use> only B<Yahoo::Search>, which brings in the others
as needed.

In the common case, you need read only the first and the last
(Yahoo::Search to create a query, and Yahoo::Search::Result to interpret
the results).

=head1 SYNOPSIS

Yahoo::Search provides a rich and full-featured set of classes for
accessing the various features of Yahoo! Search, and also offers a variety
of shortcuts to allow simple access, such as the following B<Doc> search:

 use Yahoo::Search;
 my @Results = Yahoo::Search->Results(Doc => "Britney latest marriage",
                                      AppId => "YahooDemo",
                                      # The following args are optional.
                                      # (Values shown are package defaults).
                                      Mode         => 'all', # all words
                                      Start        => 0,
                                      Count        => 10,
                                      Type         => 'any', # all types
                                      AllowAdult   => 0, # no porn, please
                                      AllowSimilar => 0, # no dups, please
                                      Language     => undef,
                                     );
 warn $@ if $@; # report any errors

 for my $Result (@Results)
 {
     printf "Result: #%d\n",  $Result->I + 1,
     printf "Url:%s\n",       $Result->Url;
     printf "%s\n",           $Result->ClickUrl;
     printf "Summary: %s\n",  $Result->Summary;
     printf "Title: %s\n",    $Result->Title;
     printf "In Cache: %s\n", $Result->CacheUrl;
     print "\n";
 }

The first argument to C<Results> indicates which search space is to be
queried (in this case, B<Doc>). The second argument is the search term or
phrase (described in detail in the next section). Subsequent arguments are
optional key/value pairs (described in detail in the section after that) --
the ones shown in the example are those allowed for a B<Doc> query, with
the values shown being the defaults.

C<Results> returns a list of Yahoo::Search::Result objects, one per item
(in the case of a B<Doc> search, an item is a web page, I<pdf> document,
I<doc> document, etc.). The methods available to a C<Result> object are
dependent upon the search space of the original query -- see
Yahoo::Search::Result documentation for the complete list.

=head1 Search term / phrase

Within a search phrase ("C<Britney latest marriage>" in the example
above), words that you wish to be included even if they would otherwise be
eliminated as "too common" should be proceeded with a "C<+>". Words that you
wish to exclude should be proceeded with a "C<->". Words can be separated
with "C<OR>" (the default for the C<any> Mode, described below), and can be
wrapped in double quotes to identify an exact phrase (the default with the
C<phrase> Mode, also described below).

There are also a number of "Search Meta Words", as described at
http://help.yahoo.com/help/us/ysearch/basics/basics-04.html and
http://help.yahoo.com/help/us/ysearch/tips/tips-03.html , which can stand
along or be combined with B<Doc> searches (and, to some extent, some of the
others -- YMMV):

=over 4

=item B<site:>

allows one to find all documents within a particular domain and all its
subdomains. Example: B<site:yahoo.com>

=item B<hostname:>

allows one to find all documents from a particular host only.
Example: B<hostname:autos.yahoo.comm>

=item B<link:>

allows one to find documents that link to a particular url.
Example: B<link:http://autos.yahoo.com/>

=item B<url:>

allows one to find a specific document in Yahoo!'s index.
Example: B<url:http://edit.autos.yahoo.com/repair/tree/0.html>

=item B<inurl:>

allows one to find a specific keyword as part of indexed urls.
Example: B<inurl:bulgarian>

=item B<intitle:>

allows one to find a specific keyword as part of the indexed titles.
Example: B<intitle:Bulgarian>

=back

As an example combining a number of different search styles, consider

    my @Results = Yahoo::Search->Results(Doc => 'site:TheSmokingGun.com "Michael Jackson" -arrest',
                                         AppId => "YahooDemo");

This returns data about pages at TheSmokingGun.com about Michael Jackson
that don't contain the word "arrest" (yes, there are actually a few such
pages).

=head1 Query arguments

As mentioned above, the arguments allowed in a C<Query> call depend upon
the search space of the query. Here is a table of the possible arguments,
showing which apply to queries of which search space:

                  Doc   Image  Video  News   Local  Spell Related Terms
                 -----  -----  -----  -----  -----  ----- ------- -----
  AppId           [X]    [X]    [X]    [X]    [X]    [X]    [X]    [X]
  Mode            [X]    [X]    [X]    [X]    [X]     .      .      .
  Start           [X]    [X]    [X]    [X]    [X]     .      .      .
  Count           [X]    [X]    [X]    [X]    [X]     .     [X]     .

  Context         [X]     .      .      .      .      .      .     [X]
  Country         [X]     .      .      .      .      .      .      .
  License         [X]     .      .      .      .      .      .      .
  AllowSimilar    [X]     .      .      .      .      .      .      .
  AllowAdult      [X]    [X]    [X]     .      .      .      .      .
  Type            [X]    [X]    [X]     .      .      .      .      .
  Language        [X]     .      .     [X]     .      .      .      .
  Sort             .      .      .     [X]    [X]     .      .      .
  Color            .     [X]     .      .      .      .      .      .
      .
  Lat              .      .      .      .     [X]     .      .      .
  Long             .      .      .      .     [X]     .      .      .
  Street           .      .      .      .     [X]     .      .      .
  City             .      .      .      .     [X]     .      .      .
  State            .      .      .      .     [X]     .      .      .
  PostalCode       .      .      .      .     [X]     .      .      .
  Location         .      .      .      .     [X]     .      .      .
  Radius           .      .      .      .     [X]     .      .      .

  AutoContinue    [X]    [X]    [X]    [X]    [X]     .      .      .
  Debug           [X]    [X]    [X]    [X]    [X]    [X]    [X]    [X]
  PreRequestCallback [X] [X]    [X]    [X]    [X]    [X]    [X]    [X]

Here are details of each:

=over 4

=item AppId

A 8-40 character string which identifies the application making use of the
Yahoo! Search API. (Think of it along the lines of an HTTP User-Agent
string.)

The characters allowed are space, plus C<A-Za-z0-9_()[]*+-=,.:@\>

This argument is required of all searches (sorry). You can make up whatever
AppId you'd like, but you are encouraged to register it via the link on

  http://developer.yahoo.net/

especially if you are creating something that will be widely distributed.

As mentioned below in I<Defaults and Default Overrides>, it's particularly
convenient to get the C<AppId> out of the way by putting it on the C<use>
line, e.g.

   use Yahoo::Search AppId => 'just testing';

It then applies to all queries unless explicitly overridden.

=item Mode

Must be one of: C<all> (the default), C<any>, or C<phrase>. Indicates how
multiple words in the search term are used: search for documents with
I<all> words, documents with I<any> words, or documents that contain the
search term as an exact I<phrase>.

=item Start

Indicates the ordinal of the first result to be returned, e.g. the "30" of
"showing results 30-40" (except that C<Start> is zero-based, not
one-based). The default is zero, meaning that the primary results will be
returned.

=item Count

Indicates how many items should be returned. The default is 10. The maximum
allowed depends on the search space being queried: B<20> for I<Local>
searches, and B<50> for others which support the C<Count> argument.

Note that

  Yahoo::Search::MaxCount($SearchSpace)

and

  $SearchEngine->MaxCount($SearchSpace)

return the maximum count allowed for the given C<$SearchSpace>.

=item Context

By providing a context string to a B<Doc> query, you change the request
from a normal document query to a Y!Q contextual query. Y!Q is described at

   http://yq.search.yahoo.com/

The C<Content> string can be raw text, html, etc., and is to provide the
document search more information about what kind of results are wanted.

For example, without a C<Context>, a document search for "Madonna" returns
the most popular documents (which are invariably about the famous pop
singer). However, if you provide a context string even as simple as "Virgin
Mary", the results skew away from the pop singer toward the Mother of God.
Since it's likely that a confusion between the two would be less than
optimal in pretty much every conceivable case, this is a Good Thing.

When a C<Context> is given, the query string itself may be empty. For
example, if you have the text of a blog entry in C<$BlogText>, you can
fetch "related links" via:

   use Yahoo::Search AppId => 'my blog stuff';
   my @Results = Yahoo::Search->Results(Doc => undef, Context => $BlogText);

In a B<Terms> search, C<Context> is required.

=item Country

Attempts to restrict the B<Doc> search to web servers residing in the named
country. As of this writing, the Yahoo! web services support the following
codes for C<Country>:

 code   country
 ----   ---------------
  ar    Argentina
  au    Australia
  at    Austria
  be    Belgium
  br    Brazil
  ca    Canada
  cn    China
  cz    Czech Republic
  dk    Denmark
  fi    Finland
  fr    France
  de    Germany
  it    Italy
  jp    Japan
  kr    Korea
  nl    Netherlands
  no    Norway
  pl    Poland
  rf    Russian Federation
  es    Spain
  se    Sweden
  ch    Switzerland
  tw    Taiwan
  uk    United Kingdom
  us    United States

In addition, the code "default" is the same as the lack of a country
specifier: no country-related restrictions.


The above list can be found in C<%Yahoo::Search::KnownCountry>.

Because the list of countries may be updated more often than this Perl API,
this Perl API does not attempt to restrict the C<Country> value to members
of this specific list. If you provide a C<Country> value which is not
supported by Yahoo!'s web services, a "400 Bad Request" error is returned
in C<@$>.

=item License

For C<Doc> searches, can be:

=over 10

=item C<any>

(the default) -- results are not filtered with respect to licenses

=item C<cc_any>

Only items with a Creative Commons license (of any type) are returned.
See their (horribly designed hard to find anything substantial) site at:

  http://creativecommons.org/

=item C<cc_commercial>

Only items with a Creative Commons license which allows some kind of
commercial use are returned.

=item C<cc_modifiable>

Only items with a Creative Commons license which allows modification
(e.g. derived works) of some kind are returned.

=back

You may combine the above to create an intersection, e.g.

   License => "cc_commercial+cc_modifiable"

(space, comma, or plus-separated) returns items which allow I<both> some
kind of commercial use, and their use in some kinds of derivative works.

=item AllowSimilar

If this boolean is true (the default is false), similar results which would
otherwise not be returned are included in the result set.

=item AllowAdult

If this boolean is false (the default), results considered to be "adult"
(i.e. porn) are not included in the result set. Set to true to allow
unfiltered results.

Standard precautions apply about how the "is adult?" determination is not
perfect.

=item Type

This argument can be used to restrict the results to only a specific file
type. The default value, C<any>, allows any type associated with the search
space to be returned (that is, provides no restriction). Otherwise, the
values allowed for C<Type> depend on the search space:

 Search space    Allowed Type values
 ============    ========================================================
 Doc             any  html msword pdf ppt rss txt xls
 Image           any  bmp gif jpeg png
 Video           any  avi flash mpeg msmedia quicktime realmedia
 News            N/A
 Local           N/A
 Spell           N/A
 Related         N/A
 Term            N/A

(Deprecated: you may use C<all> in place of C<any>)

=item Language

If provided, attempts to restrict the results to documents in the given
language. The value is an language code such as C<en> (English), C<ja>
(Japanese), etc (mostly ISO 639-1 codes). As of this writing, the following
codes are supported:

 code  language
 ----  ---------
  sq   Albanian
  ar   Arabic
  bg   Bulgarian
  ca   Catalan
  szh  Chinese (simplified)
  tzh  Chinese (traditional)
  hr   Croatian
  cs   Czech
  da   Danish
  nl   Dutch
  en   English
  et   Estonian
  fi   Finnish
  fr   French
  de   German
  el   Greek
  he   Hebrew
  hu   Hungarian
  is   Icelandic
  it   Italian
  ja   Japanese
  ko   Korean
  lv   Latvian
  lt   Lithuanian
  no   Norwegian
  fa   Persian
  pl   Polish
  pt   Portuguese
  ro   Romanian
  ru   Russian
  sk   Slovak
  sl   Slovenian
  es   Spanish
  sv   Swedish
  th   Thai
  tr   Turkish

In addition, the code "default" is the same as the lack of a language
specifier, and seems to mean a mix of major world languages, skewed toward
English.

The above list can be found in C<%Yahoo::Search::KnownLanguage>.

Because the list of languages may be updated more often than this Perl API,
this Perl API does not attempt to restrict the C<Language> value to members
of this specific list. If you provide a C<Language> value which is not
supported by Yahoo!'s web services, a "400 Bad Request" error is returned
in C<@$>.

=item Sort

For B<News> searches, C<sort> may be C<rank> (the default) or C<date>.

For B<Local> searches, C<sort> may be C<relevance> (the default; most
relevant first), C<distance> (closest first), C<rating> (highest rating
first), or C<title> (alphabetic sort).

=item Color

For B<Image> searches, may be C<any> (the default), C<color>, or C<bw>:

=over 10

=item C<any>

No filtering based on colorization or lack thereof

=item C<color>

Only images with color are returned

=item C<bw>

Only black & white / grayscale images are returned

=back

=item Lat

=item Long

=item Street

=item City

=item State

=item PostalCode

=item Location

These items are for a B<Local> query, and specify the epicenter of the
search. The epicenter must be provided in one of a variety of ways:

=over 3

=item *

via C<Lat> and C<Long>

=item *

via the free-text C<Location>

=item *

via C<Street> and C<PostalCode>

=item *

via C<Street> and C<City> and C<State>

=item *

via C<PostalCode> alone

=item *

via C<City> and C<State> alone.

=back

The list above is the order of precedence for when multiple fields are sent
(e.g. if a C<Lat> and C<Long> are sent, they are used regardless of
whether, say, a C<PostalCode> is used), but it's probably best to send
exactly only the fields you wish to be used.

C<Lat> and C<Long> are floating point numbers, such as this example: