Vertex AI での Google マップを使用したグラウンディング

このページでは、Vertex AI の Google マップによるグラウンディングが、地理空間コンテキストを提供することで生成 AI アプリケーションの強化にどのように役立つかについて説明します。

概要

Vertex AI の「Google マップによるグラウンディング」は、Gemini モデルと Google マップの地理空間データを接続するサービスです。Google マップは、ビジネス、ランドマーク、スポットなど、何百万もの場所に関する情報にアクセスできます。このデータを使用すると、2 億 5,000 万か所以上の場所に関する情報にアクセスして、モデルのレスポンスのグラウンディングに使用できます。これにより、AI アプリケーションとエージェントはローカルデータと地理空間コンテキストを提供できます。

Google マップ、Google 検索、データソースによるグラウンディングを同時に有効にすることもできます。

Google マップによるグラウンディングの用途

Google マップによるグラウンディングは、次のようなさまざまな用途で使用できます。

「イタリアンエスプレッソを飲める一番近い場所はどこ？」など、近くの場所に関する質問に回答できる会話型アシスタント。
「徒歩圏内にあるファミレスについて詳しく教えて」などの、パーソナライズされた説明やコミュニティのインサイト。
EV 充電スタンドやホテルなど、特定の場所の周辺エリアの要約。

これは、不動産、旅行、モビリティ、ソーシャルメディアアプリのユースケースで役立ちます。

Google マップによるグラウンディングのデモを試す

サポートされているモデル

このセクションでは、Google マップによるグラウンディングをサポートするモデルを示します。

Gemini 3 Pro （プレビュー）
Gemini 2.5 Pro
Gemini 2.5 Flash （プレビュー）
Gemini 2.5 Flash-Lite （プレビュー）
Gemini 2.5 Flash
Gemini 2.5 Flash-Lite
Live API ネイティブ音声を使用した Gemini 2.5 Flash （プレビュー）
Live API を使用した Gemini 2.0 Flash （プレビュー）
Gemini 2.0 Flash

Gemini モデルの詳細については、Gemini モデルをご覧ください。

Google マップでグラウンディングを使用してモデルのレスポンスをグラウンディングする

このコードサンプルは、Google マップでグラウンディングを使用して、モデルのレスポンスをグラウンディングする方法を示しています。

緯度と経度の座標を使用して、特定の地理的位置に合わせて検索結果をカスタマイズできます。詳細については、グラウンディング API をご覧ください。

コンソール

Vertex AI で Google マップを使用してグラウンディングを使用する手順は次のとおりです。

Google Cloud コンソールで、Vertex AI Studio のページに移動します。

Vertex AI Studio に移動
[ツール] セクションで、[Grounding: Google] をクリックします。構成ペインが表示されます。
Google マップを使用するには、[Google マップ] 切り替えをクリックします。
[適用] をクリックします。
フィールドにプロンプトを入力し、[送信] をクリックします。プロンプトの回答が Google マップにグラウンディングされます。

Python

インストール

pip install --upgrade google-genai

詳しくは、SDK リファレンスドキュメントをご覧ください。

Vertex AI で Gen AI SDK を使用するための環境変数を設定します。

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    GoogleMaps,
    HttpOptions,
    Tool,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Where can I get the best espresso near me?",
    config=GenerateContentConfig(
        tools=[
            # Use Google Maps Tool
            Tool(google_maps=GoogleMaps(
              enable_widget=False # Optional: return Maps widget token
            ))
        ],
        tool_config=types.ToolConfig(
            retrieval_config = types.RetrievalConfig(
                lat_lng = types.LatLng( # Pass geo coordinates for location-aware grounding
                    latitude=40.7128,
                    longitude=-74.006
                ),
                language_code = "en_US", # Optional: localize Maps results
            ),
        ),
    ),
)

print(response.text)
# Example response:
# 'Here are some of the top-rated places to get espresso near you: ...'

REST

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION: リクエストを処理するリージョン。グローバルエンドポイントを使用するには、エンドポイント名からロケーションを除外し、リソースのロケーションをグローバルに構成します。
PROJECT_ID: 実際のプロジェクト ID。
MODEL_ID: マルチモーダルモデルのモデル ID。
PROMPT: モデルに送信するプロンプト。
LATITUDE: ロケーションの緯度。たとえば、緯度 37.7749 はサンフランシスコを表します。緯度と経度の座標は、Google マップなどのサービスや他のジオコーディングツールを使用して取得できます。
LONGITUDE: ロケーションの経度。たとえば、経度 -122.4194 はサンフランシスコを表します。
ENABLE_WIDGET: トークンを返して Google マップウィジェットを有効にするかどうか（デフォルトは false）。

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

