زمین با نقشه گوگل

اتصال به زمین با Google Maps یک مدل Gemini را به داده‌های مکانی از Google Maps متصل می‌کند تا بتوانید قابلیت‌های مبتنی بر مکان را در برنامه‌های خود ایجاد کنید.

اتصال به زمین با Google Maps مزایای زیر را دارد:

  • افزایش دقت واقعی : با مبنا قرار دادن پاسخ‌ها بر اساس پایگاه داده گوگل شامل بیش از ۲۵۰ میلیون مکان و کسب‌وکار در دنیای واقعی، توهمات مدل‌سازی را کاهش دهید.
  • دسترسی به اطلاعات بلادرنگ : با استفاده از داده‌های زنده، مانند ساعات کاری فعلی و وضعیت بلادرنگ ایستگاه‌های شارژ خودروهای برقی، به سؤالات پاسخ دهید.
  • ارائه زمینه بصری : با ادغام ویجت‌های نقشه تعاملی، عکس‌ها و نمای خیابان مستقیماً در کنار ادعاهای مبتنی بر مکان مدل، اعتماد کاربر را جلب کنید.

مدل‌های پشتیبانی‌شده

  • gemini-3.1-pro-preview
  • gemini-3-flash-preview
  • gemini-3.1-flash-lite
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

زبان‌های پشتیبانی‌شده

زبان‌های پشتیبانی‌شده برای مدل‌های Gemini را ببینید.

مدل را با Google Maps زمین بزنید

برای مشاهده محتوا و کد مخصوص ارائه‌دهنده در این صفحه، روی ارائه‌دهنده API Gemini خود کلیک کنید.

وقتی نمونه‌ی GenerativeModel را ایجاد می‌کنید، GoogleMaps به عنوان tool ارائه دهید که مدل بتواند از آن برای تولید پاسخ خود استفاده کند.

سویفت


import FirebaseAILogic

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Example: Coordinates for New York City
let latAndLong = CLLocationCoordinate2D(latitude: 40.7128, longitude: -74.0060)

// (Optional) Define a RetrievalConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
let retrievalConfig = RetrievalConfig(
    location: latAndLong,
    // Example: Language code for English (US)
    languageCode: "en_US"
)

// Wrap the RetrievalConfig inside a ToolConfig.
let toolConfig = ToolConfig(retrievalConfig: retrievalConfig)

// Create a `GenerativeModel` instance with a model that supports your use case.
let model = ai.generativeModel(
    modelName: "GEMINI_MODEL_NAME",
    // Provide Google Maps as a tool that the model can use to generate its response.
    tools: [Tool.googleMaps()],
    // Add the configuration for the Grounding with Google Maps tool
    // (if this optional config was defined above).
    toolConfig: toolConfig
)

let response = try await model.generateContent("restaurants near me?")
print(response.text ?? "No text in response.")

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Kotlin


// (Optional) Define a RetrievalConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
val retrievalConfig = RetrievalConfig(
    // Example: Coordinates for New York City
    latLng = LatLng(latitude = 40.7128, longitude = -74.0060),
    // Example: Language code for English (US)
    languageCode = "en_US"
)

// Wrap the RetrievalConfig inside a ToolConfig.
val toolConfig = ToolConfig(
    retrievalConfig = retrievalConfig
)

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case.
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    // Add the configuration for the Grounding with Google Maps tool
    // (if this optional config was defined above).
    toolConfig = toolConfig,
    // Provide Google Maps as a tool that the model can use to generate its response.
    tools = listOf(Tool.googleMaps())
)

val response = model.generateContent("restaurants near me?")
print(response.text)

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Java


// (Optional) Define a ToolConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
ToolConfig toolConfig = new ToolConfig(
    null,
    new RetrievalConfig(
        // Example: Coordinates for New York City
        new LatLng(40.7128, -74.0060),
        // Example: Language code for English (US)
       "en_US"
    )
);

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports your use case.
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generativeModel("GEMINI_MODEL_NAME",
                        null,
                        null,
                        // Provide Google Maps as a tool that the model can use to generate its response.
                        List.of(Tool.googleMaps()),
                        // Add the configuration for the Grounding with Google Maps tool
                        // (if this optional config was defined above).
                        toolConfig);

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs.
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

