الاستناد إلى "خرائط Google"

يربط أسلوب "الاستناد إلى بيانات Google Maps" نموذج Gemini ببيانات جغرافية مكانية من Google Maps حتى تتمكّن من إنشاء وظائف تستند إلى الموقع الجغرافي في تطبيقاتك.

يوفّر أسلوب "الاستناد إلى بيانات Google Maps" المزايا التالية:

  • زيادة الدقة الوقائعية: يمكنك تقليل الهلوسات التي قد يقدّمها النموذج من خلال استناد الردود إلى قاعدة بيانات Google التي تضم أكثر من 250 مليون مكان ونشاط تجاري في العالم الحقيقي.
  • الوصول إلى المعلومات في الوقت الفعلي: يمكنك الإجابة عن الأسئلة باستخدام البيانات المباشرة، مثل ساعات العمل الحالية ومحطات شحن المركبات الكهربائية في الوقت الفعلي.
  • توفير سياق مرئي: يمكنك تعزيز ثقة المستخدمين من خلال دمج أدوات الخرائط التفاعلية والصور وميزة "التجوّل الافتراضي" مباشرةً بجانب الادعاءات المستندة إلى الموقع الجغرافي التي يقدّمها النموذج.

النماذج المتوافقة

  • gemini-3.1-pro-preview
  • gemini-3.6-flash (والنموذج الأقدم gemini-3.5-flash)
  • gemini-3.5-flash-lite (والنموذج الأقدم gemini-3.1-flash-lite)

تتيح نماذج Gemini 2.5 ذات الاستخدام العام هذه الإمكانية، ولكن تم إيقافها جميعًا.Gemini 2.5

اللغات المتاحة

يمكنك الاطّلاع على اللغات المتاحة لنماذج Gemini.

الاستناد إلى بيانات Google Maps في النموذج

انقر على مقدّم Gemini API لعرض المحتوى والرمز البرمجي الخاصَّين بالمقدّم على هذه الصفحة.

عند إنشاء مثيل GenerativeModel، عليك تقديم GoogleMaps كـ tool يمكن للنموذج استخدامها لإنشاء ردّه.

Swift


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

Unity


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

تعرَّف على كيفية اختيار نموذج مناسبَين لحالة الاستخدام والتطبيق.

أفضل الممارسات والنصائح لتحسين النتائج

يوضّح هذا القسم بعض أفضل الممارسات العامة لاستخدام أسلوب "الاستناد إلى بيانات خرائط Google" مع Google Maps، بالإضافة إلى كيفية الاستفادة من خصائص المكان لتحسين النتائج.

أفضل الممارسات العامة

  • توفير الأداة عند الحاجة فقط: لتحسين الأداء والتكلفة، عليك منح النموذج إذن الوصول إلى أداة "الاستناد إلى بيانات خرائط Google"Google Maps فقط عندما يكون لحالة الاستخدام سياق جغرافي واضح.

  • توفير موقع المستخدم: للحصول على الردود الأكثر ملاءمة وتخصيصًا (وعند معرفة موقع المستخدم)، عليك تضمين موقع المستخدم (باستخدام خطوط الطول والعرض من خلال latLng) في إعداد أداة Google Maps.

  • إعلام المستخدمين النهائيين: عليك إعلام المستخدمين النهائيين بوضوح بأنّه يتم استخدام بيانات Google Maps للإجابة عن طلباتهم. يُعدّ تزويد المستخدمين النهائيين بالمصادر من Google Maps أحد متطلبات استخدام الخدمة لأداة "الاستناد إلى بيانات Google Maps".

  • (حزمة تطوير البرامج للويب فقط) عرض الأداة السياقية Google Maps: يتم عرض الأداة السياقية باستخدام رمز مميّز سياقي googleMapsWidgetContextToken الذي يتم عرضه في ردّ Gemini API ويمكن استخدامه لعرض محتوى مرئي من Google Maps. لمزيد من المعلومات عن الأداة السياقية، يُرجى الاطّلاع على أداة "الاستناد إلى بيانات Google Maps في مستندات Google Maps.

استخدام خصائص المكان في الطلبات

يسرد هذا القسم خصائص المكان التي تُستخدم لوصف المواقع الجغرافية ويستخدمها أسلوب "الاستناد إلى بيانات Google Maps" لإنشاء الردود. تُستخدم هذه الخصائص لتحديد أنواع الأسئلة التي يمكن أن يجيب عنها أسلوب "الاستناد إلى بيانات Google Maps ".

نماذج لخصائص المكان

