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

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

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

البدء

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

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="What are the best Italian restaurants within a 15-minute walk from here?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

# Print the model's text response and annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "What are the best Italian restaurants within a 15-minute walk from here?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  // Print the model's text response and annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - {annotation.name}: {annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "latitude": 34.050481,
      "longitude": -118.248526
    }]
  }'

آلية عمل ميزة "تحديد المصدر من خلال خرائط Google"

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

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

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

أسباب استخدام ميزة "تحديد المصدر من خلال خرائط Google" والحالات التي يجب استخدامها فيها

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

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

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

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

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

تتيح ميزة "تحديد المصدر من خلال خرائط Google" مجموعة متنوعة من حالات الاستخدام التي تستند إلى الموقع الجغرافي.

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

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

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

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

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

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Which family-friendly restaurants near here have the best playground reviews?",
    tools=[{
        "type": "google_maps",
        "latitude": 30.2672,
        "longitude": -97.7431
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Which family-friendly restaurants near here have the best playground reviews?",
    tools: [{
      type: "google_maps",
      latitude: 30.2672,
      longitude: -97.7431
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

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

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

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476
    }]
)
# ... code to process response

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.",
    tools: [{
      type: "google_maps",
      latitude: 37.78193,
      longitude: -122.40476
    }]
  });
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.",
    "tools": [{
      "type": "google_maps",
      "latitude": 37.78193,
      "longitude": -122.40476
    }]
  }'

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

يصف هذا القسم متطلبات استخدام خدمة "تحديد المصدر من خلال خرائط Google".

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

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

  • عنوان URL للمصدر
  • الاسم

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

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

عرض مصادر "خرائط Google" مع روابط "خرائط Google"

لكل تعليق توضيحي للمصدر، يجب إنشاء معاينة للرابط وفقًا للمتطلبات التالية:

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

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

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

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

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

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

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

القيود

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

الأسعار والحدود القصوى للطلبات

تختلف أسعار ميزة "تحديد المصدر من خلال خرائط Google" استنادًا إلى إنشاء النموذج:

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

للحصول على معلومات مفصّلة عن الأسعار، اطّلِع على صفحة أسعار Gemini API.

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

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

الطراز تحديد المصدر من خلال خرائط Google
Gemini 3.5 Flash ✔️
Gemini 3.1 Pro Preview ✔️
Gemini 3.1 Flash-Lite ✔️
Gemini 3 Flash Preview ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

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

تتيح نماذج Gemini 3 الجمع بين الأدوات المضمّنة (مثل "تحديد المصدر من خلال خرائط Google") والأدوات المخصّصة (استدعاء الدوال). يمكنك الاطّلاع على مزيد من المعلومات في صفحة مجموعات الأدوات.

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

  • التعرّف على الأدوات الأخرى المتاحة.
  • لمزيد من المعلومات حول أفضل ممارسات الذكاء الاصطناعي المسؤول وفلاتر الأمان في Gemini API، اطّلِع على دليل إعدادات الأمان.