リクエストの本文（JSON）:

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "PROMPT"
    }]
  }],
  "tools": [{
    "googleMaps": {
      "enableWidget": "ENABLE_WIDGET"
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      },
      "languageCode": "en_US"
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout. It has a rating of 4.2 stars based on 411 reviews."
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "groundingChunks": [
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=9001322937822692826",
              "title": "The Italian Place",
              "placeId": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w"
            }
          },
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=9001322937822692826",
              "title": "Hank's Pasta Bar",
              "placeId": "places/MMVtPzn9FGcevML89",
              "placeAnswerSources": {
                "reviewSnippets": [
                  {
                    "id": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w",
                    "title": "Google Maps Review",
                    "uri": "https://maps.google.com/?cid=9001322937822692826"
                  },
                ]
              }
            }
          },
          ...
        ],
        "groundingSupports": [
          {
            "segment": {
              "endIndex": 79,
              "text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout."
            },
            "groundingChunkIndices": [
              0
            ]
          },
        ],
        "googleMapsWidgetContextToken": "widgetcontent/..."
      }
    }
  ],
  ...
}

場所のプロパティ

このセクションでは、場所の説明に使用され、Google マップのグラウンディングでレスポンスの生成に使用される場所のプロパティについて説明します。これらのプロパティは、Google マップによるグラウンディングで回答できる質問のタイプを特定するために使用されます。

場所のプロパティの例

このリストは、モデルがレスポンスの生成に使用できる場所に関するプロパティのアルファベット順のサンプルです。

住所
ピックアップ
デビットカード
距離
無料駐車場
生演奏が楽しめるお店
子供向けメニュー
営業時間
お支払い方法（現金、クレジットカードなど）
場所に関する回答
ペット OK
ビールを出すお店
ベジタリアン料理の提供
車椅子対応
Wi-Fi

場所の回答は、ユーザーのクチコミから得られた情報に基づいて、Google マップによるグラウンディングから得られた回答です。

場所のプロパティの使用例

次の例では、さまざまな種類の場所に関する質問で場所のプロパティを使用しています。Google マップでのグラウンディングでは、プロパティを使用してユーザーの意図を理解し、Google マップの場所に関連付けられたデータに基づいて関連性の高い回答を提供します。

家族での夕食を計画する: 次のように質問してみましょう。「イタリアンプレイス」は子供連れでも大丈夫ですか？テイクアウトはできますか？評価はどのくらいですか？
これらの質問への回答は、レストランが家族連れに適しているかどうか、便利なサービスを提供しているかどうかの判断に役立ちます。
友人のアクセシビリティを確認する: 「車椅子対応の入り口があるレストランを探して」と尋ねます。
このプロンプトに対する回答は、特定のアクセシビリティ要件を満たしているかどうかの判断に役立ちます。
夜食を食べられる場所を探す: 次のように尋ねます。「Burger Joint」は今営業していますか？ディナーは提供していますか？金曜日の営業時間は何時から何時までですか？
これらの質問への回答は、特定の時間に特定の食事を提供する営業中の店舗を探す際に役立ちます。
クライアントとコーヒーを飲む: 次のように尋ねます。「カフェセントラル」に Wi-Fi はありますか？コーヒーは飲めますか？価格帯とクレジットカードの利用可否を教えてください。
これらの質問への回答は、アメニティ、提供内容、支払いオプションに基づいて、仕事の打ち合わせに適したカフェかどうかの評価に役立ちます。

Google マップのグラウンディングされた検索結果の情報は、道路の実際の状況と異なる場合があります。

レスポンスを理解する

Google マップのソースは、groundingChunks 内の groundingMetadata で返されます。場所とユーザーのクチコミのソースが返されます。これらのソースは、Google マップのグラウンディングされた結果の生成に役立ちます。

このコードサンプルは、レスポンス内の場所ソースと場所回答ソースを示しています。

"groundingChunks": [
  {
    "maps": {
      "uri": "{Link to Maps Content}",
      "title": "{Name of Maps Place}",
      "placeId": "{Place ID}",
      "placeAnswerSources": {
        "reviewSnippets" : [
          {
            "reviewId": "{Review ID}",
            "googleMapsUri": "{Link to Maps Content}",
            "title": "{Title of review}"
          }
        ]
      }
    },
  }
],

