Căn cứ vào Google Maps

Tính năng căn cứ vào thông tin trên Google Maps kết nối các khả năng tạo sinh của Gemini với dữ liệu phong phú, thực tế và mới nhất của Google Maps. Tính năng này giúp nhà phát triển dễ dàng tích hợp chức năng nhận biết vị trí vào các ứng dụng của họ. Khi một cụm từ tìm kiếm của người dùng có ngữ cảnh liên quan đến dữ liệu trên Maps, mô hình Gemini sẽ tận dụng Google Maps để cung cấp câu trả lời chính xác về mặt thực tế và mới nhất, đồng thời phù hợp với vị trí cụ thể hoặc khu vực chung mà người dùng chỉ định.

• Câu trả lời chính xác, nhận biết được vị trí: Tận dụng dữ liệu phong phú và mới nhất của Google Maps cho các cụm từ tìm kiếm theo địa lý cụ thể.
• Nâng cao khả năng cá nhân hoá: Điều chỉnh đề xuất và thông tin dựa trên vị trí do người dùng cung cấp.
• Thông tin theo bối cảnh và tiện ích: Mã thông báo theo bối cảnh để hiển thị các tiện ích tương tác của Google Maps cùng với nội dung được tạo.

Bắt đầu

Ví dụ này minh hoạ cách tích hợp tính năng Nền tảng với Google Maps vào ứng dụng của bạn để cung cấp câu trả lời chính xác, nhận biết vị trí cho các truy vấn của người dùng. Câu lệnh yêu cầu đề xuất địa điểm ở địa phương kèm theo vị trí người dùng (không bắt buộc), cho phép mô hình Gemini tận dụng dữ liệu của Google Maps.

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-2.5-flash-lite',
    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})')

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

const ai = new GoogleGenAI({});

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

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite: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}
    }
  }
}'

Cách hoạt động của tính năng Liên kết với Google Maps

Tính năng tiếp đất bằng Google Maps tích hợp Gemini API với hệ sinh thái Google Geo bằng cách sử dụng Maps API làm nguồn tiếp đất. Khi cụm từ tìm kiếm của người dùng chứa bối cảnh địa lý, mô hình Gemini có thể gọi công cụ Grounding with Google Maps. Sau đó, mô hình có thể tạo ra câu trả lời dựa trên dữ liệu của Google Maps liên quan đến vị trí được cung cấp.

Quy trình này thường bao gồm:

1. Truy vấn của người dùng: Người dùng gửi một truy vấn đến ứng dụng của bạn, có thể bao gồm cả bối cảnh địa lý (ví dụ: "quán cà phê gần tôi", "bảo tàng ở Hà Nội").
2. Gọi công cụ: Mô hình Gemini, khi nhận ra ý định liên quan đến địa lý, sẽ gọi công cụ Grounding with Google Maps. Bạn có thể cung cấp cho công cụ này latitude và longitude của người dùng (không bắt buộc) để nhận được kết quả dựa trên vị trí.
3. Truy xuất dữ liệu: Dịch vụ Grounding with Google Maps truy vấn Google Maps để lấy thông tin liên quan (ví dụ: địa điểm, bài đánh giá, ảnh, địa chỉ, giờ mở cửa).
4. Tạo thông tin có căn cứ: Dữ liệu được truy xuất từ Maps được dùng để cung cấp thông tin cho câu trả lời của mô hình Gemini, đảm bảo tính chính xác và mức độ phù hợp của thông tin.
5. Phản hồi và mã thông báo tiện ích: Mô hình này trả về một phản hồi bằng văn bản, bao gồm cả trích dẫn các nguồn trên Google Maps. Ngoài ra, phản hồi API cũng có thể chứa một google_maps_widget_context_token, cho phép nhà phát triển hiển thị một tiện ích Google Maps theo bối cảnh trong ứng dụng của họ để tương tác trực quan.

