Skip to content
SerpApi Web Search

SerpApi Web Search Skill

by SerpApi serpapi/skills

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.

GitHub Docs
Development
Added to Onei
MIT

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from serpapi/skills.

$ npx skills add serpapi/skills --skill serpapi-web-search

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

  1. Open the skill on GitHub and download the folder that holds its SKILL.md.
  2. Put it at ~/.claude/skills/serpapi-web-search/, where Claude Code picks it up in every project.

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/serpapi-web-search/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/
Open folder on GitHub

About

  • 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

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.

Try it

Once installed, ask your agent something like:

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.

SKILL.md

The instructions your agent loads, as published by SerpApi.

SKILL.md
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:

# 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](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).

IntentEngineResult keyKey fields
General web (default)google_lightorganic_results.title, .link, .snippet
Knowledge graph / featured snippetsgoogleorganic_results + many.knowledge_graph, .answer_box
Newsgoogle_news_lightnews_results.title, .link, .date
Imagesgoogle_images_lightimages_results.original, .thumbnail
Shopping / pricesgoogle_shopping_lightshopping_results.title, .price, .source
Academic papersgoogle_scholarorganic_results.title, .inline_links.cited_by.total
Local businesses (list)google_mapslocal_results.title, .phone, .address, .rating, .reviews
Local business (single)google_mapsplace_results.title, .phone, .address, .rating, .reviews
Place reviewsgoogle_maps_reviewsreviews.rating, .snippet, .date
Videoyoutubevideo_results.title, .link, .views, .length
Stock / tickergoogle_financesummary.price, .exchange, .currency
Flightsgoogle_flightsbest_flights.flights[].airline, .price, .total_duration
Hotelsgoogle_hotelsproperties.name, .rate_per_night.extracted_lowest, .total_rate.extracted_lowest, .overall_rating
Jobsgoogle_jobsjobs_results.title, .company_name, .location
App Store (iOS)apple_app_storeorganic_results.title, .rating[0].rating, .rating[0].count, .developer.name
Alternative webbing, duckduckgoorganic_results.title, .link, .snippet
SerpApi's own index (alpha)search_indexorganic_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:
EngineParam (not q)
youtubesearch_query
amazonk
ebay_nkw
walmartquery
google_maps_reviewsdata_id
google_flightsdeparture_id + arrival_id + outbound_date
google_hotelsq + check_in_date + check_out_date + adults
apple_app_storeterm (not q)
Parameters

Most tasks need only engine, q, num. Add when relevant:

ParamUse
glCountry code (us, uk, de). Default us.
hlLanguage (en, es, fr). Affects ranking.
locationCity string ("Austin, Texas"). Overrides gl.
tbsTime: qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year).
startPagination 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=<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
CodeMeaningFix
400Missing q or engineAdd the required param.
401Invalid API keyRun serpapi login or set SERPAPI_KEY=<key from serpapi.com/dashboard>. Do NOT retry with the same key.
429Quota exhaustedSwitch 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
Install

Related Skills

See all SerpApi Web Search alternatives

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
Browse all skills →