تقدّم هذه القائمة عيّنة مرتّبة أبجديًا من الخصائص المتعلقة بالأماكن التي يمكن أن يستخدمها النموذج لإنشاء الردود.

  • العنوان
  • الاستلام من السيارة
  • بطاقة السحب الآلي
  • المسافة
  • موقف سيارات مجاني
  • موسيقى حية
  • قائمة طعام للأطفال
  • ساعات العمل
  • خيارات الدفع (مثل الدفع نقدًا أو بطاقة الائتمان)
  • الإجابة المتعلقة بالمكان
  • مناسبة للحيوانات الأليفة
  • تقديم البيرة
  • تقديم المأكولات النباتية
  • أنشطة مناسبة لأصحاب الكراسي المتحرّكة
  • Wifi

الإجابات المتعلقة بالأما1كن هي ردّ من أسلوب "الاستناد إلى بيانات Google Maps استنادًا إلى معلومات مستخلَصة من مراجعات المستخدمين.

أمثلة على الطلبات التي تستخدم خصائص المكان

تستخدم الأمثلة التالية خصائص المكان في الطلبات المتعلقة بأنواع مختلفة من الأماكن. يستخدم أسلوب "الاستناد إلى بيانات Google Maps" الخصائص لفهم هدفك، ثم يقدّم إجابات ذات صلة استنادًا إلى البيانات المرتبطة بالأماكن في Google Maps.

  • التخطيط لعشاء عائلي: يمكنك تحديد ما إذا كان المطعم مناسبًا لـ العائلة وما إذا كان يقدّم خدمة مريحة.

    • مثال على الطلب: هل مطعم "The Italian Place" مناسب للأطفال؟ وهل يقدّم خدمة الطلبات الخارجية؟ ما هو تقييمه؟
  • التحقّق من إمكانية الوصول لصديق: يمكنك تحديد ما إذا كان الموقع الجغرافي يستوفي احتياجات معيّنة لإمكانية الوصول.

    • مثال على الطلب: أحتاج إلى مطعم يضم مدخلاً مناسبًا لأصحاب الكراسي المتحرّكة.
  • العثور على مكان لتناول وجبة خفيفة في وقت متأخر من الليل: يمكنك العثور على مكان مفتوح يقدّم وجبة معيّنة خلال وقت معيّن.

    • مثال على الطلب: هل مطعم "Burger Joint" مفتوح الآن؟ هل يقدّم العشاء؟_ ما هي ساعات العمل ليوم الجمعة؟
  • الاجتماع بعميل لتناول القهوة: يمكنك تقييم مدى ملاءمة مقهى لاجتماع عمل استنادًا إلى وسائل الراحة والعروض وخيارات الدفع.

    • مثال على الطلب: هل يقدّم مقهى "Cafe Central" خدمة Wifi؟ هل يقدّم القهوة؟_ ما هو مستوى الأسعار؟ وهل يقبل بطاقات الائتمان؟

يُرجى العِلم أنّ المعلومات الواردة في Google Maps النتائج المستندة إلى بيانات "خرائط Google" قد تختلف عن الظروف الفعلية للطريق.

طريقة عمل أسلوب "الاستناد إلى بيانات Google Maps"

عند منح النموذج أداة GoogleMaps، يتولّى النموذج سير العمل بالكامل المتمثل في البحث عن المعلومات ومعالجتها والاستشهاد بها تلقائيًا.

في ما يلي سير عمل النموذج:

  1. تلقّي الطلب: يرسل تطبيقك طلبًا إلى نموذج Gemini مع تفعيل أداة GoogleMaps.

  2. تحليل الطلب: يحلّل النموذج الطلب ويحدّد ما إذا كان بإمكان Google Maps تحسين ردّه، مثلاً إذا كان الطلب يتضمّن سياقًا جغرافيًا (مثل "مقاهي قريبة مني" أو "متاحف في بيروت").

  3. استدعاء الأداة: يستدعي النموذج أداة "Google Maps" بعد التعرّف على الهدف الجغرافي.

  4. إرسال طلبات بحث إلى Google Maps: تطلب خدمة "الاستناد إلى بيانات Google Maps " معلومات ذات صلة من Google Maps (مثل الأماكن والمراجعات والصور والعناوين وساعات العمل).

    يمكنك اختياريًا تضمين خطوط الطول والعرض في إعداد الأداة (أو حتى في الطلب مباشرةً) للحصول على نتائج أكثر ملاءمة وتخصيصًا Google Maps الأداة هي أداة بحث نصي وتعمل بطريقة مشابهة للبحث على Google Maps، حيث ستستخدم الطلبات المحلية ("قريبة مني") الإحداثيات، بينما من غير المرجّح أن تتأثر الطلبات المحدّدة أو غير المحلية بالموقع الجغرافي الصريح.

  5. معالجة النتائج: يعالج النموذج النتائج ويصوغ ردًا على الطلب الأصلي.Google MapsGoogle Maps

  6. عرض Google Maps نتيجة مستندة إلى بيانات: يعرض النموذج ردًا نهائيًا، سهل الاستخدام يستند إلى نتائج Google Maps. يتضمّن هذا الردّ ما يلي:

    • الإجابة النصية للنموذج
    • عنصر groundingMetadata يتضمّن نتائج Google Maps ومصادرها
    • (حزمة تطوير البرامج للويب فقط) رمز googleMapsWidgetContextToken اختياري يتيح لك عرض أداة سياقية Google Maps في تطبيقك للتفاعل المرئي لمزيد من المعلومات عن الأداة السياقية، يُرجى الاطّلاع على مقالة الاستناد إلى بيانات Google Maps أداة في مستندات Google Maps.

