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

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

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

البدء

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

Python

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

JavaScript

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

const ai = new GoogleGenAI({});

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

REST

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

طريقة عمل ميزة "الاستناد إلى خرائط Google"

تدمج ميزة استخدام "خرائط Google" كمصدر واجهة Gemini API مع نظام Google Geo البيئي من خلال استخدام Maps API كمصدر للبيانات الأساسية. عندما يتضمّن طلب بحث المستخدم سياقًا جغرافيًا، يمكن لنموذج Gemini استخدام أداة Grounding with Google Maps. يمكن للنموذج بعد ذلك إنشاء ردود استنادًا إلى بيانات "خرائط Google" ذات الصلة بالموقع الجغرافي المقدَّم.

تتضمّن العملية عادةً ما يلي:

  1. طلب بحث المستخدم: يرسل المستخدم طلب بحث إلى تطبيقك، وقد يتضمّن سياقًا جغرافيًا (مثل "مقاهي بالقرب مني" أو "متاحف في دبي").
  2. استدعاء الأداة: يستدعي نموذج Gemini أداة "استخدام خرائط Google كمصدر" بعد أن يتعرّف على النية الجغرافية. يمكن بشكل اختياري تزويد هذه الأداة latitude وlongitude الخاصين بالمستخدم. الأداة هي أداة بحث نصي وتعمل بشكل مشابه للبحث على "خرائط Google"، إذ إنّ طلبات البحث المحلية ("بالقرب مني") ستستخدم الإحداثيات، بينما من غير المرجّح أن تتأثر طلبات البحث المحدّدة أو غير المحلية بالموقع الجغرافي الواضح.
  3. استرداد البيانات: تستعلم خدمة استخدام "خرائط Google" كمصدر من "خرائط Google" عن المعلومات ذات الصلة (مثل الأماكن والمراجعات والصور والعناوين وساعات العمل).
  4. الإنشاء المستند إلى مصادر: يتم استخدام بيانات "خرائط Google" التي تم استرجاعها لإبلاغ ردّ نموذج Gemini، ما يضمن الدقة الواقعية ومدى الصلة بالموضوع.
  5. الردّ: يعرض النموذج ردًا نصيًا يتضمّن اقتباسات من مصادر "خرائط Google".

أهمية استخدام ميزة "الاستناد إلى خرائط Google" وحالات استخدامها

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

عليك استخدام Grounding with Google Maps عندما يحتاج تطبيقك إلى:

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

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

طُرق واجهة برمجة التطبيقات والمَعلمات

يتم عرض استخدام "خرائط Google" كمصدر من خلال Gemini API كأداة ضمن الطريقة generateContent. يمكنك تفعيل ميزة استخدام "خرائط Google" كمصدر وضبطها من خلال تضمين عنصر googleMaps في المَعلمة tools من طلبك.

JSON

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

بالإضافة إلى ذلك، تتيح الأداة تمرير الموقع الجغرافي السياقي كـ toolConfig.

JSON

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

فهم الردّ المستند إلى معلومات خارجية

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

JSON

{
  "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"
        ]
      }
    }
  ]
}

تعرض Gemini API المعلومات التالية مع groundingMetadata:

  • groundingChunks: مصفوفة من العناصر التي تحتوي على مصادر maps (uri وplaceId وtitle)
  • groundingSupports: مصفوفة من الأجزاء لربط نص ردّ النموذج بالمستندات المصدر في groundingChunks يربط كل جزء نطاقًا نصيًا (محدّدًا بواسطة startIndex وendIndex) بعنصر groundingChunkIndices واحد أو أكثر. وهذا هو المفتاح لإنشاء اقتباسات مضمّنة.

للحصول على مقتطف رمز يعرض كيفية عرض الاقتباسات المضمّنة في النص، يمكنك الاطّلاع على المثال في مستندات تحديد المصدر من خلال "بحث Search".

حالات الاستخدام

يتيح استخدام "خرائط Google" كمصدر مجموعة متنوعة من حالات الاستخدام التي تعتمد على الموقع الجغرافي. توضّح الأمثلة التالية كيف يمكن أن تستفيد الطلبات والمَعلمات المختلفة من استخدام "خرائط Google" كمصدر. قد تختلف المعلومات الواردة في "النتائج المستندة إلى بيانات واقعية" من "خرائط Google" عن الظروف الفعلية.

التعامل مع الأسئلة المتعلّقة بمكان معيّن

طرح أسئلة مفصّلة حول مكان معيّن للحصول على إجابات استنادًا إلى مراجعات المستخدمين على Google وبيانات أخرى من "خرائط Google"

