Gemini 中文指南
获取 API 密钥 ↗

使用 Google 地图提供事实依据

↓ 下载 Markdown

事实依据与 Google 地图将 Gemini 的生成能力与 Google 地图丰富、真实且最新的数据连接起来。此功能使开发人员能够轻松地将位置感知功能合并到他们的应用程序中。当用户查询具有与地图数据相关的上下文时,Gemini 模型利用 Google 地图提供与用户指定位置或一般区域相关的事实准确且新鲜的答案。

  • 准确、位置感知的响应: 利用 Google 地图广泛的最新数据进行地理特定查询。

  • 增强的个性化: 根据用户提供的位置定制建议和信息。

快速入门 #

此示例演示如何将事实依据与 Google 地图集成到您的应用程序中,以便为用户查询提供准确的、位置感知的响应。该提示要求提供带有可选用户位置的本地建议,使 Gemini 模型能够使用 Google 地图数据。

python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    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}")

事实依据与 Google 地图的工作原理 #

事实依据与 Google 地图通过使用地图 API 作为事实依据源,将 Gemini API 与 Google Geo 生态系统集成。当用户的查询包含地理上下文时,Gemini 模型可以使用 Google 地图工具调用事实依据。然后,该模型可以生成基于与所提供位置相关的 Google 地图数据的响应。

该过程通常涉及:

  1. 用户查询: 用户向您的应用程序提交查询,可能包括地理上下文(例如,“我附近的咖啡店”、“旧金山的博物馆”)。

  2. 工具调用: Gemini 模型识别地理意图,使用 Google 地图工具调用事实依据。该工具可以选择与用户一起提供 latitude 和 longitude。该工具是一种文本搜索工具,其行为类似于在地图上搜索,因为本地查询(“靠近我”)将使用坐标,而特定或非本地查询不太可能受到显式位置的影响。

  3. 数据检索: 事实依据与 Google 地图服务查询 Google 地图的相关信息(例如地点、评论、照片、地址、开放时间)。

  4. 提供事实依据一代: 检索到的地图数据用于告知 Gemini 模型的响应,确保事实准确性和相关性。

  5. 回复及注释: 该模型返回带有链接到 Google 地图源的内联注释的文本响应,允许开发人员显示引用。

为什么以及何时将事实依据与 Google 地图一起使用 #

事实依据和 Google 地图非常适合需要准确、最新和特定位置信息的应用。它通过提供由 Google 地图全球超过 100 万个地点的 250 广泛数据库支持的相关和个性化内容来增强用户体验。

当您的应用程序需要执行以下操作时,您应该将事实依据与 Google 地图一起使用:

  • 对特定地理问题提供完整、准确的答复。

  • 建立对话式旅行计划和当地指南。

  • 根据位置和用户偏好推荐兴趣点,例如餐馆或商店。

  • 为社交、零售或食品配送服务创建位置感知体验。

事实依据和 Google 地图在邻近性和当前事实数据至关重要的用例中表现出色,例如查找“我附近最好的咖啡店”或获取路线。

使用案例 #

事实依据和 Google 地图支持各种位置感知用例。

处理特定地点的问题 #

询问有关特定地点的详细问题,以便根据 Google 用户评论和其他地图数据获得答案。

python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    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}")

提供基于位置的个性化 #

获取根据用户偏好和特定地理区域量身定制的建议。

python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    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}")

协助行程规划 #

生成包含各个地点的方向和信息的多日计划,非常适合旅行应用。

python
# This will only work for SDK newer than 2.0.0
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-4-hydrogen",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476
    }]
)
# ... code to process response

服务使用要求 #

本节介绍事实依据和Google 地图的服务使用要求。

通知用户有关 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 地球法律声明.

最佳实践 #

  • 提供用户位置: 对于最相关和个性化的回复,请始终包含 latitude 和 longitude 在你的 google_maps 当用户位置已知时的工具配置。

  • 告知最终用户: 明确告知您的最终用户 Google 地图数据正在用于回答他们的查询,尤其是在启用该工具时。

  • 不需要时关闭: 事实依据和 Google 地图默认关闭。仅启用它("tools": [{"type": "google_maps"}])当查询具有明确的地理上下文时,可以优化性能和成本。

限制 #

  • 事实依据和 Google 地图目前仅支持英语提示和响应。

  • 该工具可能并非在所有地区都可用。

  • 结果可能会因位置精度和可用地图数据而异。

  • 地理范围: 事实依据和 Google 地图已在全球上市。

  • 默认状态: 事实依据和 Google 地图工具默认处于关闭状态。您必须在 API 请求中明确启用它。

定价和费率限制 #

事实依据和 Google 地图的定价因型号而异:

  • Gemini 3 及更新型号: 您的项目针对模型决定执行的每个搜索查询进行计费,每月 5,000 免费请求在所有 Gemini 3 和更新的模型之间共享,然后 $14 每个 1,000 搜索查询。单个搜索提示(您对模型的 API 请求)可能会导致模型执行多个搜索查询以查找必要的信息。每个查询都算作该工具的一次计费使用。
  • Gemini 2.5 及旧型号: 您的项目按搜索提示计费($25 按 1,000 提供事实依据提示)。仅当提示成功返回至少一个 Google 地图提供事实依据结果时,才会对请求进行计费,无论模型内部执行了多少个单独的搜索查询以获得该结果。

事实依据和 Google 地图的配额通常与基础 Gemini 模型速率限制一致。有关详细定价信息,请参阅 Gemini API 定价页面.

支持的模型 #

以下型号支持事实依据和 Google 地图:

支持的工具组合 #

您可以将事实依据与 Google 地图以及其他内置工具(例如 使用 Google 搜索提供事实依据 (在 Gemini 3.5 Flash 及更高版本上受支持)为更复杂的用例提供支持。 Gemini 4 和 Gemini 3 型号还支持将这些内置工具与自定义工具 (函数调用) 相结合。了解更多信息 工具组合 页。

后续步骤 #

搜索标题、API 名称或正文内容