Mohammad S Anwar

NAME

WWW::Google::CustomSearch - Interface to Google JSON/Atom Custom Search.

VERSION

Version 0.06

DESCRIPTION

This module is intended for anyone who wants to write applications that can interact with the JSON/Atom Custom Search API. With Google Custom Search, you can harness the power of Google to create a customized search experience for your own website. You can use the JSON/Atom Custom Search API to retrieve Google Custom Search results programmatically.

The JSON / Atom Custom Search API requires the use of an API key, which you can get from the Google APIs console. The API provides 100 search queries per day for free. If you need more, you may sign up for billing in the console.

Important:The version v1 of the Google JSON/Atom Custom Search API is in Labs and its features might change unexpectedly until it graduates.

LANGUAGES (lr)

    +----------------------+------------+
    | Language             | Value      |
    +----------------------+------------+
    | Arabic               | lang_ar    | 
    | Bulgarian            | lang_bg    |
    | Catalan              | lang_ca    |
    | Chinese (Simplified) | lang_zh-CN |
    | Chinese (Traditional)| lang_zh-TW |
    | Croatian             | lang_hr    |
    | Czech                | lang_cs    |
    | Danish               | lang_da    |
    | Dutch                | lang_nl    |
    | English              | lang_en    |
    | Estonian             | lang_et    |
    | Finnish              | lang_fi    |
    | French               | lang_fr    |
    | German               | lang_de    |
    | Greek                | lang_el    |
    | Hebrew               | lang_iw    |
    | Hungarian            | lang_hu    |
    | Icelandic            | lang_is    |
    | Indonesian           | lang_id    |
    | Italian              | lang_it    |
    | Japanese             | lang_ja    |
    | Korean               | lang_ko    | 
    | Latvian              | lang_lv    |
    | Lithuanian           | lang_lt    |
    | Norwegian            | lang_no    |
    | Polish               | lang_pl    |
    | Portuguese           | lang_pt    |
    | Romanian             | lang_ro    |
    | Russian              | lang_ru    |
    | Serbian              | lang_sr    |
    | Slovak               | lang_sk    |
    | Slovenian            | lang_sl    |
    | Spanish              | lang_es    |
    | Swedish              | lang_sv    |
    | Turkish              | lang_tr    |
    +----------------------+------------+

CONSTRUCTOR

The constructor expects your application API Key & Custom search engine identifier. Use either cx or cref to specify the custom search engine you want to perform this search. If both are specified, cx is used.

    +-------------+------------------------------------------------------------------+
    | Key         | Description                                                      |
    +-------------+------------------------------------------------------------------+
    | api_key     | Your application API Key.                                        | 
    |             |                                                                  |
    | alt         | Alternative data representation format. If you don't specify an  |
    |             | alt parameter, the API returns data in the JSON format. This is  |
    |             | equivalent to alt=json. Accepted values are json and atom.       |
    |             |                                                                  |
    | cx          | For a search engine created with the Google Custom Search page.  |
    |             |                                                                  |
    | cref        | For a linked custom search engine.                               |
    |             |                                                                  |
    | lr          | The language restriction for the search results.                 |
    |             |                                                                  |
    | num         | Number of search results to return. Valid values are integers    |
    |             | between 1 and 10, Default is 10.                                 |
    |             |                                                                  |
    | prettyprint | Returns a response with indentations and line breaks.            |  
    |             | If prettyprint=true, the results returned by the server will be  |
    |             | human readable (pretty printed).                                 |
    |             |                                                                  |
    | safe        | Search safety level. Default is off. Possible values are:        |
    |             | * high - enables highest level of safe search filtering.         |
    |             | * medium - enables moderate safe search filtering.               |
    |             | * off - disables safe search filtering.                          |
    |             |                                                                  |
    | start       | The index of the first result to return.Valid values are between |
    |             | 1 and 91. Default is 1.                                          |
    |             |                                                                  |
    | filter      | Controls turning on or off the duplicate content filter.         |
    |             | * filter=0 - Turns off the duplicate content filter.             |
    |             | * filter=1 - Turns on the duplicate content filter (default).    |  
    +-------------+------------------------------------------------------------------+

METHODS

Get search result for the given query.

    use strict; use warnings;
    use Data::Dumper;
    use WWW::Google::CustomSearch;
    
    my $api_key = 'Your_API_Key';
    my $cx      = 'Search_Engine_Identifier';

    # Most recommended format to use key, value as mentioned below format which  gives
    # flexibility to play with query parameters.
    my $engine1 = WWW::Google::CustomSearch->new(api_key=>$api_key, cx=>$cx, start=>2);
    print Dumper($engine1->search('Google'));

    # NOTE: If you intend to use default settings  for  search engine created with the 
    # Google Custom Search then use this format.
    my $engine2 = WWW::Google::CustomSearch->new($api_key, $cx);
    print Dumper($engine2->search('Google'));

AUTHOR

Mohammad S Anwar, <mohammad.anwar at yahoo.com>

BUGS

Please report any bugs or feature requests to bug-www-google-customsearch at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Google-CustomSearch. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WWW::Google::CustomSearch

You can also look for information at:

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

DISCLAIMER

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.