زمین با نقشه گوگل

اتصال به نقشه‌های گوگل، قابلیت‌های تولیدی Gemini را با داده‌های غنی، واقعی و به‌روز نقشه‌های گوگل مرتبط می‌کند. این ویژگی به توسعه‌دهندگان این امکان را می‌دهد که به راحتی قابلیت‌های آگاه از مکان را در برنامه‌های خود بگنجانند. هنگامی که یک پرس‌وجوی کاربر زمینه‌ای مرتبط با داده‌های نقشه‌ها دارد، مدل Gemini از نقشه‌های گوگل برای ارائه پاسخ‌های دقیق و به‌روز مرتبط با مکان یا منطقه عمومی مشخص شده توسط کاربر استفاده می‌کند.

• پاسخ‌های دقیق و آگاه از موقعیت مکانی: از داده‌های گسترده و به‌روز گوگل مپ برای پرسش‌های جغرافیایی خاص استفاده کنید.
• شخصی‌سازی پیشرفته: توصیه‌ها و اطلاعات را بر اساس مکان‌های ارائه شده توسط کاربر تنظیم کنید.
• اطلاعات و ابزارک‌های زمینه‌ای: توکن‌های زمینه‌ای برای رندر ابزارک‌های تعاملی نقشه‌های گوگل در کنار محتوای تولید شده.

شروع کنید

این مثال نشان می‌دهد که چگونه Grounding را با Google Maps در برنامه خود ادغام کنید تا پاسخ‌های دقیق و آگاه از موقعیت مکانی به سؤالات کاربر ارائه دهید. این اعلان از شما توصیه‌های محلی با موقعیت مکانی اختیاری کاربر را درخواست می‌کند و مدل Gemini را قادر می‌سازد از داده‌های Google Maps استفاده کند.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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}")

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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();

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-flash-preview",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "latitude": 34.050481,
      "longitude": -118.248526
    }]
  }'

نحوه اتصال به زمین با نقشه‌های گوگل

اتصال به زمین با نقشه‌های گوگل، با استفاده از API نقشه‌ها به عنوان منبع اتصال به زمین، رابط برنامه‌نویسی Gemini را با اکوسیستم Google Geo ادغام می‌کند. هنگامی که پرس‌وجوی کاربر شامل زمینه جغرافیایی باشد، مدل Gemini می‌تواند ابزار اتصال به زمین با نقشه‌های گوگل را فراخوانی کند. سپس این مدل می‌تواند پاسخ‌هایی را بر اساس داده‌های نقشه‌های گوگل مرتبط با مکان ارائه شده تولید کند.

این فرآیند معمولاً شامل موارد زیر است:

1. پرس‌وجوی کاربر: کاربر پرس‌وجویی را به برنامه شما ارسال می‌کند که احتمالاً شامل زمینه جغرافیایی نیز می‌شود (مثلاً «کافی شاپ‌های نزدیک من»، «موزه‌های سانفرانسیسکو»).
2. فراخوانی ابزار: مدل Gemini، با تشخیص هدف جغرافیایی، ابزار Grounding with Google Maps را فراخوانی می‌کند. این ابزار می‌تواند به صورت اختیاری latitude و longitude جغرافیایی کاربر را در اختیار قرار دهد. این ابزار یک ابزار جستجوی متنی است و مشابه جستجو در Maps رفتار می‌کند، به این صورت که جستجوهای محلی ("نزدیک من") از مختصات استفاده می‌کنند، در حالی که جستجوهای خاص یا غیر محلی بعید است که تحت تأثیر مکان صریح قرار گیرند.
3. بازیابی داده‌ها: سرویس Grounding with Google Maps اطلاعات مرتبط (مثلاً مکان‌ها، نظرات، عکس‌ها، آدرس‌ها، ساعات کاری) را از Google Maps جستجو می‌کند.
4. تولید مبتنی بر داده: داده‌های بازیابی‌شده‌ی Maps برای اطلاع‌رسانی به پاسخ مدل Gemini استفاده می‌شوند و دقت و ارتباط واقعی را تضمین می‌کنند.
5. پاسخ و حاشیه‌نویسی‌ها: این مدل یک پاسخ متنی با حاشیه‌نویسی‌های درون‌خطی که به منابع نقشه‌های گوگل لینک می‌دهند، برمی‌گرداند و به توسعه‌دهندگان اجازه می‌دهد تا استنادها را نمایش دهند و به صورت اختیاری یک ویجت نقشه‌های گوگل متنی را رندر کنند.

