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