Python

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

JavaScript

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-3.8-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();

REST

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

توفير ميزة التخصيص المستندة إلى الموقع الجغرافي

الحصول على اقتراحات مخصّصة حسب تفضيلات المستخدِم ومنطقة جغرافية معيّنة

Python

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-3.8-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})')

JavaScript

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-3.8-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();

REST

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

المساعدة في التخطيط لبرنامج الرحلة

إنشاء خطط لعدة أيام تتضمّن الاتجاهات ومعلومات عن مواقع جغرافية مختلفة، ما يجعلها مثالية لتطبيقات السفر

Python

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-3.8-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 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})')

JavaScript

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

run();

REST

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

متطلبات استخدام الخدمة

يوضّح هذا القسم متطلبات استخدام خدمة "التأسيس مع خرائط Google".

إبلاغ المستخدم بشأن استخدام مصادر "خرائط Google"

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

  • عنوان URI المصدر
  • title
  • رقم التعريف

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

  • يجب أن تظهر مراجع "خرائط Google" مباشرةً بعد المحتوى الذي تم إنشاؤه والذي تستند إليه هذه المراجع. يُشار إلى هذا المحتوى الذي تم إنشاؤه أيضًا باسم "نتيجة مستندة إلى بيانات واقعية" في "خرائط Google".
  • يجب أن تكون مصادر "خرائط Google" قابلة للعرض من خلال تفاعل واحد من المستخدم.

عرض مصادر "خرائط Google" باستخدام روابط إلى "خرائط Google"

بالنسبة إلى كل مصدر في groundingChunks وgrounding_chunks.maps.placeAnswerSources.reviewSnippets، يجب إنشاء معاينة للرابط وفقًا للمتطلبات التالية:

  • يجب الإشارة إلى مصدر كل صورة في "خرائط Google" وفقًا لإرشادات الإشارة إلى المصدر في "خرائط Google".
  • عرض عنوان المستند المصدر المقدَّم في الردّ
  • انقر على uri أو googleMapsUri في الردّ للانتقال إلى رابط المصدر.

تعرض هذه الصور الحدّ الأدنى من المتطلبات لعرض المصادر وروابط "خرائط Google".

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

يمكنك تصغير عرض المستندات المصدر.

تم تصغير الطلب مع الرد والمصادر

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

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

إرشادات تحديد المصدر باستخدام نص في "خرائط Google"

عند الإشارة إلى مصادر في "خرائط Google" ضمن نص، اتّبِع الإرشادات التالية:

  • لا تعدّل النص في "خرائط Google" بأي شكل من الأشكال:
    • لا تغيِّر استخدام الأحرف اللاتينية الكبيرة في "خرائط Google".
    • لا تلتفّ "خرائط Google" على أسطر متعددة.
    • عدم ترجمة "خرائط Google" إلى لغة أخرى
    • يمكنك منع المتصفّحات من ترجمة "خرائط Google" باستخدام السمة translate="no" في HTML.
  • يمكنك تنسيق نص "خرائط Google" كما هو موضّح في الجدول التالي:
