Interactions API 现已正式发布。我们建议使用此 API 来访问所有最新功能和模型。

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

依托 Google 地图进行接地

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

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

开始使用

此示例演示了如何将 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' \
  -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 地图来源的内嵌注释，以便开发者显示引用。

为何及何时使用 Grounding with Google Maps

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

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

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

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

使用场景

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
    }]
)
# ... code to process response

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
    }]
  });
}

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' \
  -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
    }]
  }'

服务使用要求

本部分介绍了将 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 地图数据正用于回答他们的问题，尤其是在该工具处于启用状态时。
在不需要时切换为关闭状态：默认情况下，Grounding with Google Maps 处于关闭状态。仅当查询具有明确的地理位置背景信息时才启用此功能 ("tools": [{"type": "google_maps"}])，以优化性能和费用。

限制

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

价格和速率限制

Grounding with Google Maps 的价格因模型代际而异：

Gemini 3 模型：对于模型决定执行的每项搜索查询，系统都会向您的项目收取费用。单个搜索提示（您向模型发出的 API 请求）可能会导致模型执行多次搜索查询，以查找必要的信息。每项查询都算作一次工具的付费使用。
Gemini 2.5 及更早版本的模型：您的项目按搜索提示收费。仅当提示成功返回至少一个 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 模型支持将内置工具（例如依托 Google 地图进行接地）与自定义工具（函数调用）相结合。如需了解详情，请参阅工具组合页面。

后续步骤

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