透過「利用 Google 地圖建立基準」功能，Gemini 的生成式功能可連結至 Google 地圖豐富、符合事實且最新的資料。開發人員可以輕鬆將位置辨識功能整合至自家應用程式。當使用者查詢的內容與地圖資料相關時，Gemini 模型會利用 Google 地圖提供準確且最新的答案，並與使用者指定的確切位置或大概區域相關。
- 準確的地理位置感知回覆：針對特定地理位置的查詢，運用 Google 地圖的豐富最新資料。
- 強化個人化功能：根據使用者提供的地點，量身打造推薦內容和資訊。
- 情境資訊和小工具：情境權杖，可與生成的內容一起顯示互動式 Google 地圖小工具。
開始使用
本範例說明如何在應用程式中整合利用 Google 地圖建立基準，針對使用者查詢提供精確的回覆，並納入位置資訊。提示會要求提供當地建議，並可選擇提供使用者位置資訊，讓 Gemini 模型使用 Google 地圖資料。
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="What are the best Italian restaurants within a 15-minute walk from here?",
tools=[{
"type": "google_maps",
"latitude": 34.050481,
"longitude": -118.248526
}]
)
# Print the model's text response and annotations
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
if content_block.annotations:
print("\nSources:")
for annotation in content_block.annotations:
if annotation.type == "place_citation":
print(f" - {annotation.name}: {annotation.url}")
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const interaction = await ai.interactions.create({
model: "gemini-3-flash-preview",
input: "What are the best Italian restaurants within a 15-minute walk from here?",
tools: [{
type: "google_maps",
latitude: 34.050481,
longitude: -118.248526
}]
});
// Print the model's text response and annotations
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const contentBlock of step.content) {
if (contentBlock.type === 'text') {
console.log(contentBlock.text);
if (contentBlock.annotations) {
console.log("\nSources:");
for (const annotation of contentBlock.annotations) {
if (annotation.type === 'place_citation') {
console.log(` - ${annotation.name}: ${annotation.url}`);
}
}
}
}
}
}
}
}
main();
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3-flash-preview",
"input": "What are the best Italian restaurants within a 15-minute walk from here?",
"tools": [{
"type": "google_maps",
"latitude": 34.050481,
"longitude": -118.248526
}]
}'
如何利用 Google 地圖建立基準
利用 Google 地圖建立基準的服務會使用 Maps API 做為基準來源，將 Gemini API 與 Google 地理位置生態系統整合。如果使用者查詢內容包含地理位置資訊，Gemini 模型可以叫用「以 Google 地圖建立基準」工具。模型接著會根據與所提供位置相關的 Google 地圖資料生成回覆。
整個程序通常涵蓋下列工作：
- 使用者查詢：使用者向應用程式提交查詢，可能包含地理位置背景資訊 (例如「附近的咖啡店」、「舊金山的博物館」)。
- 叫用：Gemini 模型辨識出地理位置意圖後，會叫用「利用 Google 地圖建立基準」工具。這項工具可選擇性提供使用者的
latitude和longitude。這項工具是文字搜尋工具，運作方式與在 Google 地圖上搜尋類似，也就是說，系統會使用座標來處理本地查詢 (「我附近」)，而特定或非本地查詢則不太會受到明確位置的影響。 - 資料擷取：「利用 Google 地圖建立基準」服務會查詢 Google 地圖，以取得相關資訊 (例如地點、評論、相片、地址、營業時間)。
- 以擷取資料為基礎生成內容：系統會使用擷取的 Google 地圖資料，輔助 Gemini 模型生成回覆，確保內容符合事實且具關聯性。
- 回覆和註解：模型會傳回文字回覆，並附上連結至 Google 地圖來源的內嵌註解，方便開發人員顯示引用內容，並視需要算繪情境式 Google 地圖小工具。
使用 Google 地圖建立基準的原因與時機
如果應用程式需要準確、最新且特定地點的資訊，就非常適合使用「利用 Google 地圖建立基準」功能。這項功能會根據 Google 地圖全球超過 2.5 億個地點的龐大資料庫，提供相關且個人化的內容，提升使用者體驗。
如果應用程式需要執行下列操作，請使用「利用 Google 地圖建立基準」功能：
- 完整且如實回答特定地區的問題。
- 建構對話式旅遊行程規劃工具和當地導覽。
- 根據位置和使用者偏好 (例如餐廳或商店) 推薦搜尋點。
- 為社群、零售或外送服務打造位置感知體驗。
利用 Google 地圖建立基準，在需要鄰近地區和當前事實資料的應用情境中表現優異，例如尋找「我附近最好的咖啡店」或取得路線。
用途
利用 Google 地圖建立基準可支援各種需要位置資訊的用途。
處理地點相關問題
詳細詢問特定地點的問題，根據 Google 使用者評論和其他地圖資料取得解答。
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",
tools=[{
"type": "google_maps",
"latitude": 34.050481,
"longitude": -118.248526
}]
)
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
if content_block.annotations:
print("\nSources:")
for annotation in content_block.annotations:
if annotation.type == "place_citation":
print(f" - {annotation.name}: {annotation.url}")
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const interaction = await ai.interactions.create({
model: "gemini-3-flash-preview",
input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",
tools: [{
type: "google_maps",
latitude: 34.050481,
longitude: -118.248526
}]
});
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const contentBlock of step.content) {
if (contentBlock.type === 'text') {
console.log(contentBlock.text);
if (contentBlock.annotations) {
console.log("\nSources:");
for (const annotation of contentBlock.annotations) {
if (annotation.type === 'place_citation') {
console.log(` - ${annotation.name}: ${annotation.url}`);
}
}
}
}
}
}
}
}
main();
提供以位置為準的個人化服務
根據使用者的偏好和特定地理區域提供建議。
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Which family-friendly restaurants near here have the best playground reviews?",
tools=[{
"type": "google_maps",
"latitude": 30.2672,
"longitude": -97.7431
}]
)
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
if content_block.annotations:
print("\nSources:")
for annotation in content_block.annotations:
if annotation.type == "place_citation":
print(f" - {annotation.name}: {annotation.url}")
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const interaction = await ai.interactions.create({
model: "gemini-3-flash-preview",
input: "Which family-friendly restaurants near here have the best playground reviews?",
tools: [{
type: "google_maps",
latitude: 30.2672,
longitude: -97.7431
}]
});
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const contentBlock of step.content) {
if (contentBlock.type === 'text') {
console.log(contentBlock.text);
if (contentBlock.annotations) {
console.log("\nSources:");
for (const annotation of contentBlock.annotations) {
if (annotation.type === 'place_citation') {
console.log(` - ${annotation.name}: ${annotation.url}`);
}
}
}
}
}
}
}
}
main();
協助規劃行程
生成多日行程，提供路線資訊和各種地點的相關資訊，非常適合用於旅遊應用程式。
Python
from google import genai
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."
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=prompt,
tools=[{
"type": "google_maps",
"latitude": 37.78193,
"longitude": -122.40476,
"enable_widget": True
}]
)
# ... code to process response and widget token
JavaScript
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: '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: [{
type: "google_maps",
latitude: 37.78193,
longitude: -122.40476,
enableWidget: true
}],
});
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3-flash-preview",
"input": "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": [{
"type": "google_maps",
"latitude": 37.78193,
"longitude": -122.40476,
"enable_widget": true
}]
}'
服務使用規定
本節說明 Grounding with Google Maps 的服務使用規定。
告知使用者 Google 地圖來源的使用情形
對於每個 Google 地圖的「基礎」結果，您都會在 model_output步驟的內容區塊中收到來源註解，這些註解支援每個回覆。系統會傳回下列中繼資料：
- 來源網址
- 名稱
呈現利用 Google 地圖建立基準的結果時，您必須指定相關聯的 Google 地圖來源，並告知使用者下列事項：
- Google 地圖來源必須緊接在來源支援的生成內容後方。這類生成的內容也稱為 Google 地圖基礎結果。
- Google 地圖來源必須在一次使用者互動中顯示。
顯示 Google 地圖來源和 Google 地圖連結
系統必須按照下列規定，為每個來源註解產生連結預覽畫面：
- 請按照 Google 地圖文字出處資訊規範，將每個來源歸功於 Google 地圖。
- 顯示回覆中提供的來源名稱。
- 使用註解中的
url連結至來源。
Google 地圖文字出處註明規範
在文字中將來源歸功於 Google 地圖時，請遵循下列準則：
- 請勿以任何方式修改「Google 地圖」文字：
- 請勿變更 Google 地圖的英文大小寫。
- 請勿將 Google 地圖換行。
- 請勿將 Google 地圖本地化為其他語言。
- 使用 HTML 屬性 translate="no"，禁止瀏覽器翻譯 Google 地圖。
如要進一步瞭解部分 Google 地圖資料供應商及其授權條款，請參閱 Google 地圖和 Google 地球法律聲明。
最佳做法
- 提供使用者位置資訊：如要獲得最相關的個人化回覆，請在使用者位置資訊已知的情況下，一律在
google_maps工具設定中加入latitude和longitude。 - 算繪 Google 地圖情境小工具：情境小工具是使用情境權杖
google_maps_widget_context_token算繪，該權杖會隨 Gemini API 回應傳回，可用於算繪 Google 地圖的視覺內容。 - 告知使用者：清楚告知使用者系統會使用 Google 地圖資料回答查詢，尤其是在啟用這項工具時。
- 在不需要時關閉：根據預設，利用 Google 地圖建立基準的功能會關閉。只有在查詢有明確的地理位置脈絡時，才啟用這項功能 (
"tools": [{"type": "google_maps"}])，以提升效能並節省費用。
限制
- 利用 Google 地圖建立基準目前僅支援英文提示和回覆。
- 這項工具可能僅適用於部分地區。
- 結果可能因位置準確度和可用的 Google 地圖資料而異。
- 地理範圍：利用 Google 地圖建立基準的服務已在全球推出。
- 預設狀態：「利用 Google 地圖建立基準」工具預設為關閉。 您必須在 API 要求中明確啟用這項功能。
定價與頻率限制
利用 Google 地圖建立基準的價格取決於查詢次數。目前的費率為 每 1,000 個已建立基準的提示詞$25 美元。免費方案也提供每天最多 500 次的要求。只有在提示成功傳回至少一個 Google 地圖基礎結果 (即結果包含至少一個 Google 地圖來源) 時，要求才會計入配額。如果單一要求傳送多個查詢至 Google 地圖，系統會將其計為一項要求，並計入速率限制。
如需詳細定價資訊，請參閱 Gemini API 定價頁面。
支援的模型
下列模型支援「利用 Google 地圖建立基準」：
| 型號 | 利用 Google 地圖建立基準 |
|---|---|
| Gemini 3.1 Pro 預先發布版 | ✔️ |
| Gemini 3.1 Flash-Lite | ✔️ |
| Gemini 3.1 Flash-Lite 預先發布版 | ✔️ |
| Gemini 3 Flash 預先發布版 | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
| Gemini 2.0 Flash | ✔️ |
支援的工具組合
Gemini 3 模型支援結合內建工具 (例如 Google 地圖的基礎功能) 和自訂工具 (函式呼叫)。詳情請參閱「工具組合」頁面。