# perldoc > WWW::Search

---
type: CommandReference
command: WWW::Search
mode: perldoc
section: ""
source: perldoc
---

## Quick Reference
- `my $oSearch = new WWW::Search('AltaVista');` — Create a search object for a specific engine.
- `$oSearch->native_query(WWW::Search::escape_query($sQuery));` — Set a query with escaped parameters.
- `while (my $oResult = $oSearch->next_result()) { ... }` — Iterate over results.
- `$oSearch->maximum_to_retrieve(100);` — Limit the number of returned results.
- `$oSearch->cookie_jar('/tmp/cookies');` — Use a cookie file for session persistence.
- `$oSearch->env_proxy('yes');` — Enable proxy from environment variables.
- `my @engines = WWW::Search::installed_engines();` — List all installed backend modules.
- `$oSearch->response->is_success` — Check if the last HTTP request was successful.

## Name
Virtual base class for WWW searches

## Synopsis
perl
use WWW::Search;
my $oSearch = new WWW::Search($sEngine);
## Methods

### Constructor
- `new($engine_name)` — Creates a new search object for the named backend. Defaults to `Null::Empty` if no engine given.

### Query Setup
- `native_query($escaped_query, \%options)` — Set the query string and optional options. The query must be pre‑escaped with `escape_query()`. Does not start the search.
- `gui_query($query)` — Perform a query with default engine options, as if typed by a user. Supported by few backends.
- `escape_query($string)` — (function) Escape a string for use in a URL. Non‑alphanumerics are percent‑encoded, spaces become `+`.
- `unescape_query($escaped_string)` — (function) Reverse of `escape_query()`.
- `strip_tags($html_string)` — (function) Remove HTML tags from a string; used by backends when populating result fields.

### Result Retrieval
- `next_result()` — Return the next `WWW::SearchResult` object, or `undef` when no more results.
- `results()` — Fetch all results as a list of `WWW::SearchResult` objects. May take time because it internally requests all pages.
- `seek_result($index)` — Set the next result to be returned by `next_result()`. Index 0 replays from the beginning.
- `approximate_result_count()` / `approximate_hit_count()` — Return the engine‑reported total hit count, or `undef` if not available.
- `maximum_to_retrieve($n)` / `maximum_to_return($n)` — Limit the number of results that will be fetched. Default 500.
- `response()` — Returns the `HTTP::Response` object for the most recent query.

### Proxy & Authentication
- `env_proxy($bool)` — Enable/disable reading proxy and authentication from environment variables `http_proxy`, `http_proxy_user`, `http_proxy_pwd`.
- `http_proxy($scheme, $proxy_url)` — Set an HTTP proxy.
- `http_proxy_user($user)` / `http_proxy_pwd($pwd)` — Get/set proxy authentication credentials.
- `login($user, $password)` — Return true if login to the search engine succeeded.
- `logout()` — Log out from the search engine.

### Configuration
- `cookie_jar($filename_or_object)` — Set a cookie jar (file path or `HTTP::Cookies` object). Without arguments returns the current jar.
- `date_from($date)` / `date_to($date)` — Limit query by date range (backend dependent).
- `timeout($seconds)` — Maximum duration for any part of a query, in seconds. Default 60.
- `user_agent()` — Returns the `LWP::UserAgent` (or `LWP::RobotUA`) object. Set `agent_name()` and `agent_email()` before calling.
- `agent_name($name)` — Set the User‑Agent string.
- `agent_email($email)` — Set the email address for the robot.
- `http_method($method)` — Set HTTP method (`GET` or `POST`). Default `GET`.
- `http_referer($url)` — Set the HTTP referer header.

### Utility / Backend Support
- `installed_engines()` — (function) Return a list of all installed backend module names.
- `version()` — Return the backend’s `$VERSION`, or `$WWW::Search::VERSION` if missing.
- `maintainer()` — Return the backend’s `$MAINTAINER`, or `$WWW::Search::MAINTAINER` if missing.
- `opaque($data)` — Store/retrieve an arbitrary data element for application use.
- `submit(@args)` — Submit URLs to the engine for indexing. Returns an `HTTP::Response`. Backend‑dependent.
- `next_url($url)` — Get/set the URL for the next page of results. Useful for saving/restoring search state.
- `preprocess_results_page($html)` — (backend) Filter raw HTML before parsing.
- `_native_setup_search(...)` — Backend‑specific initialization (must be defined).
- `_native_retrieve_some()` — Core backend method to fetch and parse a page of results.
- `_parse_tree($treebuilder)` — Alternative backend method: parse an `HTML::TreeBuilder` object and return number of results found on the page.
- `test_cases()` — Deprecated. Returns the backend’s `$TEST_CASES`.
- `hash_to_cgi_string(\%hash)` — Deprecated. Build a CGI parameter string from a hash.

## Examples
perl
use WWW::Search;

my $query = 'Columbus Ohio sushi restaurant';
my $search = WWW::Search->new('AltaVista');
$search->native_query(WWW::Search::escape_query($query));
$search->login($user, $password);
while (my $result = $search->next_result()) {
    print $result->url, "\n";
}
$search->logout;
## See Also
- [`WWW::SearchResult`](https://metacpan.org/pod/WWW::SearchResult) — Result object details.
- Backend-specific manuals: `WWW::Search::`*EngineName* (e.g., [`WWW::Search::Yahoo`](https://metacpan.org/pod/WWW::Search::Yahoo), [`WWW::Search::AltaVista`](https://metacpan.org/pod/WWW::Search::AltaVista), [`WWW::Search::Ebay`](https://metacpan.org/pod/WWW::Search::Ebay)).
- [`LWP::UserAgent`](https://metacpan.org/pod/LWP::UserAgent), [`HTTP::Response`](https://metacpan.org/pod/HTTP::Response), [`HTTP::Cookies`](https://metacpan.org/pod/HTTP::Cookies) — Used internally.