Gemini API グラウンディング groundingMetadata 引用元実装ガイド

Gemini API グラウンディング groundingMetadata 引用元実装ガイド

この記事の結論: Gemini APIでgoogle_searchツールを有効化すると、レスポンスのcandidates[].groundingMetadataにgroundingChunks（引用元URL一覧）とgroundingSupports（回答文のどの範囲がどのチャンクに対応するかを示すインデックス）が返ります。この2つをendIndexの降順で走査してMarkdownリンクを差し込むだけで、Python・Node.js双方で引用元付き回答を組み立てられます。ただしsearchEntryPoint.renderedContent（Search Suggestions）の表示は利用規約上の必須事項であり、省略するとポリシー違反になる点に注意が必要です。

最終更新日: 2026年7月12日

はじめに

Gemini APIでチャットボットや検索アシスタントを実装していて、「回答は返ってくるのに、どのURLを根拠にしたのか分からない」「Perplexityのような脚注付き引用をGeminiでも再現したい」と詰まった経験がある開発者は多いはずです。原因の多くは、groundingMetadataというレスポンスフィールドの構造を正しく読み解けていないことにあります。公式ドキュメントはリファレンス的な記述が中心で、実際にPythonやNode.jsで引用元URLを1本ずつ取り出し、回答文中に脚注として埋め込むところまでのコード例は意外と見つかりにくいのが実情です。本記事では、Gemini APIのgoogle_searchツールを有効化する実装から、groundingChunks・groundingSupports・webSearchQueries・searchEntryPointの各フィールドの意味、そして実際に引用元URLを抽出してMarkdownリンク化するコードまでを、公式ドキュメントの記述に基づいて順に解説します。あわせて、Search Suggestionsの表示義務や課金体系、LLMO（大規模言語モデル最適化）の観点で自社ドメインの引用状況を監視する応用まで扱います。

グラウンディング（Grounding with Google Search）とは何か

Grounding with Google Searchは、Gemini APIが回答を生成する際にGoogle検索の結果を参照し、その根拠となった情報源をレスポンスに含める機能です。モデルが「この質問には最新情報や事実確認が必要」と判断すると、内部的に1件または複数の検索クエリを自動生成し、検索結果を取得したうえで回答文を組み立てます。開発者はこのプロセスを個別に制御することはできず、google_searchツールを有効にするかどうかだけを指定します。

従来のgoogle_search_retrieval（Gemini 1.5系）は非推奨となっており、Gemini 2.0以降のモデルではgoogle_searchツールへの統一が進んでいます。両者は名前が似ているため混同されがちですが、現行のGoogle GenAI SDK（google-genai / @google/genai）を使う場合はgoogle_search一択と考えてよく、旧SDK・旧モデル向けのレガシーコードを流用する際は名称の違いに注意してください。

グラウンディングを使う最大のメリットは、モデルの学習データの鮮度に依存せず最新情報を回答に反映できる点と、レスポンスに引用元が構造化データとして付与されるため、フロントエンドで機械的に脚注表示を実装できる点です。RAG（検索拡張生成）を自前で構築する場合と違い、検索の実行・要約・根拠の紐付けまでをGemini側が一括処理してくれるのが特徴です。

google_searchツールを有効化する実装

Gemini APIでグラウンディングを使うには、generateContent呼び出し時のtoolsにグラウンディングツールを1つ渡すだけです。Python・Node.jsそれぞれの最小実装は以下の通りです。

Python（google-genai SDK）

import os
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)

config = types.GenerateContentConfig(
    tools=[grounding_tool],
    temperature=0.2,
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="2026年時点でのGemini APIのグラウンディング課金体系を教えて",
    config=config,
)

print(response.text)
print(response.candidates[0].grounding_metadata)

Node.js（@google/genai SDK）

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const groundingTool = { googleSearch: {} };

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "2026年時点でのGemini APIのグラウンディング課金体系を教えて",
  config: {
    tools: [groundingTool],
    temperature: 0.2,
  },
});

console.log(response.text);
console.log(JSON.stringify(response.candidates[0].groundingMetadata, null, 2));

