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：上下文 token 可用于在生成的内容旁边渲染互动式 Google 地图 widget。

开始使用

此示例演示了如何将 Grounding with Google Maps 集成到应用中，以便针对用户查询提供准确的位置感知型回答。提示会要求提供本地推荐内容，并提供可选的用户位置，以便 Gemini 模型使用 Google 地图数据。

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "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 使用 Google 地图 API 作为依据来源，将 Gemini API 与 Google 地理生态系统集成在一起。当用户的查询包含地理位置上下文时，Gemini 模型可以调用“依托 Google 地图进行接地”工具。然后，模型可以生成基于与所提供位置相关的 Google 地图数据的回答。

该过程通常涉及以下步骤：

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

为何以及何时使用 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

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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

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

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    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,
      enableWidget: true
    }],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "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 地图数据来回答他们的查询，尤其是在启用该工具时。
在不需要时关闭： “依托 Google 地图进行接地”默认处于关闭状态。只有当查询具有明确的地理位置上下文时，才启用它 ("tools": [{"type": "google_maps"}])，以优化性能和费用。

限制

Grounding with Google Maps 目前仅支持英语提示和回答。
该工具可能并非在所有地区都可用。
结果可能会因位置准确性和可用的 Google 地图数据而异。
地理范围： Grounding with Google Maps 在全球范围内可用。
默认状态： Grounding with Google Maps 工具默认处于关闭状态。您必须在 API 请求中明确启用它。

价格和速率限制

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

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

支持的模型

以下模型支持 Grounding with Google Maps：

模型	Grounding with Google Maps
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 模型支持将内置工具（例如“依托 Google 地图进行接地”）与自定义工具（函数调用）相结合。如需了解详情，请参阅工具组合页面。

后续步骤

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