| name | search |
| description | Search Google, Bing, Amazon, Walmart, YouTube, Google Maps, Google Scholar, and 100+ other engines via the SerpApi REST API. Calls the API using curl. Use when the user wants to search the web, find products or prices, look up local businesses, research academic papers, check news, find jobs, compare flights or hotels, analyze SERPs, or retrieve any search engine results. |
SerpApi Search
Search any engine via a single REST endpoint. Each API call costs one search credit.
Important: Always use curl via the Shell tool 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 SERPAPI_API_KEY is not set, tell the user:
Set your SerpApi API key: export SERPAPI_API_KEY="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:
- The
engine value
- The query parameter name (
q, k, query, etc.)
- 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.)common_params: shared SerpApi parameters (api_key, device, no_cache, etc.)- Each param has
description, optional required, type, options, and group fields.
Common Parameters
These work across most engines:
| Param | Description |
|---|
location | Search origin (city-level recommended). E.g., Austin, Texas, United States |
gl | Country code. E.g., us, uk, fr |
hl | Language code. E.g., en, es, de |
device | desktop (default), tablet, or mobile |
no_cache | true to force fresh results (costs a credit; cached results are free) |
num | Number of results (where supported) |
start / page | Pagination. Google uses start (0, 10, 20...), Amazon/Walmart use page (1, 2, 3...) |
json_restrictor | Restrict response fields for smaller payloads. E.g., organic_results.title,organic_results.link |
Response Handling
SerpApi returns structured JSON. Key top-level fields vary by engine:
- Web search:
organic_results, knowledge_graph, answer_box, related_questions, local_results
- Shopping:
shopping_results or organic_results (with price, rating, etc.)
- Maps:
local_results (with address, rating, GPS coordinates, phone)
- Scholar:
organic_results (with citation_id, cited_by count, PDF links)
- News:
news_results
- Images:
images_results
- Flights:
best_flights, other_flights, 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:
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
- Always use
curl via the Shell tool. Do not use WebFetch, WebSearch, or other HTTP tools.
- Confirm before searching when the query or engine choice is ambiguous. Each non-cached call costs one credit.
- Show the curl command before executing so the user sees exactly what's being called.
- Prefer
google_light over google for simple web searches.
- Use
no_cache=false (the default) to benefit from free cached results.
- URL-encode query parameters properly. Spaces become
+ or %20.
- Read the engine schema from
engines/<engine>.json when you need to look up available parameters for a specific engine.
Additional Resources