注意点として、Python SDKはsnake_case（grounding_metadata）、Node.js SDKはcamelCase（groundingMetadata）でフィールド名が返る点が異なります。REST APIを直接叩く場合はcamelCaseが正です。またtools配列にグラウンディングツールと関数呼び出し（Function Calling）を同時に指定できるモデル・組み合わせもありますが、対応可否はモデルバージョンによって異なるため、実装前に使用モデルのドキュメントを確認してください。

groundingMetadataの構造を理解する

google_searchが有効な状態でレスポンスが返ると、candidates[0].groundingMetadata（REST/Node.js表記。Python SDKではgrounding_metadata）に以下のフィールドが含まれます。

さらに掘り下げると、groundingChunksの各要素は次の形をしています。

{
  "web": {
    "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/xxxxx",
    "title": "ai.google.dev"
  }
}

uriはGoogle側のリダイレクトURLになっており、直接そのページのURLそのものではありません。これはクリック計測や検索結果の鮮度管理のためで、リダイレクト先が最終的な情報源のドメインです。titleはページタイトルではなく、ドメイン名（例: ai.google.dev）が入ることが多い点も実装時に混乱しやすいポイントです。

groundingSupportsの各要素は次のような形です。

{
  "segment": {
    "startIndex": 45,
    "endIndex": 128,
    "text": "Gemini 2.5以降のグラウンディングは1クエリごとに課金される仕組みに変わった"
  },
  "groundingChunkIndices": [0, 2],
  "confidenceScores": [0.92, 0.78]
}

• segment.startIndex / endIndex: 回答テキスト（response.text）中の文字インデックス。この範囲の主張が、紐づくチャンクによって裏付けられていることを示す
• groundingChunkIndices: groundingChunks配列内の該当インデックス。複数の情報源が1つの主張を裏付けることもある
• confidenceScores: 0.0〜1.0のスコアで、該当チャンクがその主張をどれだけ強く支持しているかを示す相対値

つまりグラウンディングは「ページ全体を参照した」という粗い単位ではなく、「回答文の特定の一文（セグメント）が、特定のチャンクによって裏付けられている」という文単位の対応関係を返す仕組みです。この粒度を理解しておくと、後述する引用抽出コードの実装意図が理解しやすくなります。

引用元URLを抽出する実装（Python）

groundingSupportsとgroundingChunksから、回答文中に脚注番号付きの引用リンクを埋め込む実装例です。文字インデックスがずれないよう、endIndexの降順（後ろから）で文字列に挿入するのがポイントです。

def add_citations(response):
    text = response.text
    supports = response.candidates[0].grounding_metadata.grounding_supports
    chunks = response.candidates[0].grounding_metadata.grounding_chunks

    # end_indexの降順でソートし、後ろから挿入することで
    # 挿入のたびにインデックスがずれる問題を回避する
    sorted_supports = sorted(
        supports, key=lambda s: s.segment.end_index, reverse=True
    )

    for support in sorted_supports:
        end_index = support.segment.end_index
        if not support.grounding_chunk_indices:
            continue

        citation_links = []
        for i in support.grounding_chunk_indices:
            if i < len(chunks):
                uri = chunks[i].web.uri
                citation_links.append(f"[{i + 1}]({uri})")

        citation_string = ", ".join(citation_links)
        text = text[:end_index] + citation_string + text[end_index:]

    return text


response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Gemini APIのグラウンディング課金体系の変更点は?",
    config=config,
)

print(add_citations(response))

出典URLとタイトルの一覧を別途テーブルとして出したい場合は、groundingChunksをそのままループするだけで作れます。

def build_source_list(response):
    chunks = response.candidates[0].grounding_metadata.grounding_chunks
    sources = []
    for idx, chunk in enumerate(chunks):
        sources.append({
            "index": idx + 1,
            "title": chunk.web.title,
            "uri": chunk.web.uri,
        })
    return sources

引用元URLを抽出する実装（Node.js）

Node.jsでも考え方は同じです。groundingSupportsをendIndexの降順でソートし、後ろから文字列に脚注リンクを挿入します。