ListenableFuture response = model.generateContent("restaurants near me?");
  Futures.addCallback(response, new FutureCallback() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
          String resultText = result.getText();
          System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
          t.printStackTrace();
      }
  }, executor);

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// (Optional) Define a toolConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
const toolConfig = {
  retrievalConfig: {
    // Example: Coordinates for New York City
    latLng: {
      latitude: 40.7128,
      longitude: -74.0060
    },
    // Example: Language code for English (US)
    languageCode: 'en-US'
  }
};

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(
  ai,
  {
    model: "GEMINI_MODEL_NAME",
    // Provide Google Maps as a tool that the model can use to generate its response.
    // (Optional) Set `enableWidget` to control whether the response contains a `googleMapsWidgetContextToken`.
    tools: [ { googleMaps: { enableWidget: true } } ],
    // Add the configuration for the Grounding with Google Maps tool
    // (if this optional config was defined above).
    toolConfig
  }
);

const result = await model.generateContent("restaurants near me?");

console.log(result.response.text());

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Dart


import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp.
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// (Optional) Define a ToolConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
final toolConfig = ToolConfig(
  retrievalConfig: RetrievalConfig(
    // Example: Coordinates for New York City
    latLng: LatLng(latitude: 40.712728, longitude: -74.006015),
    // Example: Language code for English (US)
    languageCode: 'en',
  ),
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case.
final model = FirebaseAI.googleAI().generativeModel(
  model: 'GEMINI_MODEL_NAME',
  // Provide Google Maps as a tool that the model can use to generate its response.
  tools: [
    Tool.googleMaps(),
  ],
  // Add the configuration for the Grounding with Google Maps tool
  // (if this optional config was defined above).
  toolConfig: toolConfig,
);

final response = await model.generateContent([Content.text("restaurants near me?")]);
print(response.text);

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

وحدت


using Firebase;
using Firebase.AI;

// Initialize the Gemini Developer API backend service
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Example: Coordinates for New York City
var latLng = new LatLng(40.7128, -74.0060);

// (Optional) Define a RetrievalConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
var retrievalConfig = new RetrievalConfig(latLng, languageCode: "en");

// Wrap the RetrievalConfig inside a ToolConfig.
var toolConfig = new ToolConfig(retrievalConfig: retrievalConfig);

// Create a `GenerativeModel` instance with a model that supports your use case
var model = ai.GetGenerativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // Provide Google Maps as a tool that the model can use to generate its response.
  tools: new[] { new Tool(new GoogleMaps()) },
  // Add the configuration for the Grounding with Google Maps tool
  // (if this optional config was defined above).
  toolConfig: toolConfig
);

var response = await model.GenerateContentAsync("restaurants near me?");
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

یاد بگیرید که چگونه یک مدل را انتخاب کنیدمناسب برای مورد استفاده و برنامه شما.

برای نتایج ایده‌آل، از دمای ۱.۰ استفاده کنید (که پیش‌فرض برای همه مدل‌های Gemini 2.5 و بالاتر است). نحوه تنظیم دما را در پیکربندی مدل بیاموزید.

بهترین شیوه‌ها و نکات برای بهبود نتایج

این بخش برخی از بهترین شیوه‌های کلی برای استفاده از Grounding با Google Maps و همچنین نحوه استفاده از ویژگی‌های مکان برای بهبود نتایج را شرح می‌دهد.

