Veo 3.1 登場！如要瞭解新模型及其功能，請參閱網誌文章和說明文件。

本頁面由 Cloud Translation API 翻譯而成。

利用 Google 地圖建立基準

透過「利用 Google 地圖建立基準」功能，Gemini 的生成式功能可連結至 Google 地圖豐富、符合事實且最新的資料。開發人員可以輕鬆將位置辨識功能整合至自家應用程式。當使用者查詢的內容與地圖資料相關時，Gemini 模型會利用 Google 地圖提供準確且即時的答案，並與使用者指定的確切位置或一般區域相關。

準確的地理位置感知回覆：針對特定地理位置的查詢，運用 Google 地圖的廣泛且最新的資料。
強化個人化功能：根據使用者提供的位置資訊，量身打造推薦內容和資訊。
情境資訊和小工具：情境權杖可與生成的內容一起顯示互動式 Google 地圖小工具。

開始使用

這個範例說明如何將 Grounding 與 Google 地圖整合到應用程式中，針對使用者查詢提供精確的回覆，並考量位置資訊。提示會要求提供當地建議，並可選擇提供使用者位置，讓 Gemini 模型運用 Google 地圖資料。

Python

from google import genai
from google.genai import types

client = genai.Client()

prompt = "What are the best Italian restaurants within a 15-minute walk from here?"

response = client.models.generate_content(
    model='gemini-2.5-flash-lite',
    contents=prompt,
    config=types.GenerateContentConfig(
        # Turn on grounding with Google Maps
        tools=[types.Tool(google_maps=types.GoogleMaps())],
        # Optionally provide the relevant location context (this is in Los Angeles)
        tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
            lat_lng=types.LatLng(
                latitude=34.050481, longitude=-118.248526))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in grounding.grounding_chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

JavaScript

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

const ai = new GoogleGenAI({});

async function generateContentWithMapsGrounding() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "What are the best Italian restaurants within a 15-minute walk from here?",
    config: {
      // Turn on grounding with Google Maps
      tools: [{ googleMaps: {} }],
      toolConfig: {
        retrievalConfig: {
          // Optionally provide the relevant location context (this is in Los Angeles)
          latLng: {
            latitude: 34.050481,
            longitude: -118.248526,
          },
        },
      },
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const grounding = response.candidates[0]?.groundingMetadata;
  if (grounding?.groundingChunks) {
    console.log("-".repeat(40));
    console.log("Sources:");
    for (const chunk of grounding.groundingChunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

generateContentWithMapsGrounding();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "What are the best Italian restaurants within a 15-minute walk from here?"
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 34.050481, "longitude": -118.248526}
    }
  }
}'

如何使用 Google 地圖建立基準

透過 Google 地圖進行基礎化作業時，系統會使用 Maps API 做為基礎化來源，將 Gemini API 與 Google 地理位置生態系統整合。如果使用者查詢內容包含地理位置資訊，Gemini 模型可以呼叫「以 Google 地圖建立基準」工具。模型接著會根據與所提供位置相關的 Google 地圖資料，生成回覆。

這項程序通常包括：

使用者查詢：使用者向應用程式提交查詢，可能包含地理位置資訊 (例如「附近的咖啡廳」)。「我附近的咖啡廳」、「舊金山的博物館」)。
工具呼叫：Gemini 模型辨識出地理位置意圖後，會呼叫「使用 Google 地圖建立基準」工具。這項工具可選擇性提供使用者的 latitude 和 longitude，以取得位置資訊相關結果。
資料擷取：「Grounding with Google Maps」服務會查詢 Google 地圖，找出相關資訊 (例如地點、評論、相片、地址、營業時間)。
以擷取的資料為基準生成內容：系統會使用擷取的 Google 地圖資料，輔助 Gemini 模型生成回覆，確保內容符合事實且具關聯性。
回覆和微件權杖：模型會傳回文字回覆，其中包含 Google 地圖來源的引用內容。此外，API 回應也可能包含 google_maps_widget_context_token，開發人員可在應用程式中算繪情境式 Google 地圖小工具，以進行視覺互動。

使用 Google 地圖建立基準的原因與時機

如果應用程式需要準確、最新且特定地點的資訊，就非常適合使用「利用 Google 地圖建立基準」功能。這項功能會根據 Google 地圖全球超過 2.5 億個地點的龐大資料庫，提供相關且個人化的內容，提升使用者體驗。

如果應用程式需要執行下列操作，建議使用「以 Google 地圖建立基準」功能：