يُرجى العِلم أنّ منح النموذج Google Maps كأداة لا يتطلّب أن يستخدم النموذج دائمًا أداة Google Maps لإنشاء ردّه. في هذه الحالات، لن يتضمّن الردّ عنصر groundingMetadata، وبالتالي لن يكون نتيجة مستندة إلى بيانات Google Maps.

فهم النتيجة المستندة إلى بيانات "خرائط Google"

إذا استند النموذج في ردّه إلى نتائج Google Maps، سيتضمّن الردّ عنصر groundingMetadata يحتوي على بيانات منظَّمة ضرورية للتحقّق من الادعاءات وإنشاء تجربة مصدر غنية في تطبيقك.

يحتوي عنصر groundingMetadata في Google Maps نتيجة مستندة إلى بيانات على المعلومات التالية:

  • groundingChunks: مصفوفة من العناصر التي تحتوي على مصادر maps (uri وplaceId وtitle)
  • groundingSupports: مصفوفة من الأجزاء لربط ردّ النموذج text بالمصادر في groundingChunks. يربط كل جزء نصًا segment (محدّدًا من خلال startIndex وendIndex) بواحد أو أكثر من groundingChunkIndices. يساعدك هذا الحقل في إنشاء روابط مضمّنة للمصادر. تعرَّف على كيفية استيفاء متطلبات استخدام الخدمة لاحقًا في هذه الصفحة.
  • (حزمة تطوير البرامج للويب فقط) googleMapsWidgetContextToken: رمز نصي يمكن استخدامه لعرض أداة سياقية في "أماكن Google". لا يتم عرض هذا الحقل إلا عند استخدام حزمة تطوير البرامج للويب وإذا ضبطت المَعلمة 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 لمقدّم Gemini API الذي اخترته: Gemini Developer API أو Agent Platform Gemini API (formerly Vertex AI) (يُرجى الاطّلاع على بنود الخدمة قسم ضمن البنود الخاصة بالخدمة).

إعلام المستخدمين بمصادر Google Maps

مع كل Google Maps نتيجة مستندة إلى بيانات، ستتلقّى مصادر في groundingChunks تدعم كل ردّ. يتم أيضًا عرض البيانات الوصفية التالية:

  • معرّف الموارد المنتظم (URI) للمصدر
  • العنوان
  • رقم التعريف

عند عرض نتائج من أسلوب "الاستناد إلى بيانات Google Maps" في تطبيقك، عليك تحديد مصادر Google Maps المرتبطة وإعلام المستخدمين بما يلي:

  • يجب أن تتبع المصادر Google Maps مباشرةً المحتوى الذي تم إنشاؤه الذي تدعمه المصادر. يُشار أيضًا إلى هذا المحتوى الذي تم إنشاؤه باسم Google Maps نتيجة مستندة إلى بيانات.

  • يجب أن تكون مصادر Google Maps قابلة للعرض خلال تفاعل واحد مع المستخدم.

إليك كيفية الحصول على قيم لعرض المصادر من Google Maps النتيجة المستندة إلى بيانات "خرائط Google":

Swift

// ...

// 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
  }
}

Unity

// ...

// 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.
  • يجب عرض عنوان المصدر المقدَّم في الردّ.
  • يجب الربط بالمصدر باستخدام uri من الردّ.

طلب مع ردّ يعرض المصادر

يمكنك تصغير طريقة عرض المصادر.

الطلب مع الرد والمصادر مصغّرة

يمكنك اختياريًا تحسين معاينة الرابط بمحتوى إضافي، مثل:

لمزيد من المعلومات عن بعض مقدّمي بيانات Google Maps وبنود الترخيص الخاصة بهم ، يُرجى الاطّلاع على الإشعارات القانونية في "خرائط Google" و"Google Earth".

إرشادات إسناد النص إلى Google Maps