بهترین شیوه‌های عمومی

  • ابزار را فقط در صورت نیاز ارائه دهید : برای بهینه‌سازی عملکرد و هزینه، فقط زمانی که مورد استفاده زمینه جغرافیایی مشخصی دارد، به مدل امکان دسترسی به ابزار Grounding with Google Maps را بدهید.

  • ارائه موقعیت مکانی کاربر : برای مرتبط‌ترین و شخصی‌سازی‌شده‌ترین پاسخ‌ها (و هنگامی که موقعیت مکانی کاربر مشخص است)، موقعیت مکانی کاربر (با استفاده از طول و عرض جغرافیایی از طریق latLng ) را در پیکربندی ابزار Grounding with Google Maps وارد کنید.

  • اطلاع‌رسانی به کاربران نهایی : به طور واضح به کاربران نهایی خود اطلاع دهید که از داده‌های Google Maps برای پاسخ به سوالات آنها استفاده می‌شود. ارائه منابع Google Maps به کاربران نهایی، یک الزام استفاده از سرویس برای ابزار Grounding with Google Maps است.

  • (فقط SDK وب) رندر کردن ویجت متنی Google Maps : ویجت متنی با استفاده از توکن متنی، googleMapsWidgetContextToken ، رندر می‌شود که در پاسخ API Gemini برگردانده می‌شود و می‌تواند برای رندر کردن محتوای بصری از Google Maps استفاده شود. برای اطلاعات بیشتر در مورد ویجت متنی، به Grounding with Google Maps widget در مستندات Google Maps مراجعه کنید.

استفاده از ویژگی‌های مکان در اعلان‌ها

این بخش، ویژگی‌های مکانی را فهرست می‌کند که برای توصیف مکان‌ها استفاده می‌شوند و توسط Grounding with Google Maps برای تولید پاسخ‌ها مورد استفاده قرار می‌گیرند. این ویژگی‌ها برای تعیین انواع سوالاتی که Grounding with Google Maps می‌تواند به آنها پاسخ دهد، استفاده می‌شوند.

ویژگی‌های مکان نمونه

این لیست، نمونه‌ای الفبایی از ویژگی‌های مکان‌هایی را ارائه می‌دهد که مدل شما می‌تواند از آنها برای تولید پاسخ استفاده کند.

  • آدرس
  • وانت کنار خیابان
  • کارت بدهی
  • فاصله
  • پارکینگ رایگان
  • موسیقی زنده
  • منوی مخصوص کودکان
  • ساعات کاری
  • گزینه‌های پرداخت (مانند پول نقد یا کارت اعتباری )
  • پاسخ را قرار دهید
  • مناسب برای حیوانات خانگی
  • آبجو سرو می‌کند
  • غذاهای گیاهی سرو می‌کند
  • قابل دسترسی با ویلچر
  • وای فای

پاسخ‌های مکانی ، پاسخی از Grounding with Google Maps بر اساس اطلاعات به‌دست‌آمده از نظرات کاربران است.

مثال‌هایی از دستورات که از ویژگی‌های مکان استفاده می‌کنند

مثال‌های زیر از ویژگی‌های مکان در درخواست‌هایی درباره انواع مختلف مکان‌ها استفاده می‌کنند. Grounding with Google Maps از این ویژگی‌ها برای درک هدف شما استفاده می‌کند و سپس بر اساس داده‌های مرتبط با مکان‌ها در Google Maps پاسخ‌های مرتبط ارائه می‌دهد.

  • یک شام خانوادگی ترتیب دهید : بررسی کنید که آیا رستوران برای خانواده مناسب است و آیا خدمات مناسبی ارائه می‌دهد یا خیر.

    • مثال: آیا «رستوران ایتالیایی» برای کودکان مناسب است و آیا غذای بیرون‌بر ارائه می‌دهند؟ امتیاز آنها چیست؟
  • بررسی دسترسی برای یک دوست : مشخص کنید که آیا مکان مورد نظر نیازهای خاص دسترسی را برآورده می‌کند یا خیر.

    • مثال: من به رستورانی نیاز دارم که ورودی آن برای افراد دارای صندلی چرخدار مناسب باشد.
  • مکانی برای صرف میان وعده آخر شب پیدا کنید : یک رستوران باز پیدا کنید که در یک زمان خاص، یک وعده غذایی خاص را سرو کند.

    • مثال: آیا «برگر فروشی» الان باز است؟ آیا شام سرو می‌کنند؟ ساعات کاری آنها برای جمعه‌ها چگونه است؟
  • ملاقات با مشتری برای صرف قهوه : مناسب بودن یک کافه را برای یک جلسه کاری بر اساس امکانات، پیشنهادات و گزینه‌های پرداخت ارزیابی کنید.

    • مثال: آیا «کافه سنترال» وای‌فای دارد؟ آیا قهوه سرو می‌کنند؟ قیمت‌هایشان چقدر است و آیا کارت اعتباری قبول می‌کنند؟

