تدمج ميزة "استخدام خرائط Google كمصدر" الإمكانات التوليدية لـ Gemini مع البيانات الغنية والحقيقية والحديثة في "خرائط Google". تتيح هذه الميزة للمطوّرين دمج وظائف تستند إلى الموقع الجغرافي بسهولة في تطبيقاتهم. عندما يتضمّن طلب المستخدم سياقًا مرتبطًا ببيانات "خرائط Google"، يستفيد نموذج Gemini من "خرائط Google" لتقديم إجابات دقيقة ومحدّثة ذات صلة بالموقع الجغرافي الذي حدّده المستخدم أو المنطقة العامة.
- ردود دقيقة ومستندة إلى الموقع الجغرافي: يمكنك الاستفادة من البيانات الواسعة والنطاق والحديثة في "خرائط 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' \
-H "Api-Revision: 2026-05-20" \
-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" ذات الصلة بالموقع الجغرافي المقدَّم.
تتضمّن العملية عادةً ما يلي:
- طلب المستخدم: يرسل المستخدم طلبًا إلى تطبيقك، وقد يتضمّن سياقًا جغرافيًا (مثل "مقاهي بالقرب مني" أو "متاحف في سان فرانسيسكو").
- استدعاء الأداة: يستدعي نموذج Gemini أداة "استخدام "خرائط Google" كمصدر" بعد التعرّف على الغرض الجغرافي من الطلب. يمكن تزويد هذه الأداة اختياريًا بـ
و
latitudeوlongitudeللمستخدم. الأداة هي أداة بحث نصي وتعمل بطريقة مشابهة للبحث في "خرائط Google"، حيث ستستخدم الطلبات المحلية ("بالقرب مني") الإحداثيات، بينما من غير المرجّح أن تتأثر الطلبات المحدّدة أو غير المحلية بالموقع الجغرافي الصريح. - استرجاع البيانات: تطلب خدمة "استخدام "خرائط Google" كمصدر" معلومات ذات صلة من "خرائط Google" (مثل الأماكن والمراجعات والصور والعناوين وساعات العمل).
- الإنشاء المستند إلى المصدر: يتم استخدام بيانات "خرائط Google" التي تم استرجاعها لتقديم ردّ نموذج Gemini، ما يضمن الدقة والصلة بالوقائع.
- الردّ والتعليقات التوضيحية: يعرض النموذج ردًا نصيًا يتضمّن تعليقات توضيحية مضمّنة ترتبط بمصادر "خرائط Google"، ما يتيح للمطوّرين عرض الاقتباسات وعرض أداة سياقية من "خرائط 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,
"enable_widget": True
}]
)
# ... code to process response and widget token
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,
enable_widget: true
}]
});
}
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' \
-H "Api-Revision: 2026-05-20" \
-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,
"enable_widget": true
}]
}'
متطلبات استخدام الخدمة
يصف هذا القسم متطلبات استخدام خدمة "تحديد المصدر باستخدام خرائط 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_maps_widget_context_tokenالذي يتم عرضه في ردّ Gemini API ويمكن استخدامه لعرض محتوى مرئي من "خرائط Google". - إعلام المستخدمين النهائيين: عليك إعلام المستخدمين النهائيين بوضوح بأنّه يتم استخدام بيانات "خرائط Google" للإجابة عن طلباتهم، خاصةً عند تفعيل الأداة.
- إيقاف الأداة عند عدم الحاجة إليها: تكون ميزة "استخدام "خرائط Google" كمصدر" غير مفعّلة تلقائيًا. عليك تفعيلها فقط (
"tools": [{"type": "google_maps"}]) عندما يتضمّن الطلب سياقًا جغرافيًا واضحًا، وذلك لتحسين الأداء والتكلفة.
القيود
- لا تتيح ميزة "استخدام "خرائط Google" كمصدر" حاليًا سوى الطلبات والردود باللغة الإنجليزية.
- قد لا تتوفّر الأداة في بعض المناطق.
- قد تختلف النتائج استنادًا إلى دقة الموقع الجغرافي وبيانات "خرائط Google" المتاحة.
- النطاق الجغرافي: تتوفّر ميزة "استخدام "خرائط Google" كمصدر" على مستوى العالم.
- الحالة التلقائية: تكون أداة "استخدام "خرائط Google" كمصدر" غير مفعّلة تلقائيًا. عليك تفعيلها صراحةً في طلبات البيانات من واجهة برمجة التطبيقات.
التسعير وحدود المعدّل
يستند تسعير ميزة "استخدام خرائط Google كمصدر" إلى الطلبات. يبلغ المعدّل الحالي 25 دولارًا أمريكيًا لكل 1,000 طلب مستند إلى المصدر. يتضمّن المستوى المجاني أيضًا ما يصل إلى 500 طلب في اليوم. لا يتم احتساب الطلب ضمن الحصة إلا عندما يعرض الطلب بنجاح نتيجة واحدة على الأقل مستندة إلى "خرائط Google" (أي نتائج تحتوي على مصدر واحد على الأقل من "خرائط Google"). إذا تم إرسال طلبات متعددة إلى "خرائط Google" من طلب واحد، يتم احتسابها كطلب واحد ضمن حدّ المعدّل.
للحصول على معلومات مفصّلة عن الأسعار، اطّلِع على صفحة أسعار Gemini API.
النماذج المتوافقة
تتيح النماذج التالية ميزة "استخدام خرائط Google كمصدر":
| الطراز | استخدام "خرائط Google" كمصدر |
|---|---|
| Gemini 3.5 Flash | ✔️ |
| Gemini 3.1 Pro Preview | ✔️ |
| Gemini 3.1 Flash-Lite | ✔️ |
| Gemini 3.1 Flash-Lite Preview | ✔️ |
| Gemini 3 Flash Preview | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
| Gemini 2.0 Flash | ✔️ |
مجموعات الأدوات المتوافقة
تتيح نماذج Gemini 3 الجمع بين الأدوات المضمّنة (مثل "تحديد المصدر باستخدام خرائط Google") والأدوات المخصّصة (استدعاء الدوال). مزيد من المعلومات في صفحة مجموعات الأدوات.
الخطوات التالية
- مزيد من المعلومات عن الأدوات الأخرى المتاحة.
- لمزيد من المعلومات عن أفضل ممارسات الذكاء الاصطناعي المسؤول وفلاتر الأمان في Gemini API ، اطّلِع على دليل إعدادات الأمان.