Lý do và thời điểm nên sử dụng tính năng Liên kết với Google Maps

Tính năng tiếp đất bằng Google Maps rất phù hợp cho những ứng dụng yêu cầu thông tin chính xác, mới nhất và theo vị trí cụ thể. Nhờ cơ sở dữ liệu rộng lớn của Google Maps với hơn 250 triệu địa điểm trên toàn thế giới, tính năng này mang đến nội dung phù hợp và được cá nhân hoá, giúp nâng cao trải nghiệm người dùng.

Bạn nên sử dụng tính năng Grounding with Google Maps khi ứng dụng của bạn cần:

• Đưa ra câu trả lời đầy đủ và chính xác cho các câu hỏi theo vị trí địa lý.
• Xây dựng công cụ lập kế hoạch chuyến đi và hướng dẫn viên địa phương dựa trên cuộc trò chuyện.
• Đề xuất địa điểm yêu thích dựa trên vị trí và lựa chọn ưu tiên của người dùng, chẳng hạn như nhà hàng hoặc cửa hàng.
• Tạo trải nghiệm nhận biết vị trí cho các dịch vụ xã hội, bán lẻ hoặc giao đồ ăn.

Việc sử dụng Google Maps làm cơ sở kiến thức rất phù hợp trong những trường hợp cần có dữ liệu thực tế hiện tại và thông tin về khoảng cách, chẳng hạn như khi tìm "quán cà phê ngon nhất gần tôi" hoặc xem chỉ đường.

Phương thức và tham số API

Tính năng căn cứ vào Google Maps được cung cấp thông qua Gemini API dưới dạng một công cụ trong phương thức generateContent. Bạn có thể bật và định cấu hình tính năng Grounding bằng Google Maps bằng cách thêm một đối tượng googleMaps vào tham số tools trong yêu cầu của bạn.

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": {} }
}

Ngoài ra, công cụ googleMaps có thể chấp nhận một tham số boolean enableWidget. Tham số này được dùng để kiểm soát việc trường googleMapsWidgetContextToken có được trả về trong phản hồi hay không. Bạn có thể dùng tham số này để hiển thị tiện ích Places theo bối cảnh.

{
"contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": { "enableWidget": true } }
}

Ngoài ra, công cụ này còn hỗ trợ truyền vị trí theo bối cảnh dưới dạng toolConfig.

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near here."}
    ]
  }],
  "tools":  { "googleMaps": {} },
  "toolConfig":  {
    "retrievalConfig": {
      "latLng": {
        "latitude": 40.758896,
        "longitude": -73.985130
      }
    }
  }
}

Tìm hiểu về phản hồi cơ sở

Khi một câu trả lời được căn cứ thành công vào dữ liệu của Google Maps, câu trả lời đó sẽ bao gồm trường groundingMetadata. Dữ liệu có cấu trúc này là cần thiết để xác minh các câu trích dẫn và tạo trải nghiệm trích dẫn phong phú trong ứng dụng của bạn, cũng như đáp ứng các yêu cầu về việc sử dụng dịch vụ.

{
  "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"
        ],
        "googleMapsWidgetContextToken": "widgetcontent/..."
      }
    }
  ]
}

Gemini API trả về thông tin sau bằng groundingMetadata:

• groundingChunks: Mảng đối tượng chứa các nguồn maps (uri, placeId và title).
• groundingSupports: Mảng các đoạn văn bản để kết nối văn bản phản hồi của mô hình với các nguồn trong groundingChunks. Mỗi đoạn liên kết một khoảng văn bản (được xác định bằng startIndex và endIndex) với một hoặc nhiều groundingChunkIndices. Đây là chìa khoá để tạo trích dẫn trong dòng.
• googleMapsWidgetContextToken: Một mã thông báo văn bản có thể dùng để hiển thị một tiện ích Places theo bối cảnh.

