# Shopping search with [shopping_search](../reference/shopping_search.md#serpapi_search_tools.shopping_search)

[shopping_search](../reference/shopping_search.md#serpapi_search_tools.shopping_search) gives an agent product results from Google Shopping, Amazon, Walmart, or eBay through one consistent `query` input and a constrained engine choice.


# When to use it

Use it for product discovery, price comparison, merchant research, availability checks, and finding listings across marketplaces. Choose [`web_search`](web_search.md) when the goal is reviews, buying guides, or manufacturer documentation rather than product listings.

This is a search-results tool. It does not complete purchases, monitor a product continuously, or fetch the separate product-detail APIs.


# Quick example

``` python
from serpapi_search_tools import shopping_search

products = shopping_search(
    allowed_engines=["google_shopping", "amazon"],
    default_engine="google_shopping",
)
agent_tools = [products]
```


# Inputs the agent can provide

| Field | Type | Required | Meaning |
|----|----|----|----|
| `query` | string | yes | Product, brand, model, or category to find |
| `engine` | enum | no | Product source: `google_shopping` compares merchants; `amazon`, `walmart`, and `ebay` search that marketplace directly; omit for the configured default |

The package translates `query` to the marketplace's native parameter: `q` for Google Shopping, `k` for Amazon, `query` for Walmart, and `_nkw` for eBay.


# Configure the tool

| Constructor option | Default | Use it for |
|----|----|----|
| `provider` | `"auto"` | Detect one installed SDK or select one explicitly |
| `allowed_engines` | all four engines | Limit the marketplaces visible to the model |
| `default_engine` | `google_shopping` when allowed | Select the marketplace used when `engine` is omitted |
| `default_params` | `None` | Fix engine-specific marketplace filters or pagination |
| `mode` | `compact` | Return the main product result section; 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` | `60` | Maximum primary product results retained in either mode |
| `api_key` | `None` | Override environment key lookup |
| `timeout` | `None` | Set the built-in client timeout |
| `client` | `None` | Add result normalization, caching, logging, or tests |
| `include_examples` | `True` | Include a product-query hint in the description |
| `name` | `"shopping_search"` | Distinguish a configured marketplace capability |

Use separate instances when each marketplace needs different defaults:

``` python
from serpapi_search_tools import shopping_search

google_products = shopping_search(
    allowed_engines=["google_shopping"],
    default_params={"gl": "us", "hl": "en"},
    result_limit=5,
    name="google_products",
)
amazon_products = shopping_search(
    allowed_engines=["amazon"],
    result_limit=5,
    name="amazon_products",
)
```


# Useful SerpApi parameters

Use `result_limit` for a consistent limit across marketplaces. An eBay-only tool can also use `_ipg` to set the retrieved page size. Locale, sorting, category, condition, delivery, price, and pagination parameters differ by marketplace. See the [Google Shopping](https://serpapi.com/google-shopping-api), [Amazon](https://serpapi.com/amazon-search-api), [Walmart](https://serpapi.com/walmart-search-api), and [eBay](https://serpapi.com/ebay-search-api) references for supported values.

For a multi-engine tool, the same `default_params` dictionary is sent to every allowed engine. Restrict `allowed_engines` or use separate named tools before adding engine-specific values.


# What comes back

Both modes return up to `result_limit` primary product results (60 by default). Google Shopping uses `shopping_results`; Amazon, Walmart, and eBay use `organic_results`. Compact mode keeps useful product details such as titles, prices, links, ratings, delivery information, and seller data while omitting supporting response sections and redundant fields. Use `result_limit=None` to keep every returned product.

Normalize only fields your application needs and keep the original engine in the normalized record.


# Common mistakes

- Assuming every engine returns `shopping_results`.
- Reusing marketplace-specific `default_params` across all four engines.
- Combining Amazon keyword mode with `node`; the package rejects that input shape.
- Expecting one price format. Some engines return strings, extracted numbers, or nested offer objects.
- Sending dozens of complete product objects to a model when a bounded summary is sufficient.


# Official SerpApi documentation

- [Google Shopping API](https://serpapi.com/google-shopping-api)
- [Amazon Search API](https://serpapi.com/amazon-search-api)
- [Walmart Search API](https://serpapi.com/walmart-search-api)
- [eBay Search API](https://serpapi.com/ebay-search-api)

Run the [marketplace comparison example](examples.md) to see four response shapes normalized into common title, price, and link fields.