عند إسناد المصادر إلى Google Maps ضمن النص، يُرجى اتّباع الإرشادات التالية:

  • يجب عدم تعديل النص Google Maps بأي شكل من الأشكال:

    • يجب عدم تغيير كتابة النص Google Maps بالأحرف الكبيرة.
    • يجب عدم نقل النص Google Maps إلى أسطر متعددة.
    • يجب عدم ترجمة النص Google Maps إلى لغة أخرى.
    • يجب منع المتصفّحات من ترجمة النص Google Maps باستخدام سمة HTML‏ translate="no".
  • يجب تنسيق النص Google Maps كما هو موضّح في الجدول التالي:

    الموقع النمط
    مجموعة الخطوط Roboto تحميل الخط اختياري.
    مجموعة الخطوط الاحتياطية أي خط أساسي من نوع sans serif مستخدَم حاليًا في منتجك أو "Sans-Serif" لاستدعاء خط النظام التلقائي
    شكل الخطّ عادي
    عرض الخط 400
    لون الخط أبيض أو أسود (#1F1F1F) أو رمادي (#5E5E5E) يجب الحفاظ على تباين يسهل الوصول إليه (4.5:1) مع الخلفية.
    حجم الخط الحد الأدنى لحجم الخط: ‎12sp
    الحد الأقصى لحجم الخط: ‎16sp
    للتعرّف على وحدة sp، يُرجى الاطّلاع على مقالة وحدات حجم الخط على موقع التصميم المتعدد الأبعاد الإلكتروني.
    التباعد عادي

مثال على نمط 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 النتيجة المستندة إلى بيانات "خرائط Google" رمزًا مميّزًا سياقيًا ورقم تعريف المكان. يمكنك تخزين بيانات الردّ التالية مؤقتًا وحفظها وتصديرها:

  • (حزمة تطوير البرامج للويب فقط) googleMapsWidgetContextToken
  • placeId

لا تنطبق القيود المفروضة على التخزين المؤقت في بنود استخدام "خرائط Google" كمصدر على هذه البيانات.

الأنشطة والمناطق المحظورة

يفرض أسلوب "الاستناد إلى بيانات Google Maps" قيودًا إضافية على محتوى وأنشطة معيّنة للحفاظ على منصة آمنة وموثوقة. بالإضافة إلى قيود الاستخدام الواردة في بنود مقدّم Gemini API الذي اخترته: Gemini Developer API أو Agent Platform Gemini API (formerly Vertex AI) (يُرجى الاطّلاع على بنود الخدمة قسم ضمن البنود الخاصة بالخدمة).

  • لن تستخدم أسلوب "الاستناد إلى بيانات Google Maps" في الأنشطة عالية المخاطر، بما في ذلك خدمات الاستجابة لحالات الطوارئ.

  • لن توزع أو تسوّق تطبيقك الذي يقدّم أسلوب "الاستناد إلى بيانات خرائط Google" مع Google Maps في منطقة محظورة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة المناطق المحظورة في "منصة خرائط Google". قد يتم تعديل قائمة المناطق المحظورة من حين لآخر.

النتائج المستندة إلى بيانات "خرائط Google" وتتبّع استخدام الذكاء الاصطناعي في Firebase console

إذا فعّلت ميزة تتبّع استخدام الذكاء الاصطناعي في Firebase console، يتم تخزين الردود في Cloud Logging. تكون فترة التخزين لهذه البيانات تلقائية لمدة 30 يومًا.

تقع على عاتقك مسؤولية التأكّد من أنّ فترة التخزين هذه، أو أي فترة مخصّصة تحدّدها، تتوافق تمامًا مع حالة الاستخدام المحدّدة وأي متطلبات امتثال إضافية لمقدّم Gemini API الذي اخترته: Gemini Developer API أو Agent Platform Gemini API (formerly Vertex AI) (يُرجى الاطّلاع على قسم "بنود الخدمة" ضمن "البنود الخاصة بالخدمة"). قد تحتاج إلى تعديل فترة التخزين في Cloud Logging لاستيفاء هذه المتطلبات.

التسعير وحدود المعدّل

يستند تسعير أسلوب "الاستناد إلى بيانات Google Maps" إلى طلبات البحث. لا يتم احتساب الطلب ضمن حصة Google Maps إلا عندما يعرض الطلب بنجاح نتيجة مستندة إلى بيانات Google Maps واحدة على الأقل (ما يعني أنّ الردّ يتضمّن مصدرًا واحدًا على الأقل من Google Maps). إذا تم إرسال طلبات بحث متعددة إلى Google Maps من طلب واحد، يتم احتسابها كطلب واحد ضمن حد المعدّل.

يُرجى مراجعة التفاصيل حول التسعير وتوفّر النموذج والحدود الخاصة بأسلوب الاستناد إلى بيانات Google Maps في مستندات مقدّم Gemini API الذي اخترته documentation: Gemini Developer API | Agent Platform Gemini API (formerly Vertex AI).