Để xem đoạn mã minh hoạ cách hiển thị trích dẫn nội dòng trong văn bản, hãy xem ví dụ trong tài liệu Grounding with Google Search.

Hiển thị tiện ích theo bối cảnh của Google Maps

Để sử dụng googleMapsWidgetContextToken được trả về, bạn cần tải API JavaScript của Google Maps.

Trường hợp sử dụng

Tính năng liên kết với Google Maps hỗ trợ nhiều trường hợp sử dụng có nhận biết vị trí. Các ví dụ sau đây minh hoạ cách các câu lệnh và tham số khác nhau có thể tận dụng tính năng Nền tảng với Google Maps. Thông tin trong Kết quả có căn cứ trên Google Maps có thể khác với điều kiện thực tế.

Xử lý các câu hỏi dành riêng cho địa điểm

Đặt câu hỏi chi tiết về một địa điểm cụ thể để nhận câu trả lời dựa trên các bài đánh giá của người dùng trên Google và dữ liệu khác trên Maps.

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-2.5-flash-lite',
    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})')
  ```

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-2.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();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite: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}
    }
  }
}'

Cung cấp thông tin cá nhân hoá dựa trên vị trí

Nhận đề xuất phù hợp với lựa chọn ưu tiên của người dùng và một khu vực địa lý cụ thể.

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

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-2.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();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite: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}
    }
  }
}'

Hỗ trợ lập kế hoạch hành trình

Tạo kế hoạch nhiều ngày kèm theo chỉ đường và thông tin về nhiều địa điểm, phù hợp với các ứng dụng du lịch.

Trong ví dụ này, googleMapsWidgetContextToken đã được yêu cầu bằng cách bật tiện ích trong công cụ Google Maps. Khi được bật, bạn có thể dùng mã thông báo được trả về để hiển thị một tiện ích Places theo bối cảnh bằng cách sử dụng <gmp-places-contextual> component từ API JavaScript của Google Maps.

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-2.5-flash',
    contents=prompt,
    config=types.GenerateContentConfig(
      tools=[types.Tool(google_maps=types.GoogleMaps(enable_widget=True))],
      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})')

  if widget_token := grounding.google_maps_widget_context_token:
    print('-' * 40)
    print(f'<gmp-place-contextual context-token="{widget_token}"></gmp-place-contextual>')

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-2.5-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {enableWidget: true}}],
      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})`);
        }
      }
    }

    if (groundingMetadata.googleMapsWidgetContextToken) {
      console.log('-'.repeat(40));
      document.body.insertAdjacentHTML('beforeend', `<gmp-place-contextual context-token="${groundingMetadata.googleMapsWidgetContextToken}`"></gmp-place-contextual>`);
    }
  }
}

run();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite: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": {"enableWidget":"true"}}],
  "toolConfig": {
    "retrievalConfig": {
    "latLng": {"latitude": 37.78193, "longitude": -122.40476}
  }
  }
}'

Khi được kết xuất, tiện ích này sẽ có dạng như sau:

Yêu cầu về việc sử dụng dịch vụ

Phần này mô tả các yêu cầu về việc sử dụng dịch vụ để sử dụng tính năng Grounding with Google Maps.

Thông báo cho người dùng về việc sử dụng các nguồn dữ liệu của Google Maps

Với mỗi Kết quả thực tế trên Google Maps, bạn sẽ nhận được các nguồn trong groundingChunks hỗ trợ từng câu trả lời. Hệ thống cũng trả về siêu dữ liệu sau:

• uri nguồn
• tiêu đề
• Mã nhận dạng

Khi trình bày kết quả từ tính năng Grounding with Google Maps, bạn phải chỉ định các nguồn liên kết trên Google Maps và thông báo cho người dùng về những điều sau:

• Các nguồn trên Google Maps phải nằm ngay sau nội dung được tạo mà các nguồn đó hỗ trợ. Nội dung được tạo này còn được gọi là Kết quả dựa trên dữ liệu thực tế trên Google Maps.
• Người dùng phải xem được các nguồn của Google Maps trong một lượt tương tác.

