結論先說
- 開啟只需在
tools掛載GoogleMaps工具:模型檢測到提示詞含有地理位置、商圈、距離或門店設施意圖時,會自動檢索 Google Maps 超 2.5 億個真實地點庫,無需你手動拼裝複雜的 Places REST API 查詢參數。 - 涉及「附近 / 步行十分鐘內」提問時必須傳
lat_lng經緯度:通過ToolConfig裏的RetrievalConfig傳入用戶當前座標,模型才能以真實位置為圓心篩選周邊商戶。 - 從
grounding_chunks提取結構化門店連結與place_id:返回體除自然語言介紹外,還在grounding_metadata中附帶每個引用地點的真實店名、地圖跳轉uri與唯一place_id。 - 支持與 Google Search 聯網搜尋同時開啟:一個管真實營業時間、評分與用戶評價摘要,一個管近期臨時封路、音樂節或新店快閃新聞,互補覆蓋本地生活場景。
- 谷歌開發帳號與主力編程會員入口:在 Google AI Studio 與 Cloud 控制檯調試地圖接地需準備個人谷歌帳號,缺號可查看本站 谷歌帳號購買說明(含即買即發的 谷歌電郵成品號),跨平台主力編程會員總覽見 AI 會員充值中心。

圖:本站根據 Google Gemini API 文檔:Grounding with Google Maps 整理的示意圖
本文根據 Google Gemini API 官方文檔《Grounding with Google Maps》《Gemini Developer API Pricing》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Google 官方網站。
適用於誰
- 開發出境旅遊行程助手、酒店周邊推薦、房產配套分析或線下門店選址問答產品的團隊;
- 直接讓純文本大模型推薦餐廳時,頻繁遇到「早已倒閉的老店、張冠李戴的營業時間或憑空捏造的地址」的人;
- 想在拿到自然語言推薦的同時,提取標準
place_id與地圖直鏈渲染成可點擊店鋪卡片的前端與全棧工程師。
一、Python 代碼示例:掛載 google_maps 與傳入當前經緯度
先確保本機已安裝官方 google-genai SDK(安裝與密鑰配置見 Gemini API Python 調用教學;若你在對比個人開發者端與企業雲端的差異,可參閱 Google AI Studio 和 Vertex AI 的 Gemini API 有什麼區別)。
完整帶座標偏置的周邊檢索代碼如下:
python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="推薦附近步行 15 分鐘內、週末上午 9 點營業且適合帶筆記本辦公的安靜咖啡館。",
config=types.GenerateContentConfig(
tools=[types.Tool(google_maps=types.GoogleMaps(enable_widget=True))],
tool_config=types.ToolConfig(
retrieval_config=types.RetrievalConfig(
lat_lng=types.LatLng(latitude=35.6580, longitude=139.7016)
)
),
),
)
print(response.text)
如果不傳 retrieval_config 裏的經緯度,只要你在提示詞正文寫清明確地標(例如「東京澀谷站周邊」或「舊金山聯合廣場附近」),模型同樣能從文本中識別地理中心並觸發地圖接地。
二、解析 place_id、地圖連結與交互掛件令牌
只把模型生成的純文本直接貼到介面上不夠直觀,通過遍歷 grounding_metadata,你可以把每個推薦地點做成帶跳轉連結的卡片(對比普通網頁搜尋的元數據格式見 Gemini API 聯網搜尋怎麼調):
python
meta = response.candidates[0].grounding_metadata
if meta and meta.grounding_chunks:
for chunk in meta.grounding_chunks:
if chunk.maps:
print(f"店名: {chunk.maps.title}")
print(f"Place ID: {chunk.maps.place_id}")
print(f"地圖直鏈: {chunk.maps.uri}")
if meta and meta.google_maps_widget_context_token:
print("前端地圖組件令牌已返回,可傳給 <gmp-place-contextual> 渲染")
這裏有兩個關鍵工程細節需要留意:
- 合規展示來源歸屬(Attribution):按 Google Maps Grounding 服務條款規定,面向終端用戶展示基於地圖接地生成的商戶詳情、評論摘要或評分時,必須在對應位置清晰展示可點擊的 Google Maps 來源連結(即
chunk.maps.uri),或者在前端加載 Maps JavaScript API 的<gmp-place-contextual>組件傳入google_maps_widget_context_token渲染官方卡片。 - 與
google_search聯合使用:當用戶問「今晚去某某體育館看演唱會,散場後晚上 11 點周邊還有哪些營業的拉麵店」時,可在tools列表同時放入GoogleMaps()與GoogleSearch(),讓模型先通過網頁搜尋核實演唱會散場時間,再用地圖工具篩深夜營業門店。
谷歌開發帳號與全棧編程訂閱提示:開通 AI Studio 與地圖相關雲服務需要狀態正常的個人谷歌帳號,若註冊受阻可在本站選購已配好兩步驗證的 谷歌電郵成品號(詳見 谷歌帳號購買頁);編寫前端地圖卡片與行程規劃邏輯時,還可搭配免境外卡開通的 Claude Code 或 ChatGPT Plus。

