تتيح ميزة "الاستناد إلى بيانات خرائط Google" ربط إمكانات الذكاء الاصطناعي التوليدي في Gemini بالبيانات الغنية والدقيقة والحديثة المتوفرة في "خرائط Google". تتيح هذه الميزة للمطوّرين دمج وظائف تستند إلى الموقع الجغرافي في تطبيقاتهم بسهولة. عندما يتضمّن طلب بحث المستخدم سياقًا مرتبطًا ببيانات "خرائط Google"، يستفيد نموذج Gemini من "خرائط Google" لتقديم إجابات دقيقة وحديثة وذات صلة بالموقع الجغرافي المحدّد أو المنطقة العامة التي ذكرها المستخدم.
- ردود دقيقة ومراعية للموقع الجغرافي: يمكنك الاستفادة من البيانات الشاملة والحديثة التي توفّرها "خرائط Google" للاستعلامات الخاصة بموقع جغرافي معيّن.
- تخصيص محسّن: تخصيص الاقتراحات والمعلومات استنادًا إلى المواقع الجغرافية المقدَّمة من المستخدمين
- المعلومات والأدوات السياقية: رموز مميزة سياقية لعرض أدوات تفاعلية من "خرائط Google" إلى جانب المحتوى الذي تم إنشاؤه
البدء
يوضّح هذا المثال كيفية دمج Grounding with Google Maps في تطبيقك لتقديم ردود دقيقة ومراعية للموقع الجغرافي على طلبات المستخدمين. يطلب الطلب اقتراحات محلية مع موقع جغرافي اختياري للمستخدم، ما يتيح لنموذج 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-2.5-flash-lite',
contents=prompt,
config=types.GenerateContentConfig(
# Turn on grounding with Google Maps
tools=[types.Tool(google_maps=types.GoogleMaps())],
# Optionally provide the relevant location context (this is in Los Angeles)
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
lat_lng=types.LatLng(
latitude=34.050481, longitude=-118.248526))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in grounding.grounding_chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
JavaScript
import { GoogleGenAI } from "@google/gnai";
const ai = new GoogleGenAI({});
async function generateContentWithMapsGrounding() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: "What are the best Italian restaurants within a 15-minute walk from here?",
config: {
// Turn on grounding with Google Maps
tools: [{ googleMaps: {} }],
toolConfig: {
retrievalConfig: {
// Optionally provide the relevant location context (this is in Los Angeles)
latLng: {
latitude: 34.050481,
longitude: -118.248526,
},
},
},
},
});
console.log("Generated Response:");
console.log(response.text);
const grounding = response.candidates[0]?.groundingMetadata;
if (grounding?.groundingChunks) {
console.log("-".repeat(40));
console.log("Sources:");
for (const chunk of grounding.groundingChunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
generateContentWithMapsGrounding();
REST
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "What are the best Italian restaurants within a 15-minute walk from here?"
}]
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 34.050481, "longitude": -118.248526}
}
}
}'
طريقة عمل ميزة Grounding with Google Maps
تدمج ميزة "الاستناد إلى بيانات" في "خرائط Google" واجهة Gemini API مع نظام Google الجغرافي المتكامل باستخدام Maps API كمصدر للاستناد إلى البيانات. عندما يتضمّن طلب المستخدم سياقًا جغرافيًا، يمكن لنموذج Gemini استخدام أداة Grounding with Google Maps. يمكن للنموذج بعد ذلك إنشاء ردود تستند إلى بيانات "خرائط Google" ذات الصلة بالموقع الجغرافي المقدَّم.
تتضمّن العملية عادةً ما يلي:
- طلب بحث من المستخدم: يرسل المستخدم طلب بحث إلى تطبيقك، وقد يتضمّن هذا الطلب سياقًا جغرافيًا (مثلاً، مقاهٍ بالقرب مني" أو "متاحف في دبي").
- استدعاء الأداة: يستدعي نموذج Gemini أداة Grounding with Google Maps بعد أن يتعرّف على النية الجغرافية. يمكن توفير هذه الأداة اختياريًا مع
latitude
وlongitude
الخاصين بالمستخدم للحصول على نتائج تستند إلى الموقع الجغرافي. - استرداد البيانات: تستعلم خدمة Grounding with Google Maps من "خرائط Google" عن المعلومات ذات الصلة (مثل الأماكن والمراجعات والصور والعناوين وساعات العمل).
- الإنشاء المستند إلى مصادر: يتم استخدام بيانات "خرائط Google" التي تم استرجاعها لإبلاغ نموذج Gemini بالرد، ما يضمن الدقة الواقعية ومدى الصلة بالموضوع.
- رمز الردّ والأداة: يعرض النموذج ردًا نصيًا يتضمّن اقتباسات من مصادر "خرائط Google". يمكن أن يتضمّن ردّ واجهة برمجة التطبيقات اختياريًا
google_maps_widget_context_token
، ما يتيح للمطوّرين عرض أداة سياقية من "خرائط Google" في تطبيقاتهم للتفاعل المرئي.
أسباب استخدام ميزة "الاستناد إلى خرائط Google" وحالات استخدامها
تُعدّ عملية الربط بـ "خرائط Google" مثالية للتطبيقات التي تتطلّب معلومات دقيقة وحديثة وخاصة بالموقع الجغرافي. تعمل هذه الميزة على تحسين تجربة المستخدم من خلال توفير محتوى ملائم ومخصّص استنادًا إلى قاعدة بيانات "خرائط Google" الشاملة التي تضم أكثر من 250 مليون مكان حول العالم.
يجب استخدام Grounding with Google Maps عندما يحتاج تطبيقك إلى:
- تقديم إجابات كاملة ودقيقة عن الأسئلة الخاصة بمنطقة جغرافية معيّنة
- إنشاء أدوات تخطيط رحلات ومساعدين محليين مستندين إلى المحادثات
- اقتراح نقاط الاهتمام استنادًا إلى الموقع الجغرافي وإعدادات المستخدم المفضّلة، مثل المطاعم أو المتاجر
- إنشاء تجارب تستند إلى الموقع الجغرافي للخدمات الاجتماعية أو خدمات البيع بالتجزئة أو توصيل الطعام
تتفوّق ميزة "الاستناد إلى بيانات من خرائط Google" في حالات الاستخدام التي تكون فيها القرب المكاني والبيانات الواقعية الحالية مهمة، مثل العثور على "أفضل مقهى بالقرب مني" أو الحصول على اتجاهات.
طُرق واجهة برمجة التطبيقات والمَعلمات
يتم عرض ميزة "الاستناد إلى بيانات Google Maps" من خلال Gemini API كأداة ضمن الطريقة generateContent
. يمكنك تفعيل ميزة Grounding with Google Maps وضبطها من خلال تضمين عنصر googleMaps
في المَعلمة tools
من طلبك.
JSON
{
"contents": [{
"parts": [
{"text": "Restaurants near Times Square."}
]
}],
"tools": { "googleMaps": {} }
}
يمكن لأداة googleMaps
أيضًا قبول مَعلمة enableWidget
منطقية، تُستخدَم للتحكّم في ما إذا كان سيتم عرض الحقل googleMapsWidgetContextToken
في الردّ. ويمكن استخدامها لعرض أداة سياقية خاصة بـ "أماكن Google".
JSON
{
"contents": [{
"parts": [
{"text": "Restaurants near Times Square."}
]
}],
"tools": { "googleMaps": { "enableWidget": true } }
}
بالإضافة إلى ذلك، تتيح الأداة تمرير الموقع الجغرافي السياقي كـ 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"
],
"googleMapsWidgetContextToken": "widgetcontent/..."
}
}
]
}
تعرض Gemini API المعلومات التالية مع
groundingMetadata
:
groundingChunks
: مصفوفة من العناصر التي تحتوي على مصادرmaps
(uri
وplaceId
وtitle
).groundingSupports
: مصفوفة من الأجزاء لربط نص ردّ النموذج بالمستندات المصدر فيgroundingChunks
يربط كل جزء نطاقًا نصيًا (محدّدًا بواسطةstartIndex
وendIndex
) بواحدة أو أكثر منgroundingChunkIndices
. هذا هو المفتاح لإنشاء استشهادات مضمّنة.googleMapsWidgetContextToken
: رمز مميّز نصي يمكن استخدامه لعرض أداة Places السياقية.
للحصول على مقتطف رمز يعرض كيفية عرض الاقتباسات المضمّنة في النص، يمكنك الاطّلاع على المثال في مستندات Grounding with Google Search.
عرض الأداة السياقية من "خرائط Google"
لاستخدام googleMapsWidgetContextToken
الذي تم عرضه، عليك تحميل
Google Maps JavaScript
API.
حالات الاستخدام
تتيح ميزة "الاستناد إلى بيانات واقعية" في "خرائط Google" مجموعة متنوعة من حالات الاستخدام التي تعتمد على الموقع الجغرافي. توضّح الأمثلة التالية كيف يمكن أن تستفيد الطلبات والمَعلمات المختلفة من ميزة Grounding with Google Maps. قد تختلف المعلومات الواردة في النتائج المستندة إلى بيانات واقعية في "خرائط 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-2.5-flash-lite',
contents=prompt,
config=types.GenerateContentConfig(
# Turn on the Maps tool
tools=[types.Tool(google_maps=types.GoogleMaps())],
# Provide the relevant location context (this is in Los Angeles)
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
lat_lng=types.LatLng(
latitude=34.050481, longitude=-118.248526))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if chunks := grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
```
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-2.5-flash',
contents: prompt,
config: {
// Turn on the Maps tool
tools: [{googleMaps: {}}],
// Provide the relevant location context (this is in Los Angeles)
toolConfig: {
retrievalConfig: {
latLng: {
latitude: 34.050481,
longitude: -118.248526
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
if (chunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of chunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
run();
REST
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
}]
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 34.050481, "longitude": -118.248526}
}
}
}'
توفير ميزة التخصيص المستندة إلى الموقع الجغرافي
الحصول على اقتراحات مخصّصة حسب إعدادات المستخدِم المفضّلة ومنطقة جغرافية معيّنة
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-2.5-flash',
contents=prompt,
config=types.GenerateContentConfig(
tools=[types.Tool(google_maps=types.GoogleMaps())],
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
# Provide the location as context; this is Austin, TX.
lat_lng=types.LatLng(
latitude=30.2672, longitude=-97.7431))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if chunks := grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
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-2.5-flash',
contents: prompt,
config: {
tools: [{googleMaps: {}}],
toolConfig: {
retrievalConfig: {
// Provide the location as context; this is Austin, TX.
latLng: {
latitude: 30.2672,
longitude: -97.7431
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
if (chunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of chunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
run();
REST
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Which family-friendly restaurants near here have the best playground reviews?"
}],
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 30.2672, "longitude": -97.7431}
}
}
}'
المساعدة في التخطيط لبرنامج الرحلة
إنشاء خطط لعدة أيام تتضمّن الاتجاهات والمعلومات حول مواقع جغرافية مختلفة، ما يجعلها مثالية لتطبيقات السفر
في هذا المثال، تم طلب googleMapsWidgetContextToken
من خلال تفعيل التطبيق المصغّر في أداة "خرائط Google". عند تفعيل هذه الميزة، يمكن استخدام الرمز المميّز الذي يتم عرضه
لعرض أداة Places مستندة إلى السياق باستخدام <gmp-places-contextual> component
من Google Maps JavaScript API.
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-2.5-flash',
contents=prompt,
config=types.GenerateContentConfig(
tools=[types.Tool(google_maps=types.GoogleMaps(enable_widget=True))],
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
# Provide the location as context, this is in San Francisco.
lat_lng=types.LatLng(
latitude=37.78193, longitude=-122.40476))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in grounding.grounding_chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
if widget_token := grounding.google_maps_widget_context_token:
print('-' * 40)
print(f'<gmp-place-contextual context-token="{widget_token}"></gmp-place-contextual>')
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-2.5-flash',
contents: prompt,
config: {
tools: [{googleMaps: {enableWidget: true}}],
toolConfig: {
retrievalConfig: {
// Provide the location as context, this is in San Francisco.
latLng: {
latitude: 37.78193,
longitude: -122.40476
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const groundingMetadata = response.candidates[0]?.groundingMetadata;
if (groundingMetadata) {
if (groundingMetadata.groundingChunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of groundingMetadata.groundingChunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
if (groundingMetadata.googleMapsWidgetContextToken) {
console.log('-'.repeat(40));
document.body.insertAdjacentHTML('beforeend', `<gmp-place-contextual context-token="${groundingMetadata.googleMapsWidgetContextToken}`"></gmp-place-contextual>`);
}
}
}
run();
REST
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."
}]
}],
"tools": [{"googleMaps": {"enableWidget":"true"}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 37.78193, "longitude": -122.40476}
}
}
}'
عند عرض التطبيق المصغّر، سيبدو على النحو التالي:
متطلبات استخدام الخدمة
يوضّح هذا القسم متطلبات استخدام خدمة "التأسيس باستخدام خرائط Google".
إبلاغ المستخدم بشأن استخدام مصادر "خرائط Google"
مع كل "نتيجة مستنِدة إلى بيانات جغرافية" في "خرائط Google"، ستتلقّى مصادر groundingChunks
تستند إليها كل إجابة. يتم أيضًا عرض البيانات الوصفية التالية:
- معرّف الموارد المنتظم (URI) للمصدر
- title
- رقم التعريف
عند عرض نتائج من Grounding with Google Maps، يجب تحديد مصادر "خرائط Google" المرتبطة وإبلاغ المستخدمين بما يلي:
- يجب أن تظهر مصادر "خرائط Google" مباشرةً بعد المحتوى الذي تم إنشاؤه والذي تدعمه هذه المصادر. يُشار إلى هذا المحتوى الذي يتم إنشاؤه أيضًا باسم "النتيجة المستندة إلى معلومات جغرافية" في "خرائط Google".
- يجب أن تكون مصادر "خرائط Google" قابلة للعرض من خلال تفاعل واحد من المستخدم.
عرض مصادر "خرائط Google" مع روابط "خرائط Google"
بالنسبة إلى كل مصدر في groundingChunks
وgrounding_chunks.maps.placeAnswerSources.reviewSnippets
، يجب إنشاء معاينة للرابط وفقًا للمتطلبات التالية:
- يجب الإشارة إلى مصدر كل محتوى في "خرائط Google" باتّباع إرشادات الإشارة إلى المصدر.
- عرض عنوان المستند المصدر المقدَّم في الردّ
- انقر على
uri
أوgoogleMapsUri
من الردّ للانتقال إلى المصدر.
تعرض هذه الصور الحد الأدنى من المتطلبات لعرض المصادر وروابط "خرائط Google".
يمكنك تصغير عرض المصادر.
اختياري: تحسين معاينة الرابط باستخدام محتوى إضافي، مثل:
- يتم إدراج رمز مفضّل لـ "خرائط Google" قبل بيان مصدر البيانات النصي الخاص بـ "خرائط Google".
- تمثّل هذه السمة صورة من عنوان URL المصدر (
og:image
).
لمزيد من المعلومات حول بعض مزوّدي بيانات "خرائط 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 |
|
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" رمز السياق ومعرّف المكان ومعرّف المراجعة. يمكنك تخزين بيانات الردود التالية مؤقتًا وتصديرها:
googleMapsWidgetContextToken
placeId
reviewId
لا تنطبق القيود المفروضة على التخزين المؤقت في "بنود خدمة Grounding with Google Maps".
النشاط والأراضي المحظورة
تفرض ميزة "الاستناد إلى بيانات خرائط Google" قيودًا إضافية على بعض المحتوى والأنشطة للحفاظ على أمان المنصة وموثوقيتها. بالإضافة إلى قيود الاستخدام الواردة في البنود، لن تستخدم ميزة Grounding with Google Maps في الأنشطة عالية الخطورة، بما في ذلك خدمات الاستجابة لحالات الطوارئ. لن توزع أو تسوّق تطبيقك الذي يوفّر ميزة Grounding with Google Maps في منطقة محظورة. المناطق المحظورة الحالية هي:
- الصين
- شبه جزيرة القرم
- كوبا
- جمهورية دونيتسك الشعبية
- إيران
- جمهورية لوهانسك الشعبية
- كوريا الشمالية
- سوريا
- فيتنام
وقد يتم تعديل هذه القائمة من حين لآخر.
أفضل الممارسات
- توفير الموقع الجغرافي للمستخدم: للحصول على الردود الأكثر صلة وتخصيصًا، احرص دائمًا على تضمين
user_location
(خطوط الطول والعرض) في إعداداتgoogleMapsGrounding
عندما يكون الموقع الجغرافي للمستخدم معروفًا. - عرض التطبيق المصغّر السياقي في "خرائط Google": يتم عرض التطبيق المصغّر السياقي باستخدام الرمز المميّز الخاص بالسياق،
googleMapsWidgetContextToken
، الذي يتم عرضه في ردّ واجهة Gemini API ويمكن استخدامه لعرض المحتوى المرئي من "خرائط Google". لمزيد من المعلومات حول الأداة السياقية، يُرجى الاطّلاع على مقالة أداة "الاستناد إلى خرائط Google" في "دليل المطوّرين من Google". - إعلام المستخدمين النهائيين: يجب إعلام المستخدمين النهائيين بوضوح بأنّه يتم استخدام بيانات "خرائط Google" للرد على طلباتهم، خاصةً عند تفعيل الأداة.
- مراقبة وقت الاستجابة: بالنسبة إلى التطبيقات الحوارية، تأكَّد من أنّ وقت الاستجابة P95 للردود المستندة إلى بيانات خارجية يظل ضمن الحدود المقبولة للحفاظ على تجربة مستخدم سلسة.
- إيقاف الميزة عند عدم الحاجة إليها: تكون ميزة "التحديد الأرضي" في "خرائط Google" غير مفعّلة تلقائيًا. لا تفعِّلها (
"tools": [{"googleMaps": {}}]
) إلا عندما يكون للاستعلام سياق جغرافي واضح، وذلك لتحسين الأداء والتكلفة.
القيود
- النطاق الجغرافي: تتوفّر ميزة Grounding with Google Maps حاليًا على مستوى العالم.
- نماذج متوافقة: تتوافق ميزة "الاستناد إلى مصادر" مع "خرائط Google" مع نماذج Gemini 2.5 Flash-Lite وGemini 2.5 Pro وGemini 2.5 Flash وGemini 2.0 Flash فقط (وليس Gemini 2.0 Flash Lite).
- الإدخالات/المخرجات المتعددة الوسائط: لا تتيح ميزة "الاستناد إلى خرائط Google" حاليًا الإدخالات أو المخرجات المتعددة الوسائط بخلاف النص وwidgets الخاصة بالخرائط السياقية.
- الحالة التلقائية: تكون أداة "الاستناد إلى خرائط Google" غير مفعّلة تلقائيًا. يجب تفعيلها صراحةً في طلبات واجهة برمجة التطبيقات.
الأسعار وحدود المعدّل
تستند عملية تحديد الأسعار في ميزة Grounding with Google Maps إلى عدد طلبات البحث. يبلغ السعر الحالي 25 دولارًا أمريكيًا لكل 1,000 طلب مستند إلى بيانات واقعية. لا يتم احتساب الطلب ضمن الحصة إلا عندما يعرض الردّ بنجاح نتيجة واحدة على الأقل من نتائج "خرائط Google" المستندة إلى بيانات واقعية (أي النتائج التي تتضمّن مصدرًا واحدًا على الأقل من "خرائط Google"). إذا تم إرسال طلبات بحث متعددة إلى "خرائط Google" من طلب واحد، سيتم احتسابها كطلب واحد ضمن الحد الأقصى لعدد الطلبات.
للحصول على معلومات مفصّلة عن الأسعار، يُرجى الاطّلاع على صفحة أسعار Gemini API.
النماذج المتوافقة
يمكنك الاطّلاع على إمكاناتها في صفحة نظرة عامة على النموذج.
الطراز | تحديد المصادر باستخدام "خرائط Google" |
---|---|
Gemini 2.5 Pro | ✔️ |
Gemini 2.5 Flash | ✔️ |
Gemini 2.5 Flash-Lite | ✔️ |
Gemini 2.0 Flash | ✔️ |
الخطوات التالية
- جرِّب كتاب الطبخ الخاص بميزة "الاستناد إلى معلومات من بحث Google" في Gemini API.
- يمكنك التعرّف على الأدوات الأخرى المتاحة، مثل استدعاء الدوال.
- لمزيد من المعلومات حول أفضل ممارسات الذكاء الاصطناعي المسؤول وفلاتر الأمان في Gemini API، يُرجى الاطّلاع على دليل إعدادات الأمان.