Bing::Search - Implements the Bing AJAX Search API

Bing-Search documentation Contained in the Bing-Search distribution.

Index

Code Index:

NAME

Top

Bing::Search - Implements the Bing AJAX Search API

SYNOPSIS

Top

    use Bing::Search;
    use Bing::Search::Source::Web;

    my $search = Bing::Search->new(
      AppId => '1234567890',
      Query => 'Rocks'
    );

    my $source = Bing::Search::Source::Web->new();

    $search->add_source( $source );

    my $response = $search->search();

    print $_->Url for @{$response->results};

DESCRIPTION

Top

This set of modules implements most of the Bing Search API. See the "UNIMPLEMENTED BITS" for what's missing. This is an object-oriented monstrosity, intended to be easily extendible when the API changes. Since we all know who made Bing, we know that's going to change.

Really Important Note

The Bing API requires an AppId. If you intend to use the API, you must provide an AppId. You may obtain one by visiting http://www.bing.com/developers/createapp.aspx. Please ensure you've read the terms and whatnot.

The Quick And Easy Way

First, create a search object.

    my $search = Bing::Search->new();

And give it your AppId. (See "Really Important Note")

    $search->AppId('1234567890');

You almost always need to be searching for something, so:

    $search->Query('rocks');

Finally, Bing needs to know where to look for your rocks. This is done by supplying a Source object. You can add more than one type, but try not to add the same type more than once. Poor Bing gets confused.

    $search->add_source( 
      Bing::Search::Source::Web->new
    );

Once that's done, you're ready to wander out into the wilds of the internet and do your search.

    my $response = $search->search();

You may have to wait a second. Sometimes the internet is slow. But now, you're ready to examine your results.



    foreach my $result ( @{$response->results} ) { 
      print $result->Title, " -> ", $result->Url, "\n";
    }

METHODS

Top

search

Does the actual searching. Any parameters are ignored. Returns a Bing::Search::Response object.

AppId

Required. Sets the AppId.

Query

Sets the query string.

add_source

Accepts a Bing::Search::Source object, adds it to the list of sources.

There are also some methods that you probably don't want to fiddle with. In fact, fiddling with them might break something. Don't do it, man!

sources

An arrayref of Bing::Search::Source::* objects. Try not to change this yourself.

request_obj

A URI object. This is what ends up getting sent out over the internet. Careful, it changes a lot when you're not looking.

agent

A LWP::UserAgent object. Used to make the request. This has a default agent string of "bing-search/$VERSION libwww-perl"

_parse_json

As with all methods beginning with _, don't fiddle with it. It does what it says on the tin.

_make_uri

Called by search to generate the URI object and fiddle with the query string. Again, what it says on the tin.

SOURCES

Top

Bing::Search::Source objects what what tell Bing what sort of things to look for. The return value of the search method is a Bing::Search::Response object, which among other things contains some Bing::Search::Result objects. The sources you specifiy determine what results you'll end up with.

Sources currently implemented:

Bing::Search::Source::Image, Bing::Search::Source::InstantAnswer, Bing::Search::Source::MobileWeb, Bing::Search::Source::News, Bing::Search::Source::Phonebook, Bing::Search::Source::RelatedSearch, Bing::Search::Source::Spell, Bing::Search::Source::Translation, Bing::Search::Source::Video, Bing::Search::Source::Web

You should consult the documentation for each source you intend on using, as some have various options you may find useful. Some, like Bing::Search::Source::Translation have some required options you must set.

Attributes Available to All Sources

There are some attributes available to every source. Which each Source may not implement each of the below, this is a key-saving technique.

Market

The market the search is to take place in. See http://msdn.microsoft.com/en-us/library/dd251064.aspx for details about valid markets. Bing will attempt to select the correct market automatically if none is provided.

Version

The version of the API you wish to use. The default is "2.1".

Adult

Indicates how to filter "adult" content. Per http://msdn.microsoft.com/en-us/library/dd251007.aspx, valid options are: "Off", "Moderate", and "Strict".

UILanguage

The langauge in which "user interface strings" are presented. In most cases, this will not have affect your results or use of this module.

Valid language codes are available here: http://msdn.microsoft.com/en-us/library/dd250941.aspx.

Latitude

Latitude for searches where location is relevant. Valid values are between -90 and 90.

Longitude

Similar to the Latitude option. vcalud values are between -180 and 180.

Radius

For searches where a radius (for a location-based search) are relevant. Valid values are from 0 to 250 miles. The default value is 5.

Options

Options is a strange beast, in that there are several "options" that may be set or removed. While you may set this directly (it is an arrayref), it's suggested that you use the handy function written up nicely for you, setOptions.

Valid values are: DisableLocationDetection and EnableHilighting. You almost never need to set either of these.

setOptions

Accepts a single parameter, the name of an option. Optionally prefixed with a -, it will remove the option from the list. For consistency's sake, prefixing an option with + will add the option to the list. + is not required to add an option.

RESULTS

Top