Hiển thị các nguồn trên Google Maps bằng đường liên kết đến Google Maps

Đối với mỗi nguồn trong groundingChunks và trong grounding_chunks.maps.placeAnswerSources.reviewSnippets, bạn phải tạo bản xem trước đường liên kết theo các yêu cầu sau:

• Ghi công từng nguồn cho Google Maps theo nguyên tắc ghi công bằng văn bản của Google Maps.
• Hiển thị tiêu đề nguồn có trong câu trả lời.
• Liên kết đến nguồn bằng cách sử dụng uri hoặc googleMapsUri trong câu trả lời.

Những hình ảnh này cho thấy các yêu cầu tối thiểu để hiển thị nguồn và đường liên kết đến Google Maps.

Bạn có thể thu gọn chế độ xem nguồn.

Không bắt buộc: Nâng cao bản xem trước đường liên kết bằng nội dung bổ sung, chẳng hạn như:

• Một biểu tượng Google Maps được chèn trước thông tin ghi nhận quyền tác giả của Google Maps.
• Ảnh từ URL nguồn (og:image).

Để biết thêm thông tin về một số nhà cung cấp dữ liệu của Google Maps và điều khoản cấp phép của họ, hãy xem Thông báo pháp lý của Google Maps và Google Earth.

Nguyên tắc ghi công bằng văn bản trên Google Maps

Khi ghi nguồn cho Google Maps bằng văn bản, hãy tuân thủ các nguyên tắc sau:

• Không sửa đổi văn bản Google Maps dưới bất kỳ hình thức nào:
  • Đừng thay đổi cách viết hoa của Google Maps.
  • Đừng xuống dòng Google Maps.
  • Đừng bản địa hoá Google Maps sang một ngôn ngữ khác.
  • Ngăn trình duyệt dịch Google Maps bằng cách sử dụng thuộc tính HTML translate="no".
• Tạo kiểu cho văn bản trên Google Maps như mô tả trong bảng sau:

Ví dụ về CSS

CSS sau đây kết xuất Google Maps với kiểu chữ và màu sắc phù hợp trên nền trắng hoặc nền sáng.

@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;
}

Mã thông báo theo bối cảnh, mã địa điểm và mã bài đánh giá

Dữ liệu Google Maps bao gồm mã thông báo bối cảnh, mã địa điểm và mã bài đánh giá. Bạn có thể lưu vào bộ nhớ đệm, lưu trữ và xuất dữ liệu phản hồi sau:

• googleMapsWidgetContextToken
• placeId
• reviewId

Các quy định hạn chế đối với việc lưu vào bộ nhớ đệm trong Điều khoản về việc sử dụng Google Maps không áp dụng.

Hoạt động và lãnh thổ bị cấm

Tính năng tiếp đất bằng Google Maps có thêm các quy định hạn chế đối với một số nội dung và hoạt động nhất định để duy trì một nền tảng an toàn và đáng tin cậy. Ngoài các quy định hạn chế về việc sử dụng trong Điều khoản, bạn sẽ không sử dụng tính năng Grounding with Google Maps cho các hoạt động có rủi ro cao, bao gồm cả dịch vụ ứng phó khẩn cấp. Bạn sẽ không phân phối hoặc tiếp thị ứng dụng cung cấp tính năng Grounding with Google Maps ở một Vùng lãnh thổ bị cấm. Các lãnh thổ bị cấm hiện tại là:

• Trung Quốc
• Crimea
• Cuba
• Cộng hoà Nhân dân Donetsk
• Iran
• Cộng hoà Nhân dân Luhansk
• Triều Tiên
• Syria
• Việt Nam

Danh sách này có thể được cập nhật tuỳ từng thời điểm.

Các phương pháp hay nhất

