serpapi-web-search

Invocation

Use the first available method:

1. MCP tool — use serpapi_search if available (source):

serpapi_search(params={"engine": "google_light", "q": "query"}, mode="compact")

2. serpapi-cli — preferred shell fallback; optimized for AI agents (source):

serpapi search engine=google_light q="your query"

# --fields: server-side filtering — reduces response size at the API level
serpapi search --fields "organic_results[0:3]" engine=google_light q="your query"

# --jq: client-side filtering (like gh --jq)
serpapi search --jq ".organic_results[0:3]|[.[]|{title,link}]" engine=google_light q="your query"

Install: brew tap serpapi/homebrew-tap && brew install serpapi
Auth: SERPAPI_KEY env var, --api-key flag, or serpapi login.
Exit codes: 0 success · 1 API error · 2 usage error. Errors are JSON on stderr.

3. SDK — when writing code: see rules/sdks.md — Python, JS, Go, Ruby, PHP, Java, .NET.

4. curl — universal fallback:

curl -G "https://serpapi.com/search.json" \
  --data-urlencode "q=your query" \
  --data-urlencode "engine=google_light" \
  --data-urlencode "api_key=${SERPAPI_KEY}"

Engine Selection

Pick the engine that matches the user's intent:

Use Case	Engine
General web (default)	google_light
Comprehensive (knowledge graph, local pack)	google
News	google_news_light
Images	google_images_light
Shopping / prices	google_shopping_light
Alternative web	bing
Privacy-first	duckduckgo
Academic / research	google_scholar
Local / maps	google_maps
Video	youtube
SerpApi's own index (alpha, no Google/Bing)	search_index

Prefer _light variants — they're faster and cheaper. Use the full engine only when you need knowledge graph, local pack, or featured snippets.

For engines not listed above (flights, hotels, jobs, finance, patents, etc.), read rules/ENGINES.md.

Error Reference

• 401 — Invalid or missing API key.
• 429 — Monthly quota reached. Check usage: serpapi account or serpapi.com/dashboard · account API.
• 400 — Missing required parameter (q or engine).

Docs

Official reference (link these when agents need deeper detail):

Topic	URL
Main API reference	serpapi.com/search-api
All engines (online)	serpapi.com/search-engine-apis
Locations lookup	serpapi.com/locations-api
Account & quota API	serpapi.com/account-api
Search Index API (alpha)	serpapi.com/search-index-api
Pricing	serpapi.com/pricing

Rules

Read these files when you need more detail:

• Parameters (locale, time filter, pagination, safe search): rules/parameters.md
• Response format (result keys, JSON shape, pagination): rules/response.md
• Examples (news, shopping, time-filtered, Bing): rules/examples.md
• SDKs (Python, JS, Go, Ruby, PHP, Java, .NET): rules/sdks.md
• All 100+ engines (flights, hotels, jobs, finance, patents…): rules/ENGINES.md