依托 Google 地图进行接地

Grounding with Google Maps 可将 Gemini 的生成功能与 Google 地图丰富、真实且最新的数据相关联。借助此功能，开发者可以轻松地将位置感知功能整合到其应用中。当用户查询包含与 Google 地图数据相关的上下文时，Gemini 模型会利用 Google 地图提供与用户指定位置或大致区域相关的事实准确且最新的回答。

  • 准确且能感知位置的回答：利用 Google 地图广泛且最新的数据来回答地理位置特定的查询。
  • 增强个性化功能：根据用户提供的位置信息量身定制推荐内容和信息。

开始使用

此示例演示了如何将 Grounding with Google Maps 集成到您的应用中，以便为用户查询提供准确的、感知位置信息的回答。提示要求提供本地推荐，并包含可选的用户位置信息，使 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-3.5-flash',
    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})')

JavaScript

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

const ai = new GoogleGenAI({});

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

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "What are the best Italian restaurants within a 15-minute walk from here?"
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 34.050481, "longitude": -118.248526}
    }
  }
}'

Grounding with Google Maps 的运作方式

Grounding with Google Maps 通过使用地图 API 作为依据源，将 Gemini API 与 Google 地理位置生态系统相集成。当用户的查询包含地理位置背景信息时，Gemini 模型可以调用“使用 Google 地图建立依据”工具。然后，模型可以根据与所提供位置相关的 Google 地图数据生成回答。

此过程通常包括：

  1. 用户查询：用户向您的应用提交查询，其中可能包含地理位置背景信息（例如“我附近的咖啡店”“旧金山的博物馆”）。
  2. 工具调用：Gemini 模型识别出地理位置意图，并调用 Grounding with Google Maps 工具。此工具可选择性地提供用户的 latitude 和 longitude。该工具是一种文本搜索工具，其行为与在 Google 地图上搜索类似，即本地查询（例如“我附近”）会使用坐标，而具体或非本地查询不太可能受到明确位置的影响。
  3. 数据检索：“借助 Google 地图进行接地”服务会查询 Google 地图以获取相关信息（例如地点、评价、照片、地址、营业时间）。
  4. 依托数据的生成：检索到的 Google 地图数据用于为 Gemini 模型的回答提供信息，确保回答的事实准确性和相关性。
  5. 回答：模型返回文本回答，其中包含对 Google 地图来源的引用。

为何及何时使用 Grounding with Google Maps

Grounding with Google Maps 非常适合需要准确、最新且特定于位置的信息的应用。它依托 Google 地图在全球范围内超过 2.5 亿个地点的庞大数据库，提供相关且个性化的内容，从而提升用户体验。

如果应用需要执行以下操作，您应使用 Grounding with Google Maps 功能：

  • 完整且准确地回答特定地理位置的问题。
  • 构建对话式旅行规划工具和本地指南。
  • 根据位置信息和用户偏好（例如餐厅或商店）推荐地图注点。
  • 为社交、零售或外卖服务打造基于地理位置的体验。

在需要考虑邻近性和当前事实数据的使用场景中，例如查找“我附近的最佳咖啡店”或获取路线，Google 地图的 grounding 功能表现出色。

API 方法和参数

通过 Gemini API，Grounding with Google Maps 功能以工具的形式在 generateContent 方法中公开。您可以通过在请求的 tools 参数中添加 googleMaps 对象，启用并配置 Grounding with Google Maps。

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 搜索进行接地”文档中的示例。

使用场景