• Cung cấp vị trí của người dùng: Để có được những câu trả lời phù hợp và phù hợp với từng cá nhân nhất, hãy luôn thêm user_location (vĩ độ và kinh độ) vào cấu hình googleMapsGrounding khi bạn biết vị trí của người dùng.
• Kết xuất tiện ích theo bối cảnh của Google Maps: Tiện ích theo bối cảnh được kết xuất bằng mã thông báo bối cảnh, googleMapsWidgetContextToken. Mã thông báo này được trả về trong phản hồi của Gemini API và có thể dùng để kết xuất nội dung trực quan từ Google Maps. Để biết thêm thông tin về tiện ích theo ngữ cảnh, hãy xem phần Căn cứ vào tiện ích Google Maps trong Hướng dẫn cho nhà phát triển của Google.
• Thông báo cho Người dùng cuối: Thông báo rõ ràng cho người dùng cuối rằng dữ liệu trên Google Maps đang được dùng để trả lời các câu hỏi của họ, đặc biệt là khi công cụ này được bật.
• Theo dõi độ trễ: Đối với các ứng dụng đàm thoại, hãy đảm bảo độ trễ P95 cho các câu trả lời có căn cứ vẫn nằm trong ngưỡng chấp nhận được để duy trì trải nghiệm mượt mà cho người dùng.
• Tắt khi không cần thiết: Theo mặc định, tính năng tiếp đất bằng Google Maps sẽ ở trạng thái tắt. Chỉ bật ("tools": [{"googleMaps": {}}]) khi truy vấn có ngữ cảnh địa lý rõ ràng để tối ưu hoá hiệu suất và chi phí.

Các điểm hạn chế

• Phạm vi địa lý: Hiện tại, tính năng Liên kết với Google Maps có trên toàn cầu
• Hỗ trợ mô hình: Chỉ một số mô hình Gemini cụ thể hỗ trợ tính năng Nền tảng kiến thức bằng Google Maps: Gemini 2.5 Flash-Lite, Gemini 2.5 Pro, Gemini 2.5 Flash và Gemini 2.0 Flash (nhưng không hỗ trợ 2.0 Flash Lite).
• Đầu vào/đầu ra đa phương thức: Tính năng liên kết với Google Maps hiện không hỗ trợ đầu vào hoặc đầu ra đa phương thức ngoài văn bản và các tiện ích bản đồ theo bối cảnh.
• Trạng thái mặc định: Công cụ Grounding with Google Maps (Căn cứ vào Google Maps) sẽ tắt theo mặc định. Bạn phải bật tính năng này một cách rõ ràng trong các yêu cầu API.

Mức giá và hạn mức

Việc tiếp đất bằng thông tin định giá của Google Maps dựa trên các cụm từ tìm kiếm. Mức giá hiện tại là 25 USD / 1.000 câu lệnh có căn cứ. Yêu cầu chỉ được tính vào hạn mức khi một câu lệnh trả về thành công ít nhất một kết quả có cơ sở thực tế trên Google Maps (tức là kết quả chứa ít nhất một nguồn trên Google Maps). Nếu nhiều truy vấn được gửi đến Google Maps từ một yêu cầu duy nhất, thì yêu cầu đó sẽ được tính là một yêu cầu trong giới hạn về tốc độ.

Để biết thông tin chi tiết về giá, hãy xem trang định giá Gemini API.

Mô hình được hỗ trợ

Bạn có thể tìm thấy các chức năng của những mô hình này trên trang tổng quan về mô hình.

Bước tiếp theo

• Hãy dùng thử Sổ tay về việc tiếp đất bằng Google Tìm kiếm trong Gemini API.
• Tìm hiểu về các công cụ khác hiện có, chẳng hạn như Gọi hàm.
• Để tìm hiểu thêm về các phương pháp hay nhất về AI có trách nhiệm và bộ lọc an toàn của Gemini API, hãy xem hướng dẫn về Chế độ cài đặt an toàn.