function addCitations(response) {
  let text = response.text;
  const metadata = response.candidates[0].groundingMetadata;
  const supports = metadata?.groundingSupports ?? [];
  const chunks = metadata?.groundingChunks ?? [];

  const sortedSupports = [...supports].sort(
    (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0)
  );

  for (const support of sortedSupports) {
    const endIndex = support.segment?.endIndex;
    if (endIndex === undefined || !support.groundingChunkIndices?.length) {
      continue;
    }

    const citationLinks = support.groundingChunkIndices
      .map((i) => {
        const uri = chunks[i]?.web?.uri;
        return uri ? `[${i + 1}](${uri})` : null;
      })
      .filter(Boolean);

    const citationString = citationLinks.join(", ");
    text = text.slice(0, endIndex) + citationString + text.slice(endIndex);
  }

  return text;
}

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Gemini APIのグラウンディング課金体系の変更点は?",
  config: { tools: [{ googleSearch: {} }] },
});

console.log(addCitations(response));

TypeScriptで型を厳密にしたい場合、@google/genaiはGroundingMetadata・GroundingChunk・GroundingSupportの型定義をエクスポートしているため、import type { GroundingMetadata } from "@google/genai"のように取り込んで関数の引数に型注釈を付けると実装時の取り違えを防げます。特にwebがundefinedになるケース（マップグラウンディングなど別ソースのチャンクが混在する場合）を型レベルでガードしておくと本番導入時の事故が減ります。

Search Suggestions（検索候補)の表示義務

Grounding with Google Searchを利用する際、見落とされがちなのが「Search Suggestions」の表示義務です。groundingMetadata.searchEntryPoint.renderedContentには、そのままアプリケーションに埋め込める完成済みのHTML/CSSが含まれています。これはユーザーが元の検索結果に遷移できるようにするための仕組みで、Googleのサービス利用規約上、グラウンディングを利用したレスポンスをユーザーに表示するアプリケーションは、このrenderedContentを実際の画面に表示することが必須とされています。

実装上のポイントは以下の通りです。

• renderedContentはライトモード・ダークモード双方に対応したCSS（@media (prefers-color-scheme: dark))を含んだ完成形のHTMLであり、独自にスタイルを大きく上書きすることは想定されていない
• APIレスポンスにボタンやチップ形式の検索候補が含まれるため、dangerouslySetInnerHTML（React）やテンプレートの生HTML描画機能を使って埋め込むのが一般的な実装パターン
• searchEntryPointが存在しない（グラウンディングが発火しなかった）ケースをコード側でハンドリングし、非表示時にエラーにならないようにする

Search Suggestionsを表示せずに引用元URLの抽出結果だけを使う実装は、Google側の利用条件に抵触するリスクがあるため、社内向けの検証環境であっても本番相当のUIを組む際は必ず実装しておくことを推奨します。

エラーハンドリングと制約

グラウンディング関連の実装でつまずきやすいポイントを整理します。

また、グラウンディングは動的検索閾値をAPI利用者側から強制する手段が現行のgoogle_searchツールには用意されていません。「必ず検索させたい」「絶対に検索させたくない」という制御が必要な場合は、プロンプト側で明示的に指示するか、Function Callingで独自の検索処理に置き換える設計を検討してください。

課金体系の確認ポイント

グラウンディングは無料枠を超えると従量課金が発生する機能です。公式のPricingページに基づく大まかな傾向は以下の通りです。

• Gemini 2.5系以前のモデルは「グラウンディングされたプロンプト数」単位で課金され、無料枠を超えると1,000プロンプトあたり定額の追加費用が発生する
• Gemini 3系のモデルは「実行された検索クエリ数」単位の課金に変更されており、1回のプロンプトでモデルが複数クエリを内部生成した場合はその分だけ課金対象が増える
• いずれの世代でも無料枠（月間・日次のいずれか)が用意されているが、金額・上限は変更される可能性があるため、実装前に必ず最新のPricingページで確認する

本番環境に組み込む前に、webSearchQueriesの件数をログに記録しておくと、想定外の課金増加を早期に検知できます。

LLMO監視への応用: groundingMetadataで自社ドメインの引用状況を追う

ここまでは「Gemini APIを使ったアプリケーションを実装する開発者」向けの内容でしたが、LLMO（大規模言語モデル最適化）の観点では、このgroundingMetadataはそのまま「自社サイトがGeminiにどれだけ引用されているか」を定量的に監視するためのデータソースとしても使えます。