توجه داشته باشید که اطلاعات موجود در نتایج زمینی Google Maps ممکن است با شرایط واقعی جاده متفاوت باشد.

نحوه اتصال به زمین با Google Maps

وقتی ابزار GoogleMaps را در اختیار مدل قرار می‌دهید، مدل کل گردش کار جستجو، پردازش و استناد به اطلاعات را به طور خودکار انجام می‌دهد.

روند کار مدل به شرح زیر است:

  1. دریافت اعلان : برنامه شما با فعال بودن ابزار GoogleMaps اعلانی را به مدل Gemini ارسال می‌کند.

  2. تحلیل درخواست : مدل، درخواست را تحلیل می‌کند و تعیین می‌کند که آیا Google Maps می‌تواند پاسخ خود را بهبود بخشد یا خیر، برای مثال، اگر درخواست شامل زمینه جغرافیایی باشد (مانند «کافی شاپ‌های نزدیک من»، «موزه‌ها در سانفرانسیسکو»).

  3. ابزار را فراخوانی می‌کند : مدل، با تشخیص هدف جغرافیایی، ابزار Grounding with Google Maps را فراخوانی می‌کند.

  4. ارسال درخواست‌ها به Google Maps : سرویس Grounding with Google Maps برای اطلاعات مرتبط (مثلاً مکان‌ها، نظرات، عکس‌ها، آدرس‌ها، ساعات کاری) از Google Maps درخواست می‌کند.

    شما می‌توانید به صورت اختیاری طول و عرض جغرافیایی را در پیکربندی ابزار (یا حتی مستقیماً در اعلان) برای نتایج مرتبط‌تر و شخصی‌سازی‌شده‌تر Google Maps وارد کنید. این ابزار یک ابزار جستجوی متنی است و مشابه جستجو در Google Maps رفتار می‌کند، به این صورت که جستجوهای محلی ("نزدیک من") از مختصات استفاده می‌کنند، در حالی که جستجوهای خاص یا غیرمحلی بعید است که تحت تأثیر مکان صریح قرار گیرند.

  5. پردازش نتایج Google Maps : مدل، نتایج Google Maps را پردازش کرده و پاسخی برای درخواست اولیه تدوین می‌کند.

  6. یک نتیجه مبتنی بر Google Maps برمی‌گرداند : مدل یک پاسخ نهایی و کاربرپسند را برمی‌گرداند که مبتنی بر نتایج Google Maps است. این پاسخ شامل موارد زیر است:

    • پاسخ متنی مدل.
    • یک شیء groundingMetadata با نتایج و منابع Google Maps .
    • (فقط SDK وب) در صورت تمایل، یک googleMapsWidgetContextToken که به شما امکان می‌دهد یک ویجت Google Maps متنی را در برنامه خود برای تعامل بصری رندر کنید. برای اطلاعات بیشتر در مورد ویجت متنی، به Grounding with Google Maps widget در مستندات Google Maps مراجعه کنید.

توجه داشته باشید که ارائه Google Maps به عنوان ابزاری برای مدل، نیازی به استفاده همیشگی مدل از ابزار Google Maps برای تولید پاسخ ندارد . در این موارد، پاسخ حاوی شیء groundingMetadata نخواهد بود و بنابراین یک نتیجه Grounded Google Maps نیست .

نتیجه‌ی قطعی را درک کنید

اگر مدل، پاسخ خود را بر اساس نتایج Google Maps ارائه دهد، آنگاه پاسخ شامل یک شیء groundingMetadata است که حاوی داده‌های ساختاریافته‌ای است که برای تأیید ادعاها و ایجاد یک تجربه غنی از منبع در برنامه شما ضروری است.