サービスの使用要件

このセクションでは、Google マップによるグラウンディングのサービス使用要件について説明します。

Google マップのソースの使用についてユーザーに通知する

Google マップのグラウンディングされた結果ごとに、各レスポンスをサポートするソースが groundingChunks で提供されます。次のメタデータも返されます。

ソースの URI
タイトル
ID

Vertex AI の「Google マップによるグラウンディング」の結果を表示する場合は、関連する Google マップのソースを指定し、ユーザーに次の情報を通知する必要があります。

Google マップのソースは、ソースがサポートする生成コンテンツの直後に示す必要があります。この生成されたコンテンツは、Google マップによるグラウンディングの結果ともいいます。
Google マップのソースは、1 回のユーザー操作で表示できる必要があります。

Google マップへのリンクを含む Google マップのソースを表示する

groundingChunks と grounding_chunks.maps.placeAnswerSources.reviewSnippets の各ソースについて、次の要件に沿ってリンクのプレビューを生成する必要があります。

Google マップのテキスト帰属表示のガイドラインに従って、各ソースを Google マップに帰属させます。
レスポンスで提供されたソースのタイトルを表示します。
レスポンスの uri または googleMapsUri を使用してソースにリンクします。

これらの画像は、ソースと Google マップのリンクを表示するための最小要件を示しています。

ソースが表示された回答を含むプロンプト

ソースのビューは折りたたむことができます。

プロンプトと回答、ソースが折りたたまれた状態

省略可: リンクのプレビューを次のような追加コンテンツで強化します。

Google マップのテキスト帰属表示の前に Google マップのファビコンが挿入されます。
ソース URL（og:image）の写真。

Google マップのデータプロバイダとそのライセンス条項について詳しくは、Google マップと Google Earth の法的通知をご覧ください。

Google マップのテキストでの帰属表示に関するガイドライン

テキストでソースを Google マップに帰属させる場合は、次のガイドラインに従ってください。

「Google Maps」というテキストは一切変更しないでください。
- Google Maps の文字の大小は変更しないでください。
- Google Maps を複数行に折り返さないでください。
- Google Maps を他の言語にローカライズしないでください。
- HTML 属性 translate="no" を使用して、ブラウザが Google Maps を翻訳しないようにします。
次の表の説明に従って、Google Maps のテキストのスタイルを設定します。

プロパティ	スタイル
フォントファミリー	Roboto。フォントの読み込みは任意です。
代替フォントファミリー	プロダクトですでに使用されている Sans Serif の本文フォント、またはデフォルトのシステムフォントを呼び出すための Sans-Serif
フォントスタイル	標準
フォントの太さ	400
フォントの色	白、黒（#1F1F1F）、グレー（#5E5E5E）。背景に対してアクセシビリティの高い（4.5:1）コントラストを維持します。
フォントサイズ	最小フォントサイズ: 12sp 最大フォントサイズ: 16sp sp について詳しくは、マテリアルデザインのウェブサイトでフォントサイズの単位をご覧ください。
文字間隔	標準

CSS の例

次の CSS は、白または明るい背景に適切なタイポグラフィスタイルと色で Google Maps をレンダリングします。

@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');

.GMP-attribution {
font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}

コンテキストトークン、場所 ID、レビュー ID

Google マップのデータには、コンテキストトークン、プレイス ID、レビュー ID が含まれます。次のレスポンスデータをキャッシュに保存してエクスポートできます。

googleMapsWidgetContextToken
placeId
reviewId

Google マップによるグラウンディングの利用規約に定められているキャッシュ保存の制限は適用されません。

禁止地域

Google マップでのグラウンディングには、安全で信頼性の高いプラットフォームを維持するため、特定のコンテンツとアクティビティに対する制限があります。ユーザーは、禁止されている地域で Google マップによるグラウンディングを提供する顧客アプリケーションを配布または販売できません。現在の禁止地域は次のとおりです。

中国
クリミア
キューバ
ドネツク人民共和国（自称）
イラン
ルハンスク人民共和国（自称）
北朝鮮
シリア
ベトナム

このリストは随時更新される可能性があります。

コンテキストウィジェットは、他の Google マップコンテンツをサポートまたは補完するために使用されるビジュアルコンテナである Google マップの Pre-GA サービスです。Google マップのコンテキストウィジェットを使用すると、グラウンディングと Google マップをアプリケーションに統合して、会話型 LLM を活用したチャットエクスペリエンスを作成できます。コンテキストウィジェットは、Vertex AI API レスポンスで返されるコンテキストトークン googleMapsWidgetContextToken を使用してレンダリングされます。このトークンは、ビジュアルコンテンツのレンダリングに使用できます。