具体的な監視実装のアイデアは次の通りです。

1. 自社の主要キーワード・想定質問を一覧化し、定期的にgoogle_searchツール付きでGemini APIにプロンプトを投げる
2. レスポンスのgroundingChunks[].web.uri（リダイレクトURLを展開した先のドメイン)を集計し、自社ドメインが出現した回数・順位（groundingChunkIndices内での位置)を記録する
3. groundingSupportsのconfidenceScoresを見て、自社ページが「強く裏付けに使われている」のか「弱い参考程度」なのかを区別する
4. 競合ドメインの出現頻度と比較し、引用シェアの推移を週次・月次でダッシュボード化する

この手法の利点は、Google Search Consoleのような検索順位ベースの指標では見えない「AI回答内でどう扱われているか」を直接観測できる点です。ただしグラウンディングは同じプロンプトでも毎回同じ検索クエリ・同じ引用元になるとは限らないため、単発の実行結果だけで判断せず、複数回・複数プロンプトのサンプルを取って傾向を見ることが重要です。継続的にログを蓄積し、groundingChunksに自社ドメインが登場しやすい記事構成（一文完結型の主張、FAQ形式、構造化データの整備状況)を分析すれば、コンテンツ改善のフィードバックループとしても活用できます。

よくある質問

Q1. groundingMetadataが返ってこないのはなぜですか?

モデルが「検索による裏付けは不要」と判断した場合、グラウンディングは発火せずgroundingMetadata自体が省略されます。nullチェックが必須です。

Q2. groundingChunksのuriは元記事のURLと同じですか?

異なります。GoogleのリダイレクトURLが返るため、クリックまたは展開しないと最終的な元記事のドメインは確認できません。

Q3. google_search_retrievalとgoogle_searchはどちらを使うべきですか?

現行のGemini 2.0以降・2.5系・3系ではgoogle_searchが推奨です。google_search_retrievalは旧モデル向けの非推奨扱いです。

Q4. groundingSupportsのconfidenceScoresはどう使えばよいですか?

0.0〜1.0の相対値で、値が高いほどそのチャンクが主張を強く裏付けていることを示します。閾値を決めて弱い根拠を除外する用途に使えます。

Q5. Search Suggestionsの表示は省略してもよいですか?

省略は推奨されません。searchEntryPoint.renderedContentの表示はGoogleの利用条件で求められており、非表示運用はポリシー違反のリスクがあります。

Q6. Python SDKとNode.js SDKでフィールド名の書き方が違うのはなぜですか?

Python SDKはPython慣習のsnake_case、Node.js SDKとREST APIはcamelCaseを採用しているためです。両対応の実装では変換層を用意すると安全です。

Q7. 1回のプロンプトで複数の検索クエリが実行されることはありますか?

あります。webSearchQueriesに複数件のクエリが返ることがあり、Gemini 3系ではクエリ単位で課金されるため請求額に影響します。

Q8. グラウンディングとRAG（検索拡張生成)は何が違いますか?

RAGは自前のベクトル検索やデータベースを使う仕組み全般を指し、グラウンディングはGoogle検索を情報源としてGemini側が検索・要約・引用付けまで一括処理する点が異なります。

Q9. Function CallingとGoogle Searchツールは同時に使えますか?

モデルバージョンによって対応可否が異なります。導入前に使用するモデルの公式ドキュメントで組み合わせ可否を確認してください。

関連用語

• グラウンディング
• RAG
• JSON-LD
• 構造化データ
• Schema.org
• ハルシネーション
• LLM
• トークン
• ベクトル検索
• Gemini SEO
• Perplexity
• クエリ

関連記事

• AI検索最適化ガイド
• LLMO完全ガイド
• SEOの基礎知識完全ガイド
• AISEO完全ガイド
• Gemini 3 グラウンディング 検索引用対策の完全ガイド
• マルチモーダルAIクローラーと動画理解最適化
• AIクローラーログ分析: GPTBot・ClaudeBotとGEO
• 構造化データ実装ミスとAI引用への影響