serpapi-web-search

MCP 経由の search、または CLI 経由の serpapi を利用できます。このファイルでは、適切なエンジンの選び方、正しいレスポンスキーの取り出し方、よくある間違いの回避方法を説明します。

認証の確認 — 401 が発生した場合、または初めて serpapi を使う場合は、最初に実行してください：

# 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>

serpapi が PATH にない場合：brew install serpapi/tap/serpapi-cli でインストールしてください。 MCP ツールも CLI もない場合：以下を参照し、api_key=${SERPAPI_KEY} パラメーターを指定して curl を使ってください。

呼び出し

search(params={"engine": "google_light", "q": "<query>", "num": 20}, mode="compact")

mode="compact" はメタデータを除外します。結果は同じで、トークン数を約 200 節約できます。 デフォルトの num=20。簡単な検索には num=10、単一の事実確認には num=3 を使ってください。 結果が空でもエラーとは限りません。200 が返っても organic_results が存在しない場合があります。その場合はクエリの範囲を広げるか、エンジンを切り替えてください。

CLI の代替手段（serpapi-cli）：

serpapi search engine=google_light q="query" num=20

--fields／--jq によるフィルタリングについては、rules/examples.md を参照してください。 SDK（Python/JS/Go/Ruby/PHP/Java/.NET）については、rules/sdks.md を参照してください。 curl の場合：curl -G "https://serpapi.com/search.json" --data-urlencode "q=..." --data-urlencode "engine=google_light" --data-urlencode "api_key=${SERPAPI_KEY}"

エンジンの選択

検索意図に合わせて選んでください。より高速で安価、かつ JSON が整理された _light バリアントを優先してください。

検索意図	エンジン	結果キー	主なフィールド
一般的なウェブ検索（デフォルト）	google_light	organic_results	.title、.link、.snippet
ナレッジグラフ／強調スニペット	google	organic_results + 多数	.knowledge_graph、.answer_box
ニュース	google_news_light	news_results	.title、.link、.date
画像	google_images_light	images_results	.original、.thumbnail
ショッピング／価格	google_shopping_light	shopping_results	.title、.price、.source
学術論文	google_scholar	organic_results	.title、.inline_links.cited_by.total
ローカルビジネス（一覧）	google_maps	local_results	.title、.phone、.address、.rating、.reviews
ローカルビジネス（単一）	google_maps	place_results	.title、.phone、.address、.rating、.reviews
場所のレビュー	google_maps_reviews	reviews	.rating、.snippet、.date
動画	youtube	video_results	.title、.link、.views、.length
株式／ティッカー	google_finance	summary	.price、.exchange、.currency
フライト	google_flights	best_flights	.flights[].airline、.price、.total_duration
ホテル	google_hotels	properties	.name、.rate_per_night.extracted_lowest、.total_rate.extracted_lowest、.overall_rating
求人	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
代替ウェブ検索	bing、duckduckgo	organic_results	.title、.link、.snippet
SerpApi 独自のインデックス（アルファ版）	search_index	organic_results	.title、.link、.snippet

130 以上のすべてのエンジン：rules/ENGINES.md · オンライン：serpapi.com/search-engine-apis

注意点

• Shopping の価格は、サードパーティの再販業者のものです。 特定の小売業者の価格を調べるには、site: を指定して google_light を使います（例：q="MacBook Air M4 site:apple.com"）。Google Shopping はフィードから情報を集約するため、価格が小売業者のサイト上の価格と一致しない場合があります（例：Target のセール価格が反映されるまで時間がかかることがあります）。

• Maps は place_results または local_results を返します。名前を指定した店舗の検索では place_results、カテゴリ検索では local_results が返ります。必ず両方のキーを確認してください。

• Finance が返すのは organic_results ではなく summary です。 Flights では best_flights、Hotels では properties が返ります。

• Scholar の引用数は .organic_results[0].inline_links.cited_by.total にあります。トップレベルのフィールドではありません。抽出には --jq '.organic_results[0].inline_links.cited_by.total' を使います。

• Maps のレビュー数は .place_results.reviews（整数）または .local_results[].reviews にあります。評価は .rating にあります。

• Flights には特定のパラメーターが必要です。q は使いません。departure_id=JFK arrival_id=LAX outbound_date=2026-07-10 type=2 を使います（type 2 = 片道）。

• Hotels には日付が必要です。q="hotels in Kyoto" check_in_date=2026-07-20 check_out_date=2026-07-22 adults=2 を使います。料金は .properties[].rate_per_night.extracted_lowest（1 泊あたり）または .total_rate.extracted_lowest（滞在合計）にあります。料金順に並べ替えるには sort_by=8 を使います。

• Apple App Store では q ではなく term を使います。 評価は入れ子になっており、.organic_results[0].rating[0].rating にあります（浮動小数点数。例：4.78）。

• 標準以外のクエリパラメーター：

  Engine	Param（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（q ではありません）

パラメーター

ほとんどのタスクで必要なのは engine、q、num だけです。必要に応じて追加します。

Param	用途
gl	国コード（us、uk、de）。デフォルトは us です。
hl	言語（en、es、fr）。ランキングに影響します。
location	都市名（"Austin, Texas"）。gl を上書きします。
tbs	期間：qdr:d（日）、qdr:w（週）、qdr:m（月）、qdr:y（年）。
start	ページネーションのオフセット。利用可能な場合は serpapi_pagination.next を優先してください。
no_cache	"true" = ライブクロール（クレジットを 1 消費します）。

全リファレンス：rules/parameters.md · 地域：serpapi.com/locations-api

組み合わせ方

調査では並列にファンアウトし、順番には実行しません。

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

よく使う正確なデータの抽出方法（コピー＆ペーストできるパターン）：

# 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}]'

段階的な絞り込み： 完全一致のフレーズ → 引用符を外す → tbs=qdr:y を追加 → エンジンを切り替える。

レビューの 2 段階検索： google_maps q="business" → data_id を取得 → google_maps_reviews data_id=<id>。

相互確認： 同じクエリを google_light と bing で検索します。両方の結果が一致すれば、信頼度は高くなります。

インラインで抽出します。 各検索の後、{title, link, snippet} を作業メモに抽出してください。コンテキストの圧縮後も生の検索結果が残っているとは限りません。

その他のパターン：rules/use-cases.md

エラー

Code	意味	対処方法
400	q または engine がありません	必須のパラメーターを追加します。
401	API キーが無効です	serpapi login を実行するか、SERPAPI_KEY=<key from serpapi.com/dashboard> を設定します。同じキーで再試行しないでください。
429	クォータを使い切りました	_light に切り替え、num を減らし、ダッシュボードを確認します。

401 が発生した場合、キーが間違っているか、設定されていません。繰り返し試さず、まず環境変数を修正してください。 課金：成功した検索のみがカウントされます。同じクエリとパラメーターを使うと、1 時間はキャッシュされた結果を無料で利用できます。

参考リンク

• serpapi.com/search-api — API の全ドキュメント
• serpapi.com/search-engine-apis — すべてのエンジン
• serpapi.com/pricing — クレジットとプラン
• github.com/serpapi — SDK、CLI、MCP サーバー