Shopping search with shopping_search

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 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

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 to keep supporting sections and all fields on retained results
response_format markdown Return Markdown by default, or use 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:

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, Amazon, Walmart, and eBay 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

Run the marketplace comparison example to see four response shapes normalized into common title, price, and link fields.