完整且如實回答特定地區的問題。
建構對話式旅遊行程規劃工具和當地導覽。
根據位置和使用者偏好 (例如餐廳或商店) 推薦搜尋點。
為社群、零售或外送服務打造位置感知體驗。

在需要鄰近地區和當前事實資料的用途中，Google 地圖基礎模型表現出色，例如尋找「我附近最好的咖啡店」或取得路線。

API 方法和參數

透過 Gemini API，Google 地圖基礎功能會以 generateContent 方法中的工具形式公開。如要啟用及設定 Grounding with Google Maps，請在要求的 tools 參數中加入 googleMaps 物件。

JSON

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": {} }
}

googleMaps 工具還可接受布林值 enableWidget 參數，用於控制是否在回應中傳回 googleMapsWidgetContextToken 欄位。這可用於顯示情境式 Places 小工具。

JSON

{
"contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": { "enableWidget": true } }
}

此外，這項工具也支援將內容相關位置資訊做為 toolConfig 傳遞。

JSON

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near here."}
    ]
  }],
  "tools":  { "googleMaps": {} },
  "toolConfig":  {
    "retrievalConfig": {
      "latLng": {
        "latitude": 40.758896,
        "longitude": -73.985130
      }
    }
  }
}

瞭解基礎回應

如果系統成功以 Google 地圖資料為回覆內容設下限制，回覆內容就會包含 groundingMetadata 欄位。這類結構化資料對於驗證聲明、在應用程式中建立豐富的引用體驗，以及符合服務使用規定而言，都非常重要。

JSON

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "CanteenM is an American restaurant with..."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "groundingChunks": [
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=13100894621228039586",
              "title": "Heaven on 7th Marketplace",
              "placeId": "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
            },
            // repeated ...
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 79,
              "text": "CanteenM is an American restaurant with a 4.6-star rating and is open 24 hours."
            },
            "groundingChunkIndices": [0]
          },
          // repeated ...
        ],
        "webSearchQueries": [
          "restaurants near me"
        ],
        "googleMapsWidgetContextToken": "widgetcontent/..."
      }
    }
  ]
}

Gemini API 會透過 groundingMetadata 傳回下列資訊：

groundingChunks：包含 maps 來源 (uri、placeId 和 title) 的物件陣列。
groundingSupports：要將模型回應文字連結至 groundingChunks 中來源的區塊陣列。每個區塊都會將文字範圍 (由 startIndex 和 endIndex 定義) 連結至一或多個 groundingChunkIndices。這是建立內文引用的關鍵。
googleMapsWidgetContextToken：可用於顯示情境式地點小工具的文字權杖。

如要查看程式碼片段，瞭解如何在文字中算繪內嵌引用內容，請參閱 Google 搜尋基礎功能文件中的範例。

顯示 Google 地圖情境小工具

如要使用傳回的 googleMapsWidgetContextToken，您需要載入 Google 地圖 JavaScript API。

用途

透過 Google 地圖進行基礎定位可支援各種需要位置資訊的用途。以下範例說明如何透過不同的提示和參數，運用 Google 地圖基礎功能。Google 地圖基礎結果中的資訊可能與實際狀況不同。

處理地點相關問題

詢問特定地點的詳細問題，根據 Google 使用者評論和其他地圖資料取得解答。

Python

from google import genai
from google.genai import types

client = genai.Client()

prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?"

