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=

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": "", "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](rules/examples.md). For SDKs (Python/JS/Go/Ruby/PHP/Java/.NET): [rules/sdks.md](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).

| Intent | Engine | Result key | Key fields | |---|---|---|---| | General web (default) | google_light | organic_results | .title, .link, .snippet | | Knowledge graph / featured snippets | google | organic_results + many | .knowledge_graph, .answer_box | | News | google_news_light | news_results | .title, .link, .date | | Images | google_images_light | images_results | .original, .thumbnail | | Shopping / prices | google_shopping_light | shopping_results | .title, .price, .source | | Academic papers | google_scholar | organic_results | .title, .inline_links.cited_by.total | | Local businesses (list) | google_maps | local_results | .title, .phone, .address, .rating, .reviews | | Local business (single) | google_maps | place_results | .title, .phone, .address, .rating, .reviews | | Place reviews | google_maps_reviews | reviews | .rating, .snippet, .date | | Video | youtube | video_results | .title, .link, .views, .length | | Stock / ticker | google_finance | summary | .price, .exchange, .currency | | Flights | google_flights | best_flights | .flights[].airline, .price, .total_duration | | Hotels | google_hotels | properties | .name, .rate_per_night.extracted_lowest, .total_rate.extracted_lowest, .overall_rating | | Jobs | google_jobs | jobs_results | .title, .company_name, .location | | App Store (iOS) | apple_app_store | organic_results | .title, .rating[0].rating, .rating[0].count, .developer.name | | Alternative web | bing, duckduckgo | organic_results | .title, .link, .snippet | | SerpApi's own index (alpha) | search_index | organic_results | .title, .link, .snippet |

All 130+ engines: [rules/ENGINES.md](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:

| Param | Use | |---|---| | gl | Country code (us, uk, de). Default us. | | hl | Language (en, es, fr). Affects ranking. | | location | City string ("Austin, Texas"). Overrides gl. | | tbs | Time: qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year). | | start | Pagination offset. Prefer serpapi_pagination.next when present. | | no_cache | "true" = live crawl (costs 1 credit). |

Full reference: [rules/parameters.md](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=.

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](rules/use-cases.md)

Errors

| Code | Meaning | Fix | |---|---|---| | 400 | Missing q or engine | Add the required param. | | 401 | Invalid API key | Run serpapi login or set SERPAPI_KEY=. Do NOT retry with the same key. | | 429 | Quota exhausted | Switch to _light, reduce num, check dashboard. |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: serpapi
• Source: serpapi/skills
• License: MIT
• Homepage: https://serpapi.com/

Install and usage instructions live in the source repository linked above.