Gemini Deep Research 现已推出预览版，支持协作规划、可视化、MCP 等功能。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

依托 Google 地图进行接地

注意：此版本的页面介绍了新的 Interactions API，该 API 目前为 Beta 版。
对于稳定的生产部署，我们建议您继续使用 generateContent API。您可以使用此页面上的切换开关在不同版本之间切换。

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

准确且能感知位置的回答：利用 Google 地图广泛且最新的数据来回答地理位置特定的查询。
增强个性化功能：根据用户提供的位置信息量身定制推荐和信息。
上下文信息和 widget：用于在生成的内容旁边渲染互动式 Google 地图 widget 的上下文令牌。

开始使用

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

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    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 (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - {annotation.name}: {annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "latitude": 34.050481,
      "longitude": -118.248526
    }]
  }'

Grounding with Google Maps 的运作方式

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

此过程通常包括：

用户查询：用户向您的应用提交查询，其中可能包含地理位置背景信息（例如“我附近的咖啡店”“旧金山的博物馆”）。
工具调用：Gemini 模型识别出地理位置意图，并调用 Grounding with Google Maps 工具。此工具可以选择性地提供用户的 latitude 和 longitude。该工具是一个文本搜索工具，其行为与在 Google 地图上搜索类似，即本地查询（例如“我附近”）会使用坐标，而具体或非本地查询不太可能受到明确位置的影响。
数据检索： Grounding with Google Maps 服务会向 Google 地图查询相关信息（例如地点、评价、照片、地址、营业时间）。
依托数据的生成：检索到的 Google 地图数据用于为 Gemini 模型的回答提供信息，确保回答的事实准确性和相关性。
回答和注释：模型会返回带有内嵌注释的文本回答，这些注释会链接到 Google 地图来源，从而让开发者能够显示引用，并选择性地渲染上下文相关的 Google 地图 widget。

为何及何时使用 Grounding with Google Maps

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

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

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

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

使用场景

Grounding with Google Maps 支持各种感知位置的应用场景。

处理与地点相关的问题

详细询问特定地点，以根据 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-3.5-flash",
    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}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    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 (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

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

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

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-3.5-flash",
    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}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Which family-friendly restaurants near here have the best playground reviews?",
    tools: [{
      type: "google_maps",
      latitude: 30.2672,
      longitude: -97.7431
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

协助规划行程

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

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-3.5-flash",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476,
        "enable_widget": True
    }]
)
# ... code to process response and widget token

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "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: [{
      type: "google_maps",
      latitude: 37.78193,
      longitude: -122.40476,
      enable_widget: true
    }]
  });
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "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": [{
      "type": "google_maps",
      "latitude": 37.78193,
      "longitude": -122.40476,
      "enable_widget": true
    }]
  }'

服务使用要求

本部分介绍了将 Google 地图作为知识库的用例对服务使用情况的要求。

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

对于每个 Google 地图接地结果，您都会在model_output步骤的内容块中收到来源注释，这些注释支持相应回答。系统会返回以下元数据：

来源网址
name

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

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

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

对于每个来源注释，必须按照以下要求生成链接预览：

请按照 Google 地图文字提供方指南，将每项来源归属至 Google 地图。
显示回答中提供的来源名称。
使用注解中的 url 链接到来源。

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

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

请勿以任何方式修改“Google 地图”字样：
- 请勿更改“Google 地图”的大小写。
- 请勿将 Google 地图内容换行显示。
- 请勿将 Google 地图本地化为其他语言。
- 使用 HTML 属性 translate="no" 阻止浏览器翻译 Google 地图。

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

最佳做法

提供用户位置信息：为了获得最相关且个性化的回答，当用户的位置信息已知时，请务必在 google_maps 工具配置中添加 latitude 和 longitude。
渲染 Google 地图上下文 widget：上下文 widget 使用上下文 token google_maps_widget_context_token 进行渲染，该 token 在 Gemini API 响应中返回，可用于渲染 Google 地图中的视觉内容。
告知最终用户：明确告知最终用户，系统正在使用 Google 地图数据来回答他们的问题，尤其是在该工具处于启用状态时。
在不需要时切换为关闭状态：默认情况下，Grounding with Google Maps 处于关闭状态。仅当查询具有明确的地理位置背景信息时才启用此功能 ("tools": [{"type": "google_maps"}])，以优化性能和费用。

限制

Google 地图接地目前仅支持英语提示和回答。
此工具可能未在所有地区推出。
搜索结果可能会因位置信息的准确性和可用的 Google 地图数据而异。
地理范围：Grounding with Google Maps 在全球范围内可用。
默认状态：“依托 Google 地图进行接地”工具默认处于关闭状态。您必须在 API 请求中明确启用该功能。

价格和速率限制

Grounding with Google Maps 的价格取决于查询次数。目前的费率为每 1,000 个基于事实的提示 25 美元。免费层级每天最多可发送 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.1 Flash-Lite 预览版	✔️
Gemini 3 Flash 预览版	✔️
Gemini 2.5 Pro	✔️
Gemini 2.5 Flash	✔️
Gemini 2.5 Flash-Lite	✔️
Gemini 2.0 Flash	✔️

支持的工具组合

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

后续步骤

了解其他可用工具。
如需详细了解 Responsible AI 最佳实践和 Gemini API 的安全过滤条件，请参阅安全设置指南。