Search

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 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: 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.)
• 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:

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:

# 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
• Interactive playground: https://serpapi.com/playground
• Full API docs: https://serpapi.com/search-api
• Account & usage: https://serpapi.com/account-api

SerpApi Curl Examples

Basic Google Search (Light)

curl -s "https://serpapi.com/search.json?engine=google_light&q=best+python+web+frameworks&api_key=$SERPAPI_API_KEY"

Location-Specific Google Search

curl -s "https://serpapi.com/search.json?engine=google_light&q=coffee+shops&location=Austin,+Texas,+United+States&hl=en&gl=us&api_key=$SERPAPI_API_KEY"

Full Google Search (with Knowledge Graph, Ads, etc.)

curl -s "https://serpapi.com/search.json?engine=google&q=Tesla&location=New+York,+United+States&hl=en&gl=us&api_key=$SERPAPI_API_KEY"

Google Scholar — Academic Papers

curl -s "https://serpapi.com/search.json?engine=google_scholar&q=transformer+architecture+attention&as_ylo=2020&api_key=$SERPAPI_API_KEY"

Amazon Product Search

curl -s "https://serpapi.com/search.json?engine=amazon&k=mechanical+keyboard&api_key=$SERPAPI_API_KEY"

Walmart Product Search

curl -s "https://serpapi.com/search.json?engine=walmart&query=airpods+pro&sort=price_low&api_key=$SERPAPI_API_KEY"

eBay Product Search

curl -s "https://serpapi.com/search.json?engine=ebay&_nkw=vintage+vinyl+records&api_key=$SERPAPI_API_KEY"

Google Maps — Local Businesses

curl -s "https://serpapi.com/search.json?engine=google_maps&q=pizza&ll=%4040.7455096%2C-74.0083012%2C14z&type=search&api_key=$SERPAPI_API_KEY"

Google Maps with Location Name

curl -s "https://serpapi.com/search.json?engine=google_maps&q=restaurants&location=San+Francisco,+California&type=search&z=13&api_key=$SERPAPI_API_KEY"

Google News — Current Events

curl -s "https://serpapi.com/search.json?engine=google_news&q=artificial+intelligence&gl=us&hl=en&api_key=$SERPAPI_API_KEY"

Google Trends — Keyword Research

curl -s "https://serpapi.com/search.json?engine=google_trends&q=react,vue,svelte&api_key=$SERPAPI_API_KEY"

Google Flights

curl -s "https://serpapi.com/search.json?engine=google_flights&departure_id=SFO&arrival_id=JFK&outbound_date=2026-06-01&return_date=2026-06-08&currency=USD&hl=en&api_key=$SERPAPI_API_KEY"

Google Jobs

curl -s "https://serpapi.com/search.json?engine=google_jobs&q=senior+software+engineer&location=Remote&hl=en&api_key=$SERPAPI_API_KEY"

Google Finance — Stock Data

curl -s "https://serpapi.com/search.json?engine=google_finance&q=AAPL:NASDAQ&api_key=$SERPAPI_API_KEY"

YouTube Search

curl -s "https://serpapi.com/search.json?engine=youtube&search_query=rust+programming+tutorial&api_key=$SERPAPI_API_KEY"

Pagination — Google Page 2

curl -s "https://serpapi.com/search.json?engine=google_light&q=machine+learning&start=10&api_key=$SERPAPI_API_KEY"

Pagination — Amazon Page 2

curl -s "https://serpapi.com/search.json?engine=amazon&k=laptop+stand&page=2&api_key=$SERPAPI_API_KEY"

Using json_restrictor for Smaller Responses

curl -s "https://serpapi.com/search.json?engine=google_light&q=openai&json_restrictor=organic_results.title,organic_results.link,organic_results.snippet&api_key=$SERPAPI_API_KEY"

Price Comparison Across Engines

Run these sequentially and compare:

curl -s "https://serpapi.com/search.json?engine=amazon&k=sony+wh-1000xm5&api_key=$SERPAPI_API_KEY"
curl -s "https://serpapi.com/search.json?engine=walmart&query=sony+wh-1000xm5&api_key=$SERPAPI_API_KEY"
curl -s "https://serpapi.com/search.json?engine=google_shopping&q=sony+wh-1000xm5&api_key=$SERPAPI_API_KEY"

Google AI Mode

curl -s "https://serpapi.com/search.json?engine=google_ai_mode&q=explain+quantum+computing+in+simple+terms&api_key=$SERPAPI_API_KEY"

Yelp — Local Reviews

curl -s "https://serpapi.com/search.json?engine=yelp&find_desc=sushi&find_loc=Los+Angeles,+CA&api_key=$SERPAPI_API_KEY"

Google Autocomplete Suggestions

curl -s "https://serpapi.com/search.json?engine=google_autocomplete&q=how+to+learn&api_key=$SERPAPI_API_KEY"

Check Account Usage

curl -s "https://serpapi.com/account.json?api_key=$SERPAPI_API_KEY"