serpapi-web-search

You have search (via MCP) or serpapi (via CLI). This file helps you pick the right engine, extract the right response key, and avoid common mistakes.

Auth check — do this first if you get 401 or haven’t used serpapi before:

# Check if already authenticated:
serpapi account 2>&1 | head -1
# If "Active" → you're good. If not:
serpapi login            # interactive — stores key persistently
# Or set env: export SERPAPI_KEY=<key from serpapi.com/dashboard>

If serpapi is not on PATH: install with brew install serpapi/tap/serpapi-cli. If no MCP tool and no CLI: use curl with api_key=${SERPAPI_KEY} param (see below).

Invocation

search(params={"engine": "google_light", "q": "<query>", "num": 20}, mode="compact")

mode="compact" strips metadata — same results, ~200 fewer tokens. Default num=20. Use num=10 for simple lookups, num=3 for single-fact verification. Empty results ≠ error. organic_results may be absent on 200 — widen query or switch engine.

CLI fallback (serpapi-cli):

serpapi search engine=google_light q="query" num=20

For --fields/--jq filtering: rules/examples.md. For SDKs (Python/JS/Go/Ruby/PHP/Java/.NET): rules/sdks.md. For curl: curl -G "https://serpapi.com/search.json" --data-urlencode "q=..." --data-urlencode "engine=google_light" --data-urlencode "api_key=${SERPAPI_KEY}"

Engine selection

Pick by intent. Prefer _light variants (faster, cheaper, cleaner JSON).

All 130+ engines: rules/ENGINES.md · Online: serpapi.com/search-engine-apis

Gotchas

• Shopping = third-party reseller prices. For a specific retailer’s price, use google_light with site: (e.g., q="MacBook Air M4 site:apple.com"). Google Shopping aggregates from feeds — prices may not match the retailer’s own site (e.g., Target sale prices may lag).
• Maps returns place_results OR local_results — named business → place_results; category search → local_results. Always check both keys.
• Finance returns summary, not organic_results. Same for Flights (best_flights), Hotels (properties).
• Scholar citation count is at .organic_results[0].inline_links.cited_by.total — not a top-level field. Use --jq '.organic_results[0].inline_links.cited_by.total' to extract.
• Maps review count is at .place_results.reviews (integer) or .local_results[].reviews. Rating at .rating.
• Flights require specific params — not q. Use departure_id=JFK arrival_id=LAX outbound_date=2026-07-10 type=2 (type 2 = one-way).
• Hotels require dates — q="hotels in Kyoto" check_in_date=2026-07-20 check_out_date=2026-07-22 adults=2. Price is at .properties[].rate_per_night.extracted_lowest (per night) or .total_rate.extracted_lowest (total stay). Sort by price: sort_by=8.
• Apple App Store uses term — not q. Rating is nested: .organic_results[0].rating[0].rating (float, e.g. 4.78).

• Non-standard query params:

  Engine	Param (not q)
  youtube	search_query
  amazon	k
  ebay	_nkw
  walmart	query
  google_maps_reviews	data_id
  google_flights	departure_id + arrival_id + outbound_date
  google_hotels	q + check_in_date + check_out_date + adults
  apple_app_store	term (not q)

Parameters

Most tasks need only engine, q, num. Add when relevant:

Full reference: rules/parameters.md · Locations: serpapi.com/locations-api

Composition

Fan out for research (parallel, not sequential):

serpapi search engine=google_finance q="AAPL:NASDAQ" &
serpapi search engine=google_news_light q="Apple earnings" &
serpapi search engine=google_light q="AAPL analyst consensus" num=5 &
wait

Common exact-data extractions (copy-paste patterns):

# Exact citation count
serpapi search engine=google_scholar q="paper title" --jq '.organic_results[0].inline_links.cited_by.total'

# Business phone + rating + reviews
serpapi search engine=google_maps q="Business Name City" --jq '.place_results | {phone, rating, reviews}'

# Live flight price
serpapi search engine=google_flights departure_id=JFK arrival_id=LAX outbound_date=2026-07-10 type=2 --jq '.best_flights[0] | {price, airline: .flights[0].airline}'

# Shopping prices by retailer
serpapi search engine=google_shopping_light q="Product Name" --jq '[.shopping_results[:5] | .[] | {title, price, source}]'

Progressive refinement: exact phrase → drop quotes → add tbs=qdr:y → switch engine.

Two-step reviews: google_maps q="business" → grab data_id → google_maps_reviews data_id=<id>.

Cross-check: same query on google_light + bing — both agree → high confidence.

Extract inline. After each search, pull {title, link, snippet} into working notes. Don’t rely on raw results surviving context compaction.

More patterns: rules/use-cases.md

Errors

If you get 401: the key is wrong or missing. Do not loop — fix the env var first. Billing: only successful searches count. Same query + params = free cached result for 1 hour.

Reference links

• serpapi.com/search-api — full API docs
• serpapi.com/search-engine-apis — all engines
• serpapi.com/pricing — credits & plans
• github.com/serpapi — SDKs, CLI, MCP server