response = client.models.generate_content(
    model='gemini-2.5-flash-lite',
    contents=prompt,
    config=types.GenerateContentConfig(
        # Turn on the Maps tool
        tools=[types.Tool(google_maps=types.GoogleMaps())],

        # Provide the relevant location context (this is in Los Angeles)
        tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
            lat_lng=types.LatLng(
                latitude=34.050481, longitude=-118.248526))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if chunks := grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
  ```

JavaScript

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

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?";

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
    config: {
      // Turn on the Maps tool
      tools: [{googleMaps: {}}],
      // Provide the relevant location context (this is in Los Angeles)
      toolConfig: {
        retrievalConfig: {
          latLng: {
            latitude: 34.050481,
            longitude: -118.248526
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
  if (chunks) {
    console.log('-'.repeat(40));
    console.log("Sources:");
    for (const chunk of chunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

run();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 34.050481, "longitude": -118.248526}
    }
  }
}'

提供以位置為依據的個人化服務

根據使用者的偏好和特定地理區域提供建議。

Python

from google import genai
from google.genai import types

client = genai.Client()

prompt = "Which family-friendly restaurants near here have the best playground reviews?"

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=prompt,
    config=types.GenerateContentConfig(
      tools=[types.Tool(google_maps=types.GoogleMaps())],
      tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
          # Provide the location as context; this is Austin, TX.
          lat_lng=types.LatLng(
              latitude=30.2672, longitude=-97.7431))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if chunks := grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

JavaScript

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

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Which family-friendly restaurants near here have the best playground reviews?";

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {}}],
      toolConfig: {
        retrievalConfig: {
          // Provide the location as context; this is Austin, TX.
          latLng: {
            latitude: 30.2672,
            longitude: -97.7431
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
  if (chunks) {
    console.log('-'.repeat(40));
    console.log("Sources:");
    for (const chunk of chunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

run();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Which family-friendly restaurants near here have the best playground reviews?"
    }],
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 30.2672, "longitude": -97.7431}
    }
  }
}'

協助規劃行程

生成多日行程，提供路線資訊和各種地點的相關資訊，非常適合用於旅遊應用程式。

在本例中，使用者在 Google 地圖工具中啟用小工具，因此要求了 googleMapsWidgetContextToken。啟用後，傳回的權杖可用於使用 Google Maps JavaScript API 的 <gmp-places-contextual> component 算繪情境式地點小工具。

Python

from google import genai
from google.genai import types

client = genai.Client()

prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=prompt,
    config=types.GenerateContentConfig(
      tools=[types.Tool(google_maps=types.GoogleMaps(enable_widget=True))],
      tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
          # Provide the location as context, this is in San Francisco.
          lat_lng=types.LatLng(
              latitude=37.78193, longitude=-122.40476))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in grounding.grounding_chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

  if widget_token := grounding.google_maps_widget_context_token:
    print('-' * 40)
    print(f'<gmp-place-contextual context-token="{widget_token}"></gmp-place-contextual>')

JavaScript

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

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.";

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {enableWidget: true}}],
      toolConfig: {
        retrievalConfig: {
          // Provide the location as context, this is in San Francisco.
          latLng: {
            latitude: 37.78193,
            longitude: -122.40476
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const groundingMetadata = response.candidates[0]?.groundingMetadata;
  if (groundingMetadata) {
    if (groundingMetadata.groundingChunks) {
      console.log('-'.repeat(40));
      console.log("Sources:");
      for (const chunk of groundingMetadata.groundingChunks) {
        if (chunk.maps) {
          console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
        }
      }
    }

    if (groundingMetadata.googleMapsWidgetContextToken) {
      console.log('-'.repeat(40));
      document.body.insertAdjacentHTML('beforeend', `<gmp-place-contextual context-token="${groundingMetadata.googleMapsWidgetContextToken}`"></gmp-place-contextual>`);
    }
  }
}

run();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."
    }]
  }],
  "tools": [{"googleMaps": {"enableWidget":"true"}}],
  "toolConfig": {
    "retrievalConfig": {
    "latLng": {"latitude": 37.78193, "longitude": -122.40476}
  }
  }
}'

小工具的算繪結果如下所示：

服務使用規定

本節說明 Grounding with Google Maps 的服務使用規定。

告知使用者 Google 地圖來源的使用情形

每項 Google 地圖基礎結果都會提供groundingChunks 支援各項回覆的來源。系統也會傳回下列中繼資料：

來源 URI
title
ID

呈現「利用 Google 地圖建立基準」的結果時，請務必指定相關聯的 Google 地圖來源，並告知使用者下列事項：

Google 地圖來源必須緊接在來源支援的生成內容後方。這類生成內容也稱為 Google 地圖基礎結果。
Google 地圖來源必須在一次使用者互動中顯示。

顯示 Google 地圖來源和連結

針對 groundingChunks 和 grounding_chunks.maps.placeAnswerSources.reviewSnippets 中的每個來源，必須按照下列規定產生連結預覽畫面：

請按照 Google 地圖文字出處資訊規範，將每個來源歸功於 Google 地圖。
顯示回覆中提供的來源標題。
使用回覆中的 uri 或 googleMapsUri 連結至來源。

這些圖片顯示來源和 Google 地圖連結的最低顯示需求。

提示，並顯示回覆來源

你可以收合來源檢視畫面。

提示、回覆和來源已收合

選用：加入其他內容，例如：

Google 地圖 Favicon 會插入 Google 地圖文字出處之前。
來源網址 (og:image) 中的相片。

如要進一步瞭解部分 Google 地圖資料供應商及其授權條款，請參閱 Google 地圖和 Google 地球法律聲明。

Google 地圖文字出處註明規範

在文字中將來源歸功於 Google 地圖時，請遵循下列準則：

請勿以任何方式修改「Google 地圖」文字：
- 請勿變更 Google 地圖的英文大小寫。
- 請勿將 Google 地圖換行。
- 請勿將 Google 地圖本地化為其他語言。
- 使用 HTML 屬性 translate="no"，禁止瀏覽器翻譯 Google 地圖。
按照下表說明，設定 Google 地圖文字樣式：

屬性	樣式
`Font family`	Roboto。載入字型為選用步驟。
`Fallback font family`	產品中已使用的任何無襯線內文字型，或「Sans-Serif」來叫用預設系統字型
`Font style`	一般
`Font weight`	400
`Font color`	白色、黑色 (#1F1F1F) 或灰色 (#5E5E5E)。與背景維持無障礙 (4.5:1) 對比度。
`Font size`	字型大小下限：12sp 字型大小上限：16sp 如要瞭解 sp，請參閱 Material Design 網站上的「字型大小單位」。
`Spacing`	一般

CSS 範例

下列 CSS 會在白色或淺色背景上，以適當的排版樣式和顏色顯示 Google 地圖。

CSS

@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 地圖的 Grounding 功能。目前禁止的地域如下：

中國
克里米亞
古巴
頓內次克人民共和國
伊朗
盧甘斯克人民共和國
北韓
敘利亞
越南

這份清單可能會不時更新。

最佳做法

提供使用者位置資訊：如要取得最相關的個人化回覆，請在知道使用者位置資訊時，一律在 googleMapsGrounding 設定中加入 user_location (緯度和經度)。
算繪 Google 地圖情境小工具：情境小工具是使用情境權杖 googleMapsWidgetContextToken 算繪，該權杖會隨 Gemini API 回應傳回，可用於算繪 Google 地圖的視覺內容。如要進一步瞭解情境小工具，請參閱 Google 開發人員指南中的「使用 Google 地圖小工具進行基礎作業」。
告知使用者：清楚告知使用者系統會使用 Google 地圖資料回答查詢，特別是啟用這項工具時。
監控延遲時間：如果是對話式應用程式，請確保基礎回應的 P95 延遲時間維持在可接受的門檻內，以維持順暢的使用者體驗。
在不需要時關閉：根據預設，系統會關閉 Google 地圖的基礎功能。只有在查詢具有明確的地理位置情境時，才啟用這項功能 ("tools": [{"googleMaps": {}}])，以提升效能並節省費用。

限制

地理範圍：目前全球都可使用 Google 地圖建立基準。
支援的模型：只有特定 Gemini 模型支援透過 Google 地圖建立基準：Gemini 2.5 Flash-Lite、Gemini 2.5 Pro、Gemini 2.5 Flash 和 Gemini 2.0 Flash (但不包括 2.0 Flash Lite)。
多模態輸入/輸出：目前「利用 Google 地圖建立基準」功能僅支援文字和情境地圖小工具，不支援多模態輸入或輸出。
預設狀態：「利用 Google 地圖建立基準」工具預設為關閉。您必須在 API 要求中明確啟用這項功能。

定價與頻率限制

使用 Google 地圖建立基準的價格是以查詢次數為準。目前的費率為 每 1,000 個已完成基礎提示$25 美元。只有當提示成功傳回至少一項 Google 地圖基礎結果 (即包含至少一項 Google 地圖來源的結果) 時，要求才會計入配額。如果單一要求傳送多個查詢至 Google 地圖，則會計為一項要求，並計入速率限制。

如需詳細定價資訊，請參閱 Gemini API 定價頁面。

支援的模型

如要瞭解模型的功能，請前往模型總覽頁面。

模型	利用 Google 地圖建立基準
Gemini 2.5 Pro	✔️
Gemini 2.5 Flash	✔️
Gemini 2.5 Flash-Lite	✔️
Gemini 2.0 Flash	✔️

後續步驟

請參閱 Gemini API 教戰手冊中的「以 Google 搜尋結果做為回覆依據」一節。
瞭解其他可用工具，例如函式呼叫。
如要進一步瞭解負責任的 AI 最佳做法和 Gemini API 的安全篩選器，請參閱安全設定指南。