Interactions API 現已正式發布。建議使用這個 API，存取所有最新功能和模型。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

利用 Google 地圖建立基準

利用 Google 地圖建立基準，讓 Gemini 的生成式功能連結至 Google 地圖豐富、真實且最新的資料。這項功能可讓開發人員輕鬆將位置資訊感知功能整合至應用程式。如果使用者查詢的內容與地圖資料相關，Gemini 模型會利用 Google 地圖提供準確且即時的答案，並與使用者指定的所在位置或一般區域相關。

準確的地理位置感知回覆：針對特定地理位置的查詢，運用 Google 地圖豐富且最新的資料。
強化個人化功能：根據使用者提供的所在位置，量身打造推薦內容和資訊。

開始使用

本範例說明如何將 Grounding with Google Maps 整合至應用程式，根據使用者查詢提供準確的回覆，並加入位置資訊。提示會要求提供當地建議，並可選用使用者位置資訊，讓 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-3.8-flash',
    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/genai";

const ai = new GoogleGenAI({});

async function generateContentWithMapsGrounding() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-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-3.8-flash: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。這項工具是文字搜尋工具，運作方式與在 Google 地圖上搜尋類似，也就是說，本地查詢 (「附近的」) 會使用座標，而特定或非本地查詢則不太可能受到明確位置的影響。
資料擷取：「利用 Google 地圖建立基準」服務會查詢 Google 地圖，找出相關資訊 (例如地點、評論、相片、地址、營業時間)。
以資料為基準生成內容：系統會使用擷取的 Maps 資料，做為 Gemini 模型回覆的依據，確保內容符合事實且具關聯性。
回覆：模型會傳回文字回覆，其中包含 Google 地圖來源的引用內容。

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

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

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

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

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

API 方法和參數

透過 Gemini API，您可以使用 generateContent 方法，將 Google 地圖做為工具建立基準。如要啟用及設定利用 Google 地圖建立基準，請在要求的 tools 參數中加入 googleMaps 物件。

JSON

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

此外，這項工具也支援將情境位置資訊做為 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"
        ]
      }
    }
  ]
}

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

groundingChunks：包含 maps 來源 (uri、placeId 和 title) 的物件陣列。
groundingSupports：要將模型回應文字連結至 groundingChunks 中來源的區塊陣列。每個區塊都會將文字範圍 (由 startIndex 和 endIndex 定義) 連結至一或多個 groundingChunkIndices。這是建構內文引文的關鍵。

如需顯示如何以文字呈現文內引用的程式碼片段，請參閱「以 Google 搜尋強化事實基礎」文件中的範例。

用途

「利用 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-3.8-flash',
    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-3.8-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-3.8-flash: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-3.8-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-3.8-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-3.8-flash: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}
    }
  }
}'

協助規劃行程

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

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-3.8-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 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})')

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-3.8-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {}}],
      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})`);
        }
      }
    }
  }
}

run();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash: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": {}}],
  "toolConfig": {
    "retrievalConfig": {
    "latLng": {"latitude": 37.78193, "longitude": -122.40476}
  }
  }
}'

服務使用規定

本節說明使用「透過 Google 地圖定位」服務的相關規定。

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

每則 Google 地圖基礎結果都會附上來源，groundingChunks以佐證回覆內容。系統也會傳回下列中繼資料：

來源 URI
title
ID

呈現利用 Google 地圖建立基準的結果時，您必須指定相關聯的 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 內文，或「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。您可能會快取、儲存及匯出下列回覆資料：

placeId
reviewId

《利用 Google 地圖建立基準服務條款》的快取限制不適用。

禁止的活動和地域

利用 Google 地圖建立基準時，某些內容和活動會受到額外限制，以維護安全可靠的平台。除了《條款》中的使用限制外，您也同意不從事下列行為：

您不會將「運用 Google 地圖建立基準」功能用於高風險活動，包括緊急應變服務。
您不會在禁止地區發布或行銷應用程式，透過 Google 地圖提供 Grounding 服務。詳情請參閱「Google Maps Platform 禁止地域」一文。禁止發布內容的地區清單可能會不時更新。

最佳做法

提供使用者位置資訊：如要取得最相關的個人化回覆，請在知道使用者位置資訊時，務必在 googleMapsGrounding 設定中加入 user_location (經緯度)。
告知使用者：清楚告知使用者系統會使用 Google 地圖資料回答查詢，尤其是在啟用這項工具時。
監控延遲時間：如果是對話式應用程式，請確保有根據的回覆的 P95 延遲時間維持在可接受的門檻內，以維持流暢的使用者體驗。
在不需要時關閉：預設會關閉利用 Google 地圖建立基準的功能。只有在查詢有明確的地理位置脈絡時，才啟用這項功能 ("tools": [{"googleMaps": {}}])，以提升效能並節省費用。

限制

適用地區：利用 Google 地圖建立基準的功能已在全球推出
支援的機型：請參閱「支援的機型」一節。
多模態輸入/輸出：目前「利用 Google 地圖建立基準」功能不支援文字以外的多模態輸入或輸出內容。
預設狀態：「利用 Google 地圖建立基準」工具預設為關閉。您必須在 API 要求中明確啟用這項功能。

價格和頻率限制

利用 Google 地圖建立基準的定價會因模型生成方式而異：

Gemini 3 和更新的模型：系統會針對模型決定執行的每項搜尋查詢向專案收費，所有 Gemini 3 和更新的模型每月共用 5,000 次免費要求，之後每 1,000 次搜尋查詢的費用為 $14 美元。單一搜尋提示 (您對模型發出的 API 要求) 可能會導致模型執行多項搜尋查詢，以找出必要資訊。這些查詢都會計為工具的付費使用次數。
Gemini 2.5 和舊版模型：系統會根據搜尋提示向專案收費 (每 1,000 個基礎提示 $25 美元)。只有在提示成功傳回至少一個 Google 地圖錨定結果時，才會針對要求收費，無論模型在內部執行多少個別搜尋查詢來取得該結果，皆是如此。

「利用 Google 地圖建立基準」的配額通常與基礎 Gemini 模型的頻率限制一致。如需詳細的定價資訊，請參閱 Gemini API 定價頁面。

支援的模型

下列機型支援「利用 Google 地圖建立基準」：

模型	利用 Google 地圖建立基準
Gemini 3.8 Flash	✔️
Gemini 3.6 Flash	✔️
Gemini 3.5 Flash-Lite	✔️
Gemini 3.1 Pro 預先發布版	✔️
Gemini 3.1 Flash-Lite	✔️
Gemini 3 Flash 預先發布版	✔️
Gemini 2.5 Pro	✔️
Gemini 2.5 Flash	✔️
Gemini 2.5 Flash-Lite	✔️

支援的工具組合

您可以搭配使用「利用 Google 地圖建立基準」功能與其他內建工具，例如「以 Google 搜尋強化事實基礎」功能 (支援 Gemini 3.5 Flash-Lite 和後續版本)，處理更複雜的使用情境。Gemini 3 模型也支援將這些內建工具與自訂工具 (函式呼叫) 結合使用。詳情請參閱「工具組合」頁面。

後續步驟

請參閱 Gemini API 教戰手冊中的「以 Google 搜尋強化事實基礎」一節。
瞭解其他可用工具。
如要進一步瞭解負責任的 AI 最佳做法和 Gemini API 的安全篩選器，請參閱安全設定指南。