SerpApi Search

Search any engine via a single REST endpoint. Each API call costs one search credit.

Important: Always use Bash(curl ...) to call the SerpApi REST API. Do not use WebFetch, WebSearch, or any other HTTP tool.

Setup

The API key must be set as an environment variable:

export SERPAPI_API_KEY="your_key_here"

If SERPAPIAPIKEY is not set, tell the user:

Set your SerpApi API key: export SERPAPIAPIKEY="your_key" — get one free at https://serpapi.com/manage-api-key

API Pattern

Every search follows the same pattern regardless of engine:

curl -s "https://serpapi.com/search.json?engine=ENGINE&QUERY_PARAM=QUERY&api_key=$SERPAPI_API_KEY"

The only things that vary per engine are:

1. The engine value
2. The query parameter name (q, k, query, etc.)
3. Engine-specific optional parameters

Engine Selection

Pick the engine based on user intent:

Default to google_light for general web searches — it's faster and cheaper than google. Use google only when you need knowledge graph, ads, or advanced SERP features.

Engine Parameters

Each engine has its own parameters documented in a JSON schema file at engines/<engine_name>.json relative to this plugin's root directory. Read the relevant file when you need engine-specific parameter details.

The JSON schema structure:

• params: engine-specific parameters (query, filters, pagination, etc.)
• commonparams: shared SerpApi parameters (apikey, device, no_cache, etc.)
• Each param has description, optional required, type, options, and group fields.

Common Parameters

These work across most engines:

Response Handling

SerpApi returns structured JSON. Key top-level fields vary by engine:

• Web search: organicresults, knowledgegraph, answerbox, relatedquestions, local_results
• Shopping: shoppingresults or organicresults (with price, rating, etc.)
• Maps: local_results (with address, rating, GPS coordinates, phone)
• Scholar: organicresults (with citationid, cited_by count, PDF links)
• News: news_results
• Images: images_results
• Flights: bestflights, otherflights, price_insights
• Jobs: jobs_results
• Finance: summary, financials, graph

Always summarize results for the user. Never dump raw JSON unless explicitly asked.

Use json_restrictor to reduce response size when you only need specific fields.

Multi-Engine Comparison

For price comparisons or cross-engine research, query multiple engines sequentially:

# Compare prices across Amazon, Walmart, and Google Shopping
curl -s "https://serpapi.com/search.json?engine=amazon&k=airpods+pro&api_key=$SERPAPI_API_KEY"
curl -s "https://serpapi.com/search.json?engine=walmart&query=airpods+pro&api_key=$SERPAPI_API_KEY"
curl -s "https://serpapi.com/search.json?engine=google_shopping&q=airpods+pro&api_key=$SERPAPI_API_KEY"

Consolidate and compare the results for the user.

Rules

1. Always use curl via Bash. Never use WebFetch, WebSearch, or other HTTP tools. The allowed-tools header restricts this skill to Bash(curl *) and Read.
2. Confirm before searching when the query or engine choice is ambiguous. Each non-cached call costs one credit.
3. Show the curl command before executing so the user sees exactly what's being called.
4. Prefer google_light over google for simple web searches.
5. Use no_cache=false (the default) to benefit from free cached results.
6. URL-encode query parameters properly. Spaces become + or %20.
7. Read the engine schema from engines/<engine>.json when you need to look up available parameters for a specific engine.

Additional Resources

• For practical curl examples, see [examples.md](examples.md)
• Interactive playground: https://serpapi.com/playground
• Full API docs: https://serpapi.com/search-api
• Account & usage: https://serpapi.com/account-api