コンテキストウィジェットは、シナリオに応じてさまざまな機能を果たします。

Google マップのプロンプトが回答の生成に使用されるシナリオで、ユーザーレビューや写真（ユーザー作成コンテンツ、UGC）が表示されます。
Vertex AI がテキストレスポンスのみを生成した場合に、地図の可視化とデータで結果を充実させるのに役立ちます。

コンテキストウィジェットについて詳しくは、マップグラウンディングウィジェットをご覧ください。

Google マップのコンテキストウィジェットをレンダリングして使用するには、ウィジェットを表示するページで Google Maps JavaScript API のアルファ版を使用します。詳しくは、Maps JavaScript API を読み込むをご覧ください。

次のコードサンプルは、コンテキストウィジェットの使用方法を示しています。

コンテキストウィジェットを作成します。

  <body>
   <gmp-place-contextual id="widget"></gmp-place-contextual>
  </body>

Google マップに基づく回答には、コンテキストウィジェットのレンダリングに使用される、対応する googleMapsWidgetContextToken があります。これは、生成された回答の近くに配置されます。

コンテキストトークンを更新するには、widget.contextToken property を設定します。

"googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>...
Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",

function updateWidget(contextToken) {
  let widget = document.querySelector('#widget');
  widget.contextToken = contextToken;
}

省略可: リストのレイアウトを指定します。有効な値は次のとおりです。
- コンパクトレイアウト: <gmp-place-contextual-list-config layout="compact">
- 縦長レイアウト: <gmp-place-contextual-list-config layout="vertical">
このコードサンプルは、リストレイアウトをコンパクトレイアウトに変更する方法を示しています。
```
   <gmp-place-contextual id="widget">
     <gmp-place-contextual-list-config layout="compact">
     </gmp-place-contextual-list-config>
   </gmp-place-contextual>
```
省略可: 地図モードを変更します。有効な値は次のとおりです。
- 2D 道路地図: map-mode="roadmap"
- 3D ハイブリッド地図: map-mode="hybrid"
- 地図なし: map-mode="none"
このコードサンプルは、地図モードを 2D 地図に変更する方法を示しています。
```
   <gmp-place-contextual id="widget">
     <gmp-place-contextual-list-config map-mode="roadmap">
     </gmp-place-contextual-list-config>
   </gmp-place-contextual>
```

次のステップ

Gemini モデルを独自のデータでグラウンディングする方法の詳細については、独自のデータでグラウンディングするをご覧ください。
責任ある AI のベストプラクティスと Vertex AI の安全フィルタについては、責任ある AI をご覧ください。

Vertex AI での Google マップを使用したグラウンディング

概要

Google マップによるグラウンディングの用途

サポートされているモデル

Google マップでグラウンディングを使用してモデルのレスポンスをグラウンディングする

コンソール

Python

インストール

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

場所のプロパティ

場所のプロパティの例

場所のプロパティの使用例

レスポンスを理解する

サービスの使用要件

Google マップのソースの使用についてユーザーに通知する

Google マップへのリンクを含む Google マップのソースを表示する

Google マップのテキストでの帰属表示に関するガイドライン

CSS の例

コンテキストトークン、場所 ID、レビュー ID

禁止地域

省略可: Google マップコンテキストウィジェット

Google マップコンテキストウィジェットをレンダリングする

次のステップ

Vertex AI での Google マップを使用したグラウンディング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

Google マップによるグラウンディングの用途

サポートされているモデル

Google マップでグラウンディングを使用してモデルのレスポンスをグラウンディングする

コンソール

Python

インストール

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

場所のプロパティ

場所のプロパティの例

場所のプロパティの使用例

レスポンスを理解する

サービスの使用要件

Google マップのソースの使用についてユーザーに通知する

Google マップへのリンクを含む Google マップのソースを表示する

Google マップのテキストでの帰属表示に関するガイドライン

CSS の例

コンテキスト トークン、場所 ID、レビュー ID

禁止地域

省略可: Google マップ コンテキスト ウィジェット

Google マップ コンテキスト ウィジェットをレンダリングする

次のステップ

Vertex AI での Google マップを使用したグラウンディング

コンテキストトークン、場所 ID、レビュー ID

省略可: Google マップコンテキストウィジェット

Google マップコンテキストウィジェットをレンダリングする