الموقع النمط
Font family Roboto تحميل الخط اختياري.
Fallback font family أي خط sans serif مستخدَم حاليًا في منتجك أو "Sans-Serif" لاستدعاء خط النظام التلقائي
Font style عادي
Font weight 400
Font color أبيض أو أسود (#1F1F1F) أو رمادي (#5E5E5E) الحفاظ على تباين يسهل الوصول إليه (4.5:1) مع الخلفية
Font size
  • الحد الأدنى لحجم الخط: 12sp
  • الحدّ الأقصى لحجم الخط: 16sp
  • لمزيد من المعلومات عن sp، يمكنك الاطّلاع على وحدات حجم الخط على موقع Material Design الإلكتروني.
Spacing عادي

مثال على CSS

تعرض ورقة الأنماط المتتالية (CSS) التالية "خرائط Google" بالنمط الطباعي واللون المناسبَين على خلفية بيضاء أو فاتحة.

CSS

@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" رقم تعريف المكان ورقم تعريف المراجعة. قد يتم تخزين بيانات الردود التالية مؤقتًا وتصديرها:

  • placeId
  • reviewId

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

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

يتضمن استخدام "خرائط Google" كمصدر قيودًا إضافية على بعض المحتوى والأنشطة للحفاظ على أمان المنصة وموثوقيتها. بالإضافة إلى قيود الاستخدام الواردة في البنود:

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

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

  • توفير الموقع الجغرافي للمستخدم: للحصول على الردود الأكثر صلة بالموضوع والمخصّصة، احرص دائمًا على تضمين user_location (خطوط الطول والعرض) في إعدادات googleMapsGrounding عندما يكون الموقع الجغرافي للمستخدم معروفًا.
  • إبلاغ المستخدمين النهائيين: يجب إبلاغ المستخدمين النهائيين بوضوح بأنّه يتم استخدام بيانات "خرائط Google" للردّ على طلباتهم، خاصةً عند تفعيل الأداة.
  • مراقبة وقت الاستجابة: بالنسبة إلى التطبيقات الحوارية، تأكَّد من أنّ وقت الاستجابة P95 للردود المستندة إلى بيانات خارجية يظل ضمن الحدود المقبولة للحفاظ على تجربة مستخدم سلسة.
  • إيقاف الميزة عند عدم الحاجة إليها: يكون استخدام "خرائط Google" كمصدر غير مفعّل تلقائيًا. لا تفعِّلها ("tools": [{"googleMaps": {}}]) إلا عندما يكون لطلب البحث سياق جغرافي واضح، وذلك لتحسين الأداء والتكلفة.

القيود

  • النطاق الجغرافي: تتوفّر ميزة "استخدام خرائط Google كمصدر" على مستوى العالم.
  • طُرز الأجهزة المتوافقة: يمكنك الاطّلاع على قسم طُرز الأجهزة المتوافقة.
  • المدخلات والمخرجات بتنسيقات متعدّدة: لا تتيح ميزة "استخدام "خرائط Google" كمصدر" حاليًا استخدام المدخلات أو المخرجات بتنسيقات متعدّدة غير النص.
  • الحالة التلقائية: تكون أداة "استخدام خرائط Google كمصدر" غير مفعَّلة تلقائيًا. يجب تفعيلها صراحةً في طلبات بيانات من واجهة برمجة التطبيقات.

الأسعار وحدود الاستخدام

يختلف سعر استخدام "خرائط Google" كمصدر حسب جيل النموذج:

  • نموذج Gemini 3 والإصدارات الأحدث: يتم تحصيل رسوم من مشروعك مقابل كل طلب بحث يقرّر النموذج تنفيذه، مع توفير 5,000 طلب مجاني شهريًا تتم مشاركتها بين جميع نماذج Gemini 3 والإصدارات الأحدث، ثم 14 دولار أمريكي لكل 1,000 طلب بحث. قد يؤدي طلب بحث واحد (طلب بيانات من واجهة برمجة التطبيقات إلى النموذج) إلى تنفيذ النموذج لطلبات بحث متعددة للعثور على المعلومات اللازمة. يُحتسب كل طلب بحث من هذه الطلبات كاستخدام خاضع للفوترة للأداة.
  • ‫Gemini 2.5 والنماذج الأقدم: يتم تحصيل رسوم مقابل كل طلب بحث في مشروعك ($25 لكل 1,000 طلب بحث مستند إلى بيانات خارجية). لا يتم تحصيل رسوم مقابل الطلب إلا إذا عرضت المطالبة بنجاح نتيجة واحدة على الأقل من نتائج "خرائط Google" المستندة إلى بيانات واقعية، بغض النظر عن عدد طلبات البحث الفردية التي نفّذها النموذج داخليًا للحصول على هذه النتيجة.

تتوافق حصة استخدام "خرائط Google" كمصدر عادةً مع حدود المعدّل الأساسية لنموذج Gemini. للحصول على معلومات مفصّلة حول الأسعار، يُرجى الاطّلاع على صفحة أسعار Gemini API.

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

تتيح النماذج التالية استخدام "خرائط Google" كمصدر:

الطراز استخدام "خرائط Google" كمصدر
Gemini 3.8 Flash ✔️
Gemini 3.6 Flash ✔️
Gemini 3.5 Flash-Lite ✔️
إصدار تجريبي من 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 ✔️

مجموعات الأدوات المتوافقة

يمكنك استخدام ميزة استخدام "خرائط Google" كمصدر مع أدوات مدمجة أخرى، مثل تحديد المصدر من خلال "بحث Search" (متوفرة على Gemini 3.5 Flash-Lite والإصدارات الأحدث من النموذج) لتفعيل المزيد من حالات الاستخدام المعقّدة. تتيح نماذج Gemini 3 أيضًا إمكانية الجمع بين هذه الأدوات المضمّنة والأدوات المخصّصة (طلب تنفيذ وظيفة). يمكنك الاطّلاع على مزيد من المعلومات في صفحة مجموعات الأدوات.

الخطوات التالية