شیء groundingMetadata در یک نتیجه Grounded Google Maps شامل اطلاعات زیر است:

  • groundingChunks : آرایه‌ای از اشیاء حاوی منابع maps ( uri ، placeId و title )
  • groundingSupports : آرایه‌ای از تکه‌ها برای اتصال text پاسخ مدل به منابع موجود در groundingChunks . هر تکه یک segment متنی (تعریف شده توسط startIndex و endIndex ) را به یک یا چند groundingChunkIndices پیوند می‌دهد. این فیلد به شما در ساخت لینک‌های منبع درون‌خطی کمک می‌کند. در ادامه‌ی این صفحه، نحوه‌ی برآورده کردن الزامات استفاده از سرویس را خواهید آموخت.
  • (فقط برای وب SDK) googleMapsWidgetContextToken : یک توکن متنی که می‌تواند برای رندر کردن یک ویجت Places متنی استفاده شود. این فیلد فقط هنگام استفاده از وب SDK و در صورتی که پارامتر enableWidget را روی true تنظیم کرده باشید، بازگردانده می‌شود.

در اینجا یک پاسخ نمونه که شامل یک شیء groundingMetadata است، آورده شده است:

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

الزامات استفاده از سرویس

این بخش الزامات استفاده از سرویس برای اتصال به زمین با Google Maps را برای ارائه‌دهنده API Gemini انتخابی شما شرح می‌دهد: Gemini Developer API یا Vertex AI Gemini API (به بخش شرایط خدمات در شرایط خاص سرویس مراجعه کنید).

کاربران را از منابع Google Maps مطلع کنید

با هر نتیجه‌ی Grounded Google Maps ، منابعی را در groundingChunks دریافت خواهید کرد که از هر پاسخ پشتیبانی می‌کنند. فراداده‌های زیر نیز بازگردانده می‌شوند:

  • منبع uri
  • عنوان
  • شناسه

در برنامه خود، هنگام ارائه نتایج Grounding with Google Maps ، باید منابع مرتبط با Google Maps را مشخص کنید و موارد زیر را به کاربران خود اطلاع دهید:

  • منابع Google Maps باید بلافاصله پس از محتوای تولید شده‌ای که منابع از آن پشتیبانی می‌کنند، قرار گیرند. این محتوای تولید شده همچنین به عنوان نتایج مبتنی بر Google Maps Grounded Result) شناخته می‌شود.

  • منابع Google Maps باید در یک تعامل کاربری قابل مشاهده باشند.

در اینجا نحوه دریافت مقادیر برای نمایش منابع از نتایج Grounded Google Maps آمده است:

سویفت

// ...

// Get the model's response
let text = response.text

// Get the grounding metadata
if let candidate = response.candidates.first,
   let groundingMetadata = candidate.groundingMetadata {

  // Get sources
  let groundingChunks = groundingMetadata.groundingChunks
  for chunk in groundingChunks {
    if let maps = chunk.maps {
      let title = maps.title  // for example, "Heaven on 7th Marketplace"
      let url = maps.url  // for example, "https://maps.google.com/?cid=13100894621228039586"
      let placeId = maps.placeId  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
      // TODO(developer): show source in the UI
    }
  }
}

Kotlin

// ...

// Get the model's response
val text = response.text

// Get the grounding metadata
val groundingMetadata = response.candidates.firstOrNull()?.groundingMetadata

// Get sources
val groundingChunks = groundingMetadata?.groundingChunks
groundingChunks?.let { chunks ->
  for (chunk in chunks) {
    val title = chunk.maps?.title  // for example, "Heaven on 7th Marketplace"
    val uri = chunk.maps?.uri  // for example, "https://maps.google.com/?cid=13100894621228039586"
    val placeId = chunk.maps?.placeId  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
    // TODO(developer): show source in the UI
  }
}

Java

// ...

Futures.addCallback(response, new FutureCallback() {
  @Override
  public void onSuccess(GenerateContentResponse result) {
    // Get the model's response
    String text = result.getText();

    // Get the grounding metadata
    GroundingMetadata groundingMetadata =
        result.getCandidates()[0].getGroundingMetadata();

    if (groundingMetadata != null) {
      // Get sources
      List chunks = groundingMetadata.getGroundingChunks();
      if (chunks != null) {
        for(GroundingChunk chunk : chunks) {
          GoogleMapsGroundingChunk maps = chunk.getMaps();
          if (maps != null) {
            String title = maps.getTitle();  // for example, "Heaven on 7th Marketplace"
            String uri = maps.getUri();  // for example, "https://maps.google.com/?cid=13100894621228039586"
            String placeId = maps.getPlaceId();  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
            // TODO(developer): show sources in the UI
          }
        }
      }
    }
  }

  @Override
  public void onFailure(Throwable t) {
    t.printStackTrace();
  }
}, executor);