圖:本站根據 Google Gemini API 文檔:Grounding with Google Maps 整理的示意圖
三、計費口徑與不適合交給地圖接地的場景
在成本控制方面,地圖接地與聯網搜尋類似,屬於在常規輸入輸出 Token 之外獨立核算的官方接地工具(最新免費請求配額與每千次請求單價請以 Gemini API 價格說明 與官方 Pricing 頁面為準):
- 只有實際觸發地圖檢索才計工具次數:同一對話裏用戶先問「去日本旅遊帶什麼插頭轉換器」,模型無需查地圖,不計接地調用;下一句追問「京都站旁有哪些高分宇治抹茶店」才會觸發計次。
- 不替代毫秒級實時路況導航與打車計價接口:Google Maps Grounding 的強項是基於海量評論、設施標籤與營業時間做多條件自然語言篩選與行程推理;如果你需要做精確到秒的駕車轉向導航(Turn-by-turn)或成百上千個配送點的矩陣路徑規劃,仍應直接調用 Google Maps Platform 的 Routes API。
常見問題
問:我已經傳了 google_maps 工具,為什麼返回對象的 grounding_chunks 是空的?
答:首先檢查提問是否包含明確的地點、商戶或距離訴求;其次確認所選模型版本在官方支持矩陣內(部分極早期快照或純代碼模型不支持地圖接地);最後核查提問區域是否在 Google Maps POI 正常覆蓋範圍內。
問:拿到的 place_id 可以存進我們自己的業務數據庫長期緩存嗎?
答:Google Maps 平台條款通常允許長期存儲純粹的 place_id 字符串以便後續重新定位該地點,但對於接口返回的商戶名稱、評分、評論文本與經緯度等具體內容,一般有嚴格的緩存有效期限與不得用於脫離 Google 生態重建競品圖庫的條款約束,上線前請務必核對官方服務條款。
問:開啟地圖接地時還能同時傳自定義業務 Function Calling 嗎?
答:在較新的 Gemini 模型與 SDK 中已逐步支持內置接地工具與自定義函數的組合編排,若你的具體模型版本報工具類型衝突,可將流程拆為兩步:第一步先調地圖接地拿到候選門店與 place_id,第二步再調內部預訂或庫存函數。
問:國內沒有外幣卡怎麼買谷歌帳號或訂閱 Claude、ChatGPT 會員輔助開發,支持開報銷發票嗎?
答:可前往本站 谷歌帳號購買頁、Claude Code 充值頁 或 AI 會員充值總覽 下單,支持支付寶、微信支付與 AlipayHK,會員訂閱支持免交帳號密碼的自助卡密兌換,企業採購支持開具國內增值稅發票;實時價格與售後邊界(掉訂閱按剩餘天數折退,封號不在質保範圍)以各商品頁說明為準。
相關教學
- Gemini API 聯網搜尋(Grounding with Google Search)怎麼調
- Gemini API Python 調用教學:安裝 google-genai SDK 與多輪對話
- Google AI Studio 和 Vertex AI 的 Gemini API 有什麼區別
- Gemini API 價格:各模型每百萬 tokens 多少錢、免費層和付費層差在哪
參考資料
- Google Gemini API 官方文檔:Grounding with Google Maps — https://ai.google.dev/gemini-api/docs/maps-grounding
- Google Gemini API 官方文檔:Grounding overview — https://ai.google.dev/gemini-api/docs/grounding
- Google Gemini API 官方文檔:Gemini Developer API Pricing — https://ai.google.dev/gemini-api/docs/pricing
0 條評論
還沒有評論,來搶沙發~