چرا و چه زمانی از اتصال به زمین با نقشه‌های گوگل استفاده کنیم؟

اتصال به زمین با نقشه‌های گوگل برای برنامه‌هایی که نیاز به اطلاعات دقیق، به‌روز و مختص به مکان دارند، ایده‌آل است. این سرویس با ارائه محتوای مرتبط و شخصی‌سازی‌شده که توسط پایگاه داده گسترده نقشه‌های گوگل با بیش از ۲۵۰ میلیون مکان در سراسر جهان پشتیبانی می‌شود، تجربه کاربری را بهبود می‌بخشد.

شما باید زمانی از اتصال به زمین با نقشه‌های گوگل استفاده کنید که برنامه شما نیاز به موارد زیر داشته باشد:

• به سوالات مربوط به جغرافیا پاسخ‌های کامل و دقیقی ارائه دهید.
• برنامه‌ریزان سفر و راهنمایان محلیِ اهل مکالمه بسازید.
• نقاط مورد علاقه را بر اساس موقعیت مکانی و ترجیحات کاربر مانند رستوران‌ها یا مغازه‌ها پیشنهاد دهید.
• برای خدمات اجتماعی، خرده‌فروشی یا تحویل غذا، تجربیات مبتنی بر موقعیت مکانی ایجاد کنید.

اتصال زمینی با نقشه‌های گوگل در مواردی که نزدیکی و داده‌های واقعی فعلی حیاتی هستند، مانند یافتن «بهترین کافی‌شاپ نزدیک من» یا دریافت مسیر، بسیار عالی عمل می‌کند.

موارد استفاده

اتصال به زمین با نقشه‌های گوگل از موارد استفاده متنوعی با توجه به موقعیت مکانی پشتیبانی می‌کند.

رسیدگی به سوالات مربوط به مکان

سوالات دقیقی در مورد یک مکان خاص بپرسید تا بر اساس نظرات کاربران گوگل و سایر داده‌های نقشه، پاسخ دریافت کنید.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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}")

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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();

ارائه شخصی‌سازی مبتنی بر مکان

توصیه‌هایی متناسب با ترجیحات کاربر و یک منطقه جغرافیایی خاص دریافت کنید.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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}")

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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();

کمک به برنامه‌ریزی مسیر سفر

برنامه‌های چند روزه را با مسیرها و اطلاعات مربوط به مکان‌های مختلف ایجاد کنید، مناسب برای برنامه‌های سفر.

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-flash-preview",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476,
        "enable_widget": True
    }]
)
# ... code to process response and widget token

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    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,
      enableWidget: true
    }],
});

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-flash-preview",
    "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 Maps Grounded، حاشیه‌نویسی‌های منبع را در بلوک‌های محتوای مرحله‌ی model_output دریافت خواهید کرد که از هر پاسخ پشتیبانی می‌کنند. فراداده‌های زیر بازگردانده می‌شوند:

• آدرس اینترنتی منبع
• نام

هنگام ارائه نتایج حاصل از Grounding with Google Maps، باید منابع مرتبط با Google Maps را مشخص کنید و موارد زیر را به کاربران خود اطلاع دهید:

• منابع نقشه‌های گوگل باید بلافاصله پس از محتوای تولید شده‌ای که منابع از آن پشتیبانی می‌کنند، قرار گیرند. این محتوای تولید شده همچنین به عنوان نتایج مبتنی بر نقشه‌های گوگل (Google Maps Grounded Result) شناخته می‌شود.
• منابع نقشه‌های گوگل باید در یک تعامل کاربری قابل مشاهده باشند.

نمایش منابع نقشه‌های گوگل با لینک‌های نقشه‌های گوگل

برای هر حاشیه‌نویسی منبع، باید پیش‌نمایش لینک مطابق با الزامات زیر ایجاد شود:

• هر منبع را با پیروی از دستورالعمل‌های انتساب متن گوگل مپ به گوگل مپ نسبت دهید.
• نام منبع ارائه شده در پاسخ را نمایش بده.
• با استفاده از url موجود در حاشیه‌نویسی، به منبع لینک دهید.

دستورالعمل‌های انتساب متن در گوگل مپ

وقتی منابع را در متن به نقشه‌های گوگل نسبت می‌دهید، این دستورالعمل‌ها را دنبال کنید:

• متن نقشه‌های گوگل را به هیچ وجه تغییر ندهید:
  • حروف بزرگ و کوچک گوگل مپ را تغییر ندهید.
  • نقشه‌های گوگل را در چندین خط نپیچید.
  • نقشه‌های گوگل را به زبان دیگری بومی‌سازی نکنید.
  • با استفاده از ویژگی HTML translate="no" از ترجمه نقشه‌های گوگل توسط مرورگرها جلوگیری کنید.

برای اطلاعات بیشتر در مورد برخی از ارائه‌دهندگان داده‌های Google Maps ما و شرایط مجوز آنها، به اطلاعیه‌های قانونی Google Maps و Google Earth مراجعه کنید.

بهترین شیوه‌ها

• ارائه موقعیت مکانی کاربر: برای مرتبط‌ترین و شخصی‌سازی‌شده‌ترین پاسخ‌ها، همیشه در صورت مشخص بودن موقعیت مکانی کاربر، latitude و longitude را در پیکربندی ابزار google_maps خود وارد کنید.
• رندر کردن ویجت متنی نقشه‌های گوگل: ویجت متنی با استفاده از توکن متنی، google_maps_widget_context_token ، رندر می‌شود که در پاسخ API Gemini برگردانده می‌شود و می‌تواند برای رندر کردن محتوای بصری از نقشه‌های گوگل استفاده شود.
• به کاربران نهایی اطلاع دهید: به طور واضح به کاربران نهایی خود اطلاع دهید که از داده‌های نقشه‌های گوگل برای پاسخ به سوالات آنها استفاده می‌شود، به خصوص هنگامی که این ابزار فعال است.
• خاموش کردن در صورت عدم نیاز: اتصال به زمین با نقشه‌های گوگل به طور پیش‌فرض خاموش است. فقط زمانی آن را فعال کنید ( "tools": [{"type": "google_maps"}] ) که یک پرس‌وجو زمینه جغرافیایی مشخصی دارد، تا عملکرد و هزینه بهینه شود.

محدودیت‌ها

• اتصال به زمین با نقشه‌های گوگل در حال حاضر فقط از پیام‌ها و پاسخ‌های زبان انگلیسی پشتیبانی می‌کند.
• این ابزار ممکن است در همه مناطق در دسترس نباشد.
• نتایج ممکن است بسته به دقت مکان و داده‌های نقشه موجود متفاوت باشد.
• محدوده جغرافیایی: اتصال به زمین با نقشه‌های گوگل در سراسر جهان در دسترس است.
• حالت پیش‌فرض: ابزار Grounding with Google Maps به طور پیش‌فرض غیرفعال است. شما باید آن را صریحاً در درخواست‌های API خود فعال کنید.

قیمت‌گذاری و محدودیت‌های نرخ

قیمت‌گذاری گراندینگ با گوگل مپ بر اساس پرس‌وجوها است. نرخ فعلی ۲۵ دلار برای هر ۱۰۰۰ درخواست گراندینگ است. سطح رایگان همچنین تا ۵۰۰ درخواست در روز را در دسترس دارد. یک درخواست فقط زمانی جزو سهمیه محسوب می‌شود که یک درخواست با موفقیت حداقل یک نتیجه گراندینگ گوگل مپ را برگرداند (یعنی نتایجی که حداقل شامل یک منبع گوگل مپ باشند). اگر چندین پرس‌وجو از یک درخواست واحد به گوگل مپ ارسال شود، به عنوان یک درخواست از سقف نرخ محاسبه می‌شود.

برای اطلاعات دقیق در مورد قیمت‌گذاری، به صفحه قیمت‌گذاری Gemini API مراجعه کنید.

مدل‌های پشتیبانی‌شده

مدل‌های زیر از اتصال به زمین با نقشه‌های گوگل پشتیبانی می‌کنند:

ترکیب ابزارهای پشتیبانی‌شده

مدل‌های Gemini 3 از ترکیب ابزارهای داخلی (مانند Grounding با Google Maps) با ابزارهای سفارشی (فراخوانی تابع) پشتیبانی می‌کنند. برای کسب اطلاعات بیشتر به صفحه ترکیب ابزارها مراجعه کنید.

قدم بعدی چیست؟

• با سایر ابزارهای موجود آشنا شوید.
• برای کسب اطلاعات بیشتر در مورد بهترین شیوه‌های مسئولانه هوش مصنوعی و فیلترهای ایمنی Gemini API، به راهنمای تنظیمات ایمنی مراجعه کنید.