Gemini 中文指南
获取 API 密钥 ↗

使用 Google 地图提供事实依据

↓ 下载 Markdown

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

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

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

快速入门 #

此示例演示如何将事实依据与 Google 地图集成到您的应用程序中,以便为用户查询提供准确的、位置感知的响应。该提示要求提供带有可选用户位置的本地建议,使 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-4-hydrogen',
      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})')

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

API方法和参数 #

事实依据和 Google 地图通过 Gemini API 作为工具公开 generateContent 方法。您可以通过包含一个 Google 地图来启用和配置事实依据 googleMaps 对象在 tools 您的请求的参数。

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-4-hydrogen',
      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})')

提供基于位置的个性化 #

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

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-4-hydrogen',
      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 generateContentWithMapsGrounding() {
    const response = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      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();

服务使用要求 #

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

通知用户有关 Google 地图源的使用 #

对于每个 Google 地图提供事实依据结果,您将收到以下来源 groundingChunks 支持每个响应。还返回以下元数据:

  • 源URI
  • 标题
  • ID

当使用 Google 地图呈现事实依据的结果时,您必须指定关联的 Google 地图源,并告知您的用户以下信息:

  • Google 地图源必须紧跟在源支持的生成内容之后。此生成的内容也称为 Google 地图提供事实依据结果。

  • Google 地图源必须在一次用户交互中可见。

显示带有 Google 地图链接的 Google 地图源 #

对于每个源 groundingChunks 并在 grounding_chunks.maps.placeAnswerSources.reviewSnippets,必须按照以下要求生成链接预览:

  • 将每个源归因于 Google 地图文本后面的 Google 地图 归因指南.

  • 显示响应中提供的源标题。

  • 使用链接到源 uri 或 googleMapsUri 从响应中。

这些图像显示了显示源和 Google 地图链接的最低要求。

您可以折叠源视图。

可选:使用附加内容增强链接预览,例如:

  • A Google 地图图标 插入在 Google 地图文本属性之前。

  • 来自源 URL 的照片(og:image).

有关我们的一些 Google 地图数据提供商及其许可条款的更多信息,请参阅 Google 地图和 Google 地球法律声明.

Google 地图文本归属指南 #

当您以文本形式将来源归因于 Google 地图时,请遵循以下准则:

  • 不要以任何方式修改文本 Google 地图:

  • 不要更改 Google 地图的大小写。

  • 不要将 Google 地图换行到多行。

  • 不要将 Google 地图本地化为另一种语言。

  • 使用 HTML 属性 translate="no" 阻止浏览器翻译 Google 地图。

  • Google 地图文本样式如下表所述:

属性

风格

Font family

机器人。加载字体是可选的。

Fallback font family

您的产品中已使用的任何无衬线字体或“Sans-Serif”以调用默认系统字体

Font style

正常

Font weight

400

Font color

白色、黑色 (#1F1F1F) 或灰色 (#5E5E5E)。与背景保持可访问的(4.5:1)对比度。

Font size

最小字体大小:12sp 最大字体大小:16sp 要了解 sp,请参阅字体大小单位 材料设计网站.

Spacing

正常

CSS 示例 #

以下 CSS 在白色或浅色背景上以适当的排版样式和颜色渲染 Google 地图。

javascript
  import { GoogleGenAI } from "@google/genai";

  const ai = new GoogleGenAI({});

  async function generateContentWithMapsGrounding() {
    const response = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      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();

地点 ID 和评论 ID #

Google 地图数据包括地点ID和评论ID。您可以缓存、存储和导出以下响应数据:

  • placeId
  • reviewId

事实依据中针对缓存的限制与 Google 地图条款不适用。

禁止活动和区域 #

事实依据和 Google 地图对某些内容和活动有额外的限制,以维护安全可靠的平台。除了使用限制 条款:

  • 您不会将事实依据与 Google 地图一起用于高风险活动,包括紧急响应服务。

  • 您不会在禁止区域内分发或营销提供事实依据和 Google 地图的应用程序。有关更多信息,请参阅 Google 地图平台禁区。禁止领土列表可能会不时更新。

最佳实践 #

  • 提供用户位置: 对于最相关和个性化的回复,请始终包含 user_location (纬度和经度)在您的 googleMapsGrounding 当用户的位置已知时进行配置。

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

  • 监控延迟: 对于对话式应用程序,请确保提供事实依据响应的 P95 延迟保持在可接受的阈值内,以保持流畅的用户体验。

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

限制 #

  • 地理范围: 事实依据和 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 名称或正文内容