Grounding with Google Maps 支持各种感知位置的应用场景。以下示例展示了不同的提示和参数如何利用 Grounding with Google Maps。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-3.5-flash',
    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})')
  ```

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?";

  const response = await ai.models.generateContent({
    model: 'gemini-3.5-flash',
    contents: prompt,
    config: {
      // Turn on the Maps tool
      tools: [{googleMaps: {}}],
      // Provide the relevant location context (this is in Los Angeles)
      toolConfig: {
        retrievalConfig: {
          latLng: {
            latitude: 34.050481,
            longitude: -118.248526
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
  if (chunks) {
    console.log('-'.repeat(40));
    console.log("Sources:");
    for (const chunk of chunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

run();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 34.050481, "longitude": -118.248526}
    }
  }
}'

提供基于位置的个性化体验

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

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-3.5-flash',
    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 run() {
  const prompt = "Which family-friendly restaurants near here have the best playground reviews?";

  const response = await ai.models.generateContent({
    model: 'gemini-3.5-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {}}],
      toolConfig: {
        retrievalConfig: {
          // Provide the location as context; this is Austin, TX.
          latLng: {
            latitude: 30.2672,
            longitude: -97.7431
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
  if (chunks) {
    console.log('-'.repeat(40));
    console.log("Sources:");
    for (const chunk of chunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

run();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Which family-friendly restaurants near here have the best playground reviews?"
    }],
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 30.2672, "longitude": -97.7431}
    }
  }
}'

协助规划行程

生成包含路线和各种地点信息的为期多天的计划，非常适合旅行应用。

Python

from google import genai
from google.genai import types

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."

response = client.models.generate_content(
    model='gemini-3.5-flash',
    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 in San Francisco.
          lat_lng=types.LatLng(
              latitude=37.78193, longitude=-122.40476))),
    ),
)

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})')

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
  const 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.";

  const response = await ai.models.generateContent({
    model: 'gemini-3.5-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {}}],
      toolConfig: {
        retrievalConfig: {
          // Provide the location as context, this is in San Francisco.
          latLng: {
            latitude: 37.78193,
            longitude: -122.40476
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const groundingMetadata = response.candidates[0]?.groundingMetadata;
  if (groundingMetadata) {
    if (groundingMetadata.groundingChunks) {
      console.log('-'.repeat(40));
      console.log("Sources:");
      for (const chunk of groundingMetadata.groundingChunks) {
        if (chunk.maps) {
          console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
        }
      }
    }
  }
}

run();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "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": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
    "latLng": {"latitude": 37.78193, "longitude": -122.40476}
  }
  }
}'

服务使用要求

本部分介绍了将 Google 地图作为知识库的接地要求。

告知用户 Google 地图来源的使用情况

对于每个 Google 地图接地结果，您都会收到groundingChunks中支持相应回答的来源。系统还会返回以下元数据：

  • 源 URI
  • 标题
  • ID

在展示 Grounding with Google Maps 的结果时，您必须指明关联的 Google 地图来源，并告知用户以下信息：

  • Google 地图来源必须紧跟在来源支持的生成内容之后。此类生成的内容也称为 Google 地图接地结果。
  • Google 地图来源必须在一次用户互动中可见。

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

对于 groundingChunks 和 grounding_chunks.maps.placeAnswerSources.reviewSnippets 中的每个来源，必须按照以下要求生成链接预览：

  • 请按照 Google 地图文字提供方指南，将每项来源归属至 Google 地图。
  • 显示回答中提供的来源标题。
  • 使用回答中的 uri 或 googleMapsUri 链接到来源。

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

显示来源的回答提示

您可以收起“来源”视图。

已折叠包含回答和来源的提示

可选：使用其他内容（例如以下内容）增强链接预览：

如需详细了解部分 Google 地图数据提供商及其许可条款，请参阅 Google 地图和 Google 地球法律声明。

Google 地图文字提供方信息指南

在文本中将来源归属至 Google 地图时，请遵循以下准则：

  • 请勿以任何方式修改“Google 地图”字样：
    • 请勿更改“Google 地图”的大小写。
    • 请勿将 Google 地图换行显示。
    • 请勿将 Google 地图本地化为其他语言。
    • 使用 HTML 属性 translate="no" 防止浏览器翻译 Google 地图。
  • 按照下表中的说明设置 Google 地图文字的样式：
属性 样式
Font family Roboto加载字体是可选的。
Fallback font family 产品中已使用的任何无衬线正文字体，或“Sans-Serif”以调用默认系统字体
Font style 正常
Font weight 400
Font color 白色、黑色 (#1F1F1F) 或灰色 (#5E5E5E)。保持与背景的对比度达到无障碍标准 (4.5:1)。
Font size
  • 字体大小下限：12sp
  • 字体大小上限：16sp
  • 如需了解 sp，请参阅 Material Design 网站上的“字体大小单位”。
Spacing 正常

示例 CSS

以下 CSS 代码段可在白色或浅色背景上以适当的排版样式和颜色呈现 Google 地图。

CSS

@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');

.GMP-attribution {

font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}

地点 ID 和评价 ID

Google 地图数据包括地点 ID 和评价 ID。您可能会缓存、存储和导出以下回答数据：

  • placeId
  • reviewId

Grounding with Google Maps 条款中有关禁止缓存的限制不适用。

禁止的活动和地区

Grounding with Google Maps 对某些内容和活动有额外限制，以维护安全可靠的平台。除条款中的使用限制之外，您还不得有以下行为：

  • 您不会将 Grounding with Google Maps 用于高风险活动，包括紧急响应服务。
  • 您不会在禁止地区分发或营销提供基于 Google 地图进行接地的应用。如需了解详情，请参阅 Google Maps Platform 禁止地区。 禁止的地区列表可能会不时更新。

最佳做法

  • 提供用户位置信息：为了获得最相关且个性化的回答，当您知道用户的位置信息时，请务必在 googleMapsGrounding 配置中添加 user_location（纬度和经度）。
  • 告知最终用户：明确告知最终用户，Google 地图数据正用于回答他们的问题，尤其是在该工具处于启用状态时。
  • 监控延迟时间：对于对话式应用，请确保基于事实的回答的 P95 延迟时间保持在可接受的阈值范围内，以维持流畅的用户体验。
  • 在不需要时切换为关闭状态：默认情况下，Grounding with Google Maps 处于关闭状态。仅当查询具有明确的地理位置上下文时才启用此功能 ("tools": [{"googleMaps": {}}])，以优化性能和费用。

限制

  • 地理范围：Grounding with Google Maps 在全球范围内均可使用
  • 模型支持：请参阅支持的模型部分。
  • 多模态输入/输出：Grounding with Google Maps 目前不支持除文本以外的多模态输入或输出。
  • 默认状态：“依托 Google 地图进行接地”工具默认处于关闭状态。 您必须在 API 请求中明确启用该功能。

价格和速率限制

Grounding with Google Maps 的价格取决于查询次数。目前的费率为25 美元 / 1,000 条有根据的提示。免费层级每天最多可发送 500 个请求。仅当提示成功返回至少一个 Google 地图接地结果（即包含至少一个 Google 地图来源的结果）时，相应请求才会计入配额。如果单个请求向 Google 地图发送了多个查询，则这些查询计为一次请求，并计入速率限制。

如需详细了解价格信息，请参阅 Gemini API 价格页面。

支持的模型

以下模型支持 Grounding with Google Maps：

模型 依托 Google 地图进行接地
Gemini 3.5 Flash ✔️
Gemini 3.1 Pro 预览版 ✔️
Gemini 3.1 Flash-Lite ✔️
Gemini 3 Flash 预览版 ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

支持的工具组合

Gemini 3 模型支持将内置工具（例如将 Grounding 与 Google 地图结合使用）与自定义工具（函数调用）相结合。如需了解详情，请参阅工具组合页面。

后续步骤