Web

// ...

// Get the model's text response
const text = result.response.text();

// Get the grounding metadata
const groundingMetadata = result.response.candidates?.[0]?.groundingMetadata;

// Get sources
const groundingChunks = groundingMetadata?.groundingChunks;
if (groundingChunks) {
  for (const chunk of groundingChunks) {
    const title = chunk.maps?.title;  // for example, "Heaven on 7th Marketplace"
    const uri = chunk.maps?.uri;  // for example, "https://maps.google.com/?cid=13100894621228039586"
    const placeId = chunk.maps?.placeId;  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
    // TODO(developer): show sources in the UI
  }
}

Dart

// ...

// Get the model's response
final text = response.text;

// Get the grounding metadata
final groundingMetadata = response.candidates.first.groundingMetadata;

// Get sources
final groundingChunks = groundingMetadata?.groundingChunks;
if (groundingChunks != null) {
  for (var chunk in groundingChunks) {
    final title = chunk.maps?.title;  // for example, "Heaven on 7th Marketplace"
    final uri = chunk.maps?.uri;  // for example, "https://maps.google.com/?cid=13100894621228039586"
    final placeId = chunk.maps?.placeId;  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
    // TODO(developer): show sources in the UI
  }
}

وحدت

// ...

// Get the model's response
var text = response.Text;

// Get the grounding metadata
var groundingMetadata = response.Candidates.First().GroundingMetadata;

// Get sources
if (groundingMetadata != null) {
  foreach(GroundingChunk chunk in groundingMetadata?.GroundingChunks) {
    if (chunk.Maps != null) {
      var title = chunk.Maps?.Title;  // for example, "Heaven on 7th Marketplace"
      var uri = chunk.Maps?.Uri;  // for example, "https://maps.google.com/?cid=13100894621228039586"
      var placeId = chunk.Maps?.PlaceId;  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
      // TODO(developer): show sources in the UI
    }
  }
}

برای هر منبع در groundingChunks ، باید یک پیش‌نمایش لینک مطابق با الزامات زیر ایجاد شود:

درخواست با پاسخی که منابع را نشان می‌دهد

می‌توانید نمای منابع را کوچک کنید.

سریع با پاسخ و منابع از بین رفته

به صورت اختیاری، می‌توانید پیش‌نمایش لینک را با محتوای اضافی، مانند موارد زیر، بهبود بخشید:

  • یک فاوآیکون Google Maps که قبل از متن ارجاع Google Maps درج شده است.
  • عکسی از آدرس اینترنتی منبع ( og:image ).

برای اطلاعات بیشتر در مورد برخی از ارائه‌دهندگان داده‌های Google Maps و شرایط مجوز آنها، به اطلاعیه‌های قانونی Google Maps و Google Earth مراجعه کنید.

دستورالعمل‌های انتساب متن Google Maps

