结论先说
- 开启只需在
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 条评论
还没有评论,来抢沙发~