Skip to content
SerpApi Web Search

SerpApi Web SearchSkill

by SerpApi
Added to Onei
1 views
MIT
Repository Docs
markdown Development

Summary

SerpApi's official skill for structured search: which of 130+ engines to call for citations, local businesses, flights, hotels, shopping or jobs, which response key holds the answer, and the gotchas that silently return the wrong field.

Features

  • Intent-to-engine table covering 130+ engines, each with its result key and the fields that matter
  • Documents the silent failure modes: place_results vs local_results, summary vs organic_results, nested citation counts
  • Lists the engines that do not take `q` (youtube, amazon, ebay, walmart, apple_app_store, flights, hotels)
  • Copy-paste --jq extractions for citation counts, business details, live flight prices and shopping comparisons
  • Fan-out composition patterns and cross-engine agreement as a confidence check
  • Billing notes: only successful searches count, identical queries are cached free for an hour
  • Works through the hosted MCP server, the serpapi CLI, an SDK or curl

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: serpapi-web-search
description: >-
  Structured search data via 130+ engines — use INSTEAD OF web_search when you
  need: exact citations (google_scholar), local business details (google_maps),
  flight prices (google_flights), hotel rates (google_hotels), shopping prices
  (google_shopping_light), job listings (google_jobs), or any task where
  web_search gives approximate/unstructured results. Returns machine-readable
  JSON. Default engine: google_light.
compatibility: >-
  Requires: search MCP tool (mcp.serpapi.com), or serpapi CLI, or SDK, or curl.
  All paths need SERPAPI_KEY.
license: MIT
---

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:**
```bash
# 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](https://github.com/serpapi/serpapi-cli)):
```bash
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](https://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](https://serpapi.com/locations-api)

## Composition

**Fan out** for research (parallel, not sequential):
```bash
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):
```bash
# 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](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=<key from serpapi.com/dashboard>`. Do NOT retry with the same key. |
| 429 | Quota exhausted | Switch to `_light`, reduce `num`, check [dashboard](https://serpapi.com/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](https://serpapi.com/search-api) — full API docs
- [serpapi.com/search-engine-apis](https://serpapi.com/search-engine-apis) — all engines
- [serpapi.com/pricing](https://serpapi.com/pricing) — credits & plans
- [github.com/serpapi](https://github.com/serpapi) — SDKs, CLI, MCP server

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions

Add the hosted MCP server, then the skill:

claude mcp add --transport http serpapi https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Or in any MCP client config:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Get a key at serpapi.com/dashboard. Self-hosting is available from the serpapi-mcp repository.

Example Usage

How many citations does the "Attention Is All You Need" paper have right now, and what is the phone number and rating of the highest-rated ramen shop in Shibuya? Cite your sources.

Description

A general web_search tool returns prose about the world. SerpApi returns the world as JSON — but only if you call the right engine with the right parameter and read the right key, and getting any of the three wrong fails quietly. serpapi-web-search is SerpApi's official agent skill for closing that gap.

An engine table, not a tutorial

The core of the skill is a lookup table: intent → engine → result key → the fields worth extracting. General web is google_light → organic_results; academic citations are google_scholar; local businesses are google_maps; flights, hotels, jobs, shopping, finance, video and the Apple App Store each have their own engine and their own response shape. It steers toward _light variants, which are faster, cheaper and return cleaner JSON.

The gotchas are the real content

The section that earns the skill its place is the list of things that go wrong without erroring:

  • Google Maps returns place_results for a named business but local_results for a category search — check both keys.
  • Finance returns summary, Flights returns best_flights, Hotels returns properties — none of them organic_results.
  • A Scholar citation count lives at .organic_results[0].inline_links.cited_by.total, not a top-level field.
  • YouTube takes search_query, Amazon takes k, eBay takes _nkw, Walmart takes query, the App Store takes term — not q.
  • Flights and Hotels need structured parameters (departure_id/arrival_id/outbound_date; check-in and check-out dates) rather than a query string.
  • Shopping prices are third-party reseller feeds; for a specific retailer, use google_light with a site: filter.

It also notes that an empty organic_results on a 200 is not an error — widen the query or switch engine.

Composition and cost

The skill pushes fan-out over sequential querying (finance, news and consensus in parallel), gives copy-paste --jq extractions for common exact-data pulls, and documents progressive refinement and cross-engine agreement as confidence signals. Practical billing notes are included: only successful searches are billed, and an identical query and parameter set is a free cached result for an hour. Error handling is explicit about not retrying a 401 with the same key.

One piece of advice generalises well beyond SerpApi: extract inline — pull {title, link, snippet} into working notes after each search rather than trusting raw results to survive context compaction.

Getting it running

It works through the hosted MCP server at mcp.serpapi.com, the serpapi CLI, an SDK, or plain curl — all of them keyed on SERPAPI_KEY. MIT licensed, maintained by SerpApi.

Related Skills

Skill: Trail of Bits Static Analysis

by Trail of Bits

New

CodeQL, Semgrep and SARIF static-analysis toolkit from Trail of Bits: taint tracking, fast pattern scans and merged, deduplicated security findings for coding agents.

Development
3 views

Skill: Playwright CLI

by Microsoft

New

Microsoft's official Playwright skill — drives a real browser from the command line using accessibility snapshots and element refs, and plans, generates and heals Playwright tests.

Development
7 views 1 copies

Skill: Google Maps Platform

by Google Maps Platform

New

Google's official agent skill for writing production Maps Platform code — grounded in freshly fetched docs, with a demo key path that needs no billing account.

Development
8 views

Skill: Use Railway

by Railway

New

Railway's official agent skill: create projects, provision databases and buckets, deploy, manage variables and domains, and read build failures back — from the CLI, API or MCP server.

Development
8 views
Browse all skills →