# Web search with [web_search](../reference/web_search.md#serpapi_search_tools.web_search)

[web_search](../reference/web_search.md#serpapi_search_tools.web_search) gives an agent general webpages from Google, Google Light, Bing, Yahoo, or DuckDuckGo. It is the best default for research that does not require a specialized result type.


# When to use it

Use it for background research, documentation, company websites, public facts, and cross-checking sources. Start with `google_light` when you want fast, compact organic results for an agent.

Choose [`news_search`](news_search.md) for current articles, [`maps_search`](maps_search.md) for places, or [`shopping_search`](shopping_search.md) for products. Those tools return result structures designed for their verticals.


# Quick example

``` python
from serpapi_search_tools import web_search

tool = web_search()
agent_tools = [tool]
```

With one supported SDK installed, `tool` is native to that SDK. For a direct Python callable, use `web_search(provider="function")`.


# Inputs the agent can provide

| Field | Type | Required | Meaning |
|----|----|----|----|
| `query` | string | yes | The words or question to search for |
| `engine` | enum | no | Search source; omit for the configured default. `google_light` is fast, `google` returns richer Google result types, and the other values select that named web source |

The package maps the friendly `query` field to each engine's native parameter: Google, Google Light, Bing, and DuckDuckGo use `q`; Yahoo uses `p`.


# Configure the tool

| Constructor option | Default | Use it for |
|----|----|----|
| `provider` | `"auto"` | Detect the installed SDK; use `"function"` for a callable or an explicit SDK name in multi-SDK environments |
| `allowed_engines` | all five engines | Restrict the enum visible to the model |
| `default_engine` | `google_light` when allowed | Choose the engine used when the model omits `engine` |
| `default_params` | `None` | Fix engine parameters such as locale, filters, or pagination in application code |
| `mode` | `compact` | Return the main web result sections; use [SearchResultMode.FULL](../reference/SearchResultMode.md#serpapi_search_tools.SearchResultMode.FULL) to keep supporting sections and all fields on retained results |
| `response_format` | `markdown` | Return Markdown by default, or use [SearchResultFormat.JSON](../reference/SearchResultFormat.md#serpapi_search_tools.SearchResultFormat.JSON) for structured fields |
| `result_limit` | `10` | Maximum items kept in each web result list in either mode |
| `api_key` | `None` | Override the environment-based SerpApi key |
| `timeout` | `None` | Set the built-in client's request timeout |
| `client` | `None` | Supply a testing, caching, logging, or custom HTTP client |
| `include_examples` | `True` | Include a short invocation hint in the tool description |
| `name` | `"web_search"` | Give this configured tool a distinct name |

For predictable results, expose only the engines your application actually needs:

``` python
from serpapi_search_tools import web_search

tool = web_search(
    allowed_engines=["google_light", "bing"],
    default_engine="google_light",
)
```


# Useful SerpApi parameters

`default_params` is forwarded to the selected engine and is not editable by the model. This Google Light-only tool fixes country and language while `result_limit` bounds the returned result list:

``` python
from serpapi_search_tools import web_search

us_web = web_search(
    allowed_engines=["google_light"],
    default_params={"gl": "us", "hl": "en"},
    result_limit=5,
    name="us_web_search",
)
```

Common needs include locale, geographic targeting, pagination, safe search, and date filters. Parameter names and accepted values differ by engine. If you need engine-specific defaults, create separate tool instances instead of sending one `default_params` dictionary to several incompatible engines.

Use `result_limit` for a consistent limit across web engines. A DuckDuckGo-only tool can also use `default_params={"m": 20}` to control how many results DuckDuckGo retrieves. Pagination parameters differ by engine; see the linked API references for supported values.


# What comes back

Both modes keep up to `result_limit` items in each web result list (10 by default). Compact mode returns `organic_results` and available answer sections. Google Light may also return related questions, related searches, and top stories. Metadata, parameters, pagination, and other supporting sections are omitted.

Result sections are optional. Use `mode=SearchResultMode.FULL` when application code needs supporting response sections or additional result fields. Add `result_limit=None` to keep every returned result.


# Common mistakes

- Adding a vertical engine such as `google_news` to `allowed_engines`. Use its dedicated constructor instead.
- Applying Google-only `default_params` while Bing, Yahoo, or DuckDuckGo is still allowed.
- Setting `engine` inside `default_params`. Choose available engines with `allowed_engines` and `default_engine`.
- Combining incompatible location fields. The package catches common conflicts, but each engine's official reference remains the source of truth.


# Official SerpApi documentation

- [Google Search API](https://serpapi.com/search-api)
- [Google Light Search API](https://serpapi.com/google-light-api)
- [Bing Search API](https://serpapi.com/bing-search-api)
- [Yahoo Search API](https://serpapi.com/yahoo-search-api)
- [DuckDuckGo Search API](https://serpapi.com/duckduckgo-search-api)

See [regional tool instances](examples.md) and the [general research recipe](recipes.md) for larger examples.