このページは Cloud Translation API によって翻訳されました。

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 2.5 Flash （プレビュー）
Gemini 2.5 Flash-Lite （プレビュー）
Gemini 2.5 Flash-Lite
Live API ネイティブ音声を使用した Gemini 2.5 Flash （プレビュー）
Live API を使用した Gemini 2.0 Flash （プレビュー）
Gemini 2.5 Pro
Gemini 2.5 Flash
Gemini 2.0 Flash

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

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

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

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

コンソール

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

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

Vertex AI Studio に移動
[ツール] セクションで、[グラウンディング: 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 マップによるグラウンディングで回答できる質問のタイプを特定するために使用されます。

場所のプロパティの例

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

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

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

プレイスプロパティの使用例

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

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

Google マップの Grounded Results の情報は、道路の実際の状況と異なる場合があります。

レスポンスを理解する

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}"
          }
        ]
      }
    },
  }
],

サービスの使用要件

このセクションでは、Grounding with Google Maps のサービス使用要件について説明します。

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

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

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

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

CSS の例

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

@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 マップコンテキストウィジェットをレンダリングする