SerpApi Web SearchSkill

Added to Onei Sep 24, 2026

MIT

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.

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

Claude Code & Claude apps

Claude loads skills automatically from its skills directory.

Claude Code

Create a skill folder — personal: ~/.claude/skills/serpapi-web-search/, or per-project: .claude/skills/serpapi-web-search/
Save the skill content as SKILL.md inside that folder.
Claude Code picks it up automatically and invokes it when relevant.

mkdir -p ~/.claude/skills/serpapi-web-search

Claude.ai / Claude Desktop

Enable Skills under Settings → Capabilities, then upload the skill (a folder or zip containing SKILL.md).

One-prompt install

Paste this prompt into any agent with web access and it will install the skill for you.

Install the "SerpApi Web Search" skill from Onei AI. Fetch https://onei.ai/skills/serpapi-web-search, extract the full skill content from the page, and save it where you load skills from (for Claude Code: .claude/skills/serpapi-web-search/SKILL.md). From now on, apply this skill whenever it is relevant to my request.

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.

Install

Related Skills

Skill: Brave Web Search

by Brave

Brave's official skill for the Brave Search API — ranked web results with snippets and thumbnails, freshness and SafeSearch filters, search operators, pagination, and Goggles for custom ranking.

Development

Skill: Hugging Face Dataset Viewer

by Hugging Face

Read-only recipes for the Hugging Face Dataset Viewer API — resolve splits, paginate rows, run text search and row filters, and pull parquet URLs and column statistics.

Development

Skill: Brave Search CLI (bx)

by Brave

Brave's official search skill: one CLI that searches, scrapes and extracts in a single call, returning token-budgeted web content instead of a list of links.

Writing & Communication

Skill: OpenSEO Keyword Research

by Every App, Inc.

Turns seed topics into a prioritised keyword set using live OpenSEO MCP data — volume, difficulty and SERP evidence instead of an agent guessing at search demand.

Writing & Communication

Browse all skills →