Bing::Search::Result objects are what you've been looking for. They contain the well-parsed data from your query. To determine what methods are available to you, you should check each object's type. I suggest using the built-in ref function.

A notable exception is the Bing::Search::Result::Errors result. It occurs whenever Bing spits out an error of some sort. Remember to check for it if things aren't doing what you think they should.

Currently implemented Results:

Bing::Search::Result::Errors, Bing::Search::Result::Image, Bing::Search::Result::Image::Thumbnail, Bing::Search::Result::MobileWeb, Bing::Search::Result::InstantAnswer, Bing::Search::Result::InstantAnswer::Encarta, Bing::Search::Result::InstantAnswer::FlighStatus, Bing::Search::Result::News, Bing::Search::Result::Phonebook, Bing::Search::Result::RelatedSearch, Bing::Search::Result::Spell, Bing::Search::Result::Translation, Bing::Search::Result::Video, Bing::Search::Result::Video::StaticThumbnail, Bing::Search::Result::Web

UNIMPLEMENTED BITS

Top

I got lazy and opted to not bother implementing a few small bits of the API, mostly because I got distracted by video games or a shiny piece of metal. Future versions, if I ever get around to it, may have these bits implemented.

Also, patches welcome.

Currently unimplemented

The AdSource Source is not implemented. This is a design decision.
In the Video and Image's Filter sections, the custom Height and Width fitlers are not implemented. The pre-defined filters remain.

BUGS

Top

Oh yeah. And I bet these docs are full of typos and other broken things, too. I dare you to find them! Patches welcome.

SEE ALSO

Top

Moose, URI, LWP::UserAgent, DateTime, DatTime::Duration, JSON

AUTHOR

Top

Dave Houston, dhouston@cpan.org, 2010

CONTRIBUTORS

Top

Peter Edwards peter@dragonstaff.co.uk

LICENSE

Top

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.

Bing-Search documentation Contained in the Bing-Search distribution. 
package Bing::Search;
use Moose 1.00;
use URI 1.54;
use URI::QueryParam;
use Carp;
use LWP::UserAgent 5.835;
use JSON 2.21;
use Bing::Search::Response;
use vars qw($VERSION);

$VERSION = "0.0003";
$VERSION = eval $VERSION if $VERSION =~ /_/;

has 'sources' => ( 
   is => 'rw',
   isa => 'ArrayRef[Bing::Search::Source]',
   predicate => 'has_sources',
   default => sub { [] }
);

has 'request_obj' => ( 
   is => 'rw',
   isa => 'URI'
);

has 'agent' => ( 
   is => 'rw',
   isa => 'LWP::UserAgent',
   default => sub {  
      LWP::UserAgent->new( agent => 'bing-search/' . $VERSION . ' libwww-perl' ) 
   }
);

has 'AppId' => ( 
   is => 'rw',
   required => 1,
   default => 'NOAPPIDPROVIDED'
);

has 'Query' => ( 
   is => 'rw',
   isa => 'Str',
   default => ''
);

has 'response' => (
   is => 'rw',
   isa => 'Bing::Search::Response'
);


sub search { 
   my $self = shift;
   my $uri;
   if( @_ ) {
      $self->add_source( { source => 'Web' } );
      $self->Query( shift @_ );
   } 
   $self->_make_uri;
   $self->agent->env_proxy;
   $uri = $self->request_obj();
   my $response = $self->agent->get( $uri );
   unless( $response->is_success ) { 
      croak "Failed request: $!";
   }
   
   my $j = JSON->new->decode( $response->content );
   $self->_parse_json( $j );
}

sub _parse_json {
   # Debugging!
   use Data::Dumper;
   my( $self, $json ) = @_;
   my $resp = Bing::Search::Response->new( data => $json );
   $self->response( $resp  );
}

sub _make_uri { 
   my ($self) = @_;
   unless( $self->has_sources ) { 
      croak "No sources means no query, yo.";
   }
   my $uri = URI->new( 'http://api.bing.net/json.aspx' );
   my @source_names;
   for my $source ( @{$self->sources} ) {
      my $req = $source->build_request;
      for my $source_key ( keys %$req ) {
         if( ref $req->{$source_key} eq 'ARRAY' ) { 
            $uri->query_param_append( $source_key => $_ ) for @{$req->{$source_key}};
         } else { 
            $uri->query_param_append( $source_key => $req->{$source_key} );
         }
      }
      push @source_names, $source->source_name;
   }
   $uri->query_param_append( 'Sources' => @source_names );
   $uri->query_param_append( 'AppId' => $self->AppId );
   $uri->query_param_append( 'Query' => $self->Query );
   $self->request_obj( $uri );
}

sub add_source { 
   my( $self, $source ) = @_;
   unless( $source->isa('Bing::Search::Source') ) { 
      croak "Not a valid source: $source";
   }
   my $source_list = $self->sources;
   push @$source_list, $source;
   $self->sources( $source_list );
}


__PACKAGE__->meta->make_immutable;