وقتی منابع را در متن به Google Maps نسبت می‌دهید، این دستورالعمل‌ها را دنبال کنید:

  • متن Google Maps به هیچ وجه تغییر ندهید:

    • حروف بزرگ و کوچک متن Google Maps را تغییر ندهید.
    • متن Google Maps در چندین خط نپیچید.
    • متن Google Maps به زبان دیگری ترجمه نکنید.
    • با استفاده از ویژگی HTML translate="no" از ترجمه متن Google Maps توسط مرورگرها جلوگیری کنید.
  • متن Google Maps را مطابق جدول زیر استایل‌بندی کنید:

    ملک سبک
    خانواده فونت بارگذاری فونت اختیاری است.
    خانواده فونت جایگزین هر فونت بدنه‌ی سنس‌سریف که از قبل در محصول شما استفاده شده است یا "سنس‌سریف" برای فراخوانی فونت پیش‌فرض سیستم
    سبک فونت عادی
    وزن فونت ۴۰۰
    رنگ فونت سفید، مشکی (#1F1F1F) یا خاکستری (#5E5E5E). کنتراست (4.5:1) قابل قبول را نسبت به پس‌زمینه حفظ کنید.
    اندازه فونت حداقل اندازه فونت: 12sp
    حداکثر اندازه فونت: 16sp
    برای کسب اطلاعات در مورد sp، به واحدهای اندازه فونت در وب‌سایت Material Design مراجعه کنید.
    فاصله گذاری عادی

مثال CSS

کد CSS زیر متن Google Maps را با سبک و رنگ تایپوگرافی مناسب روی پس‌زمینه سفید یا روشن نمایش می‌دهد.

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

ذخیره سازی توکن زمینه و شناسه مکان

نتیجه‌ی زمینی Google Maps ممکن است شامل توکن زمینه و شناسه‌ی مکان باشد. می‌توانید داده‌های پاسخ زیر را ذخیره، کش و صادر کنید:

  • (فقط SDK وب) googleMapsWidgetContextToken
  • placeId

محدودیت‌های مربوط به ذخیره‌سازی در حافظه پنهان در «شرایط اتصال به زمین با نقشه‌های گوگل» برای این داده‌ها اعمال نمی‌شود.

فعالیت‌ها و مناطق ممنوعه

اتصال به زمین با Google Maps محدودیت‌های بیشتری برای محتوا و فعالیت‌های خاص دارد تا پلتفرمی ایمن و قابل اعتماد حفظ شود. علاوه بر محدودیت‌های استفاده در شرایط ارائه‌دهنده API Gemini انتخابی شما: Gemini Developer API یا Vertex AI Gemini API (به بخش شرایط خدمات در شرایط خاص خدمات مراجعه کنید).

  • شما از اتصال به زمین با Google Maps برای فعالیت‌های پرخطر از جمله خدمات واکنش اضطراری استفاده نخواهید کرد.

  • شما برنامه‌ای که اتصال به زمین با Google Maps را در یک منطقه ممنوعه ارائه می‌دهد، توزیع یا بازاریابی نخواهید کرد. برای اطلاعات بیشتر، به مناطق ممنوعه پلتفرم نقشه‌های گوگل مراجعه کنید. فهرست مناطق ممنوعه ممکن است هر از گاهی به‌روزرسانی شود.

نتایج زمینی و نظارت بر هوش مصنوعی در کنسول Firebase

اگر نظارت هوش مصنوعی را در کنسول Firebase فعال کرده باشید، پاسخ‌ها در Cloud Logging ذخیره می‌شوند. به طور پیش‌فرض، این داده‌ها دارای دوره نگهداری 30 روزه هستند.

این مسئولیت شماست که اطمینان حاصل کنید این دوره نگهداری، یا هر دوره سفارشی که تعیین می‌کنید، کاملاً با مورد استفاده خاص شما و هرگونه الزامات انطباق اضافی برای ارائه‌دهنده API Gemini انتخابی شما: Gemini Developer API یا Vertex AI Gemini API (به بخش شرایط خدمات در شرایط خاص خدمات مراجعه کنید) همسو باشد. ممکن است لازم باشد دوره نگهداری را در Cloud Logging تنظیم کنید تا این الزامات را برآورده کنید.

قیمت‌گذاری و محدودیت‌های نرخ

قیمت‌گذاری گراندینگ با Google Maps بر اساس پرس‌وجوها است. یک درخواست فقط زمانی جزو سهمیه Google Maps محسوب می‌شود که یک درخواست با موفقیت حداقل یک نتیجه گراندینگ Google Maps را برگرداند (به این معنی که پاسخ حداقل شامل یک منبع Google Maps باشد). اگر چندین پرس‌وجو از یک درخواست واحد به Google Maps ارسال شود، به عنوان یک درخواست در سقف نرخ محاسبه می‌شود.

حتماً جزئیات مربوط به قیمت‌گذاری، موجودی مدل و محدودیت‌های اتصال به زمین با Google Maps را در مستندات ارائه‌دهنده API Gemini انتخابی خود بررسی کنید: Gemini Developer API |Vertex AI Gemini API .