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

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

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

شروع کنید

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

پایتون

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

جاوا اسکریپت

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

استراحت

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

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

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

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

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

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

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

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

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

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

متدها و پارامترهای API

اتصال به زمین با نقشه‌های گوگل از طریق API مربوط به Gemini به عنوان ابزاری در متد generateContent ارائه می‌شود. شما می‌توانید با وارد کردن یک شیء googleMaps در پارامتر tools درخواست خود، اتصال به زمین با نقشه‌های گوگل را فعال و پیکربندی کنید.

جی‌سون

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

ابزار googleMaps می‌تواند علاوه بر این، یک پارامتر بولی enableWidget نیز بپذیرد که برای کنترل برگرداندن یا عدم برگرداندن فیلد googleMapsWidgetContextToken در پاسخ استفاده می‌شود. این می‌تواند برای نمایش یک ویجت Places متنی استفاده شود.

جی‌سون

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

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

جی‌سون

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

درک پاسخ اتصال به زمین

وقتی پاسخی با موفقیت با داده‌های نقشه‌های گوگل (Google Maps) مرتبط می‌شود، پاسخ شامل یک فیلد groundingMetadata است. این داده‌های ساختاریافته برای تأیید ادعاها و ایجاد یک تجربه استناد غنی در برنامه شما و همچنین برآورده کردن الزامات استفاده از سرویس ضروری است.

جی‌سون

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

API مربوط به Gemini اطلاعات زیر را به همراه groundingMetadata برمی‌گرداند:

  • groundingChunks : آرایه‌ای از اشیاء حاوی منابع maps ( uri ، placeId و title ).
  • groundingSupports : آرایه‌ای از تکه‌ها برای اتصال متن پاسخ مدل به منابع موجود در groundingChunks . هر تکه یک محدوده متنی (تعریف شده توسط startIndex و endIndex ) را به یک یا چند groundingChunkIndices پیوند می‌دهد. این کلید ساخت استنادهای درون‌خطی است.
  • googleMapsWidgetContextToken : یک توکن متنی که می‌تواند برای رندر کردن یک ویجت Places متنی استفاده شود.

برای مشاهده‌ی قطعه کدی که نحوه‌ی رندر کردن ارجاعات درون‌خطی در متن را نشان می‌دهد، به مثال موجود در مستندات Grounding with Google Search مراجعه کنید.

نمایش ویجت متنی نقشه‌های گوگل

برای استفاده از googleMapsWidgetContextToken برگردانده شده، باید API جاوا اسکریپت نقشه‌های گوگل را بارگذاری کنید .

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

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

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

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

پایتون

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

جاوا اسکریپت

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

استراحت

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

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

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

پایتون

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

جاوا اسکریپت

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

استراحت

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 Maps درخواست شده است. هنگامی که فعال شود، توکن برگردانده شده می‌تواند برای رندر کردن یک ویجت Places متنی با استفاده از <gmp-places-contextual> component از API جاوا اسکریپت Google Maps استفاده شود.

پایتون

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

جاوا اسکریپت

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

استراحت

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

وقتی ویجت رندر می‌شود، چیزی شبیه به تصویر زیر خواهد بود:

نمونه‌ای از ویجت نقشه‌ها هنگام رندر شدن

الزامات استفاده از سرویس

این بخش الزامات استفاده از سرویس اتصال به زمین با نقشه‌های گوگل را شرح می‌دهد.

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

با هر نتیجه‌ی Grounded گوگل مپ، منابعی را در groundingChunks دریافت خواهید کرد که از هر پاسخ پشتیبانی می‌کنند. فراداده‌های زیر نیز بازگردانده می‌شوند:

  • منبع uri
  • عنوان
  • شناسه

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

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

برای هر منبع در groundingChunks و در grounding_chunks.maps.placeAnswerSources.reviewSnippets ، باید یک پیش‌نمایش لینک با رعایت الزامات زیر ایجاد شود:

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

این تصاویر حداقل شرایط لازم برای نمایش منابع و لینک‌های نقشه‌های گوگل را نشان می‌دهند.

درخواست با پاسخی که منابع را نشان می‌دهد

می‌توانید نمای منابع را کوچک کنید.

سریع با پاسخ و منابع از بین رفته

اختیاری: پیش‌نمایش لینک را با محتوای اضافی، مانند موارد زیر، بهبود دهید:

  • یک فاوآیکون گوگل مپ قبل از انتساب متن گوگل مپ درج شده است.
  • عکسی از آدرس اینترنتی منبع ( og:image ).

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

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

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

  • متن نقشه‌های گوگل را به هیچ وجه تغییر ندهید:
    • حروف بزرگ و کوچک گوگل مپ را تغییر ندهید.
    • نقشه‌های گوگل را در چندین خط نپیچید.
    • نقشه‌های گوگل را به زبان دیگری بومی‌سازی نکنید.
    • با استفاده از ویژگی HTML translate="no" از ترجمه نقشه‌های گوگل توسط مرورگرها جلوگیری کنید.
  • متن نقشه گوگل را مطابق جدول زیر استایل دهید:
ملک سبک
Font family بارگذاری فونت اختیاری است.
Fallback font family هر فونت بدنه‌ی سنس‌سریف که از قبل در محصول شما استفاده شده است یا "سنس‌سریف" برای فراخوانی فونت پیش‌فرض سیستم
Font style عادی
Font weight ۴۰۰
Font color سفید، مشکی (#1F1F1F) یا خاکستری (#5E5E5E). کنتراست (4.5:1) قابل قبول را نسبت به پس‌زمینه حفظ کنید.
Font size
  • حداقل اندازه فونت: 12sp
  • حداکثر اندازه فونت: 16sp
  • برای کسب اطلاعات در مورد sp، به واحدهای اندازه فونت در وب‌سایت Material Design مراجعه کنید.
Spacing عادی

مثال CSS

کد 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;
}

توکن زمینه، شناسه مکان و شناسه نقد و بررسی

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

  • googleMapsWidgetContextToken
  • placeId
  • reviewId

محدودیت‌های مربوط به ذخیره‌سازی در شرایط Grounding with Google Maps اعمال نمی‌شود.

فعالیت و قلمرو ممنوعه

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

  • چین
  • کریمه
  • کوبا
  • جمهوری خلق دونتسک
  • ایران
  • جمهوری خلق لوهانسک
  • کره شمالی
  • سوریه
  • ویتنام

این فهرست ممکن است هر از گاهی به‌روزرسانی شود.

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

  • ارائه موقعیت مکانی کاربر: برای مرتبط‌ترین و شخصی‌سازی‌شده‌ترین پاسخ‌ها، همیشه وقتی موقعیت مکانی کاربر مشخص است، user_location (طول و عرض جغرافیایی) را در پیکربندی googleMapsGrounding خود وارد کنید.
  • رندر کردن ویجت متنی نقشه‌های گوگل: ویجت متنی با استفاده از توکن متنی، googleMapsWidgetContextToken ، رندر می‌شود که در پاسخ API Gemini برگردانده می‌شود و می‌تواند برای رندر کردن محتوای بصری از نقشه‌های گوگل استفاده شود. برای اطلاعات بیشتر در مورد ویجت متنی، به Grounding with Google Maps widget در راهنمای توسعه‌دهندگان گوگل مراجعه کنید.
  • به کاربران نهایی اطلاع دهید: به طور واضح به کاربران نهایی خود اطلاع دهید که از داده‌های نقشه‌های گوگل برای پاسخ به سوالات آنها استفاده می‌شود، به خصوص هنگامی که این ابزار فعال است.
  • نظارت بر تأخیر: برای برنامه‌های مکالمه‌ای، اطمینان حاصل کنید که تأخیر P95 برای پاسخ‌های زمینی در آستانه‌های قابل قبول باقی بماند تا یک تجربه کاربری روان حفظ شود.
  • خاموش کردن در صورت عدم نیاز: اتصال به زمین با نقشه‌های گوگل به طور پیش‌فرض خاموش است. فقط زمانی آن را فعال کنید ( "tools": [{"googleMaps": {}}] ) که یک پرس‌وجو زمینه جغرافیایی مشخصی دارد تا عملکرد و هزینه بهینه شود.

محدودیت‌ها

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

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

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

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

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

می‌توانید قابلیت‌های آنها را در صفحه نمای کلی مدل پیدا کنید.

مدل اتصال به زمین با نقشه‌های گوگل
جمینی ۲.۵ پرو ✔️
فلش جمینی ۲.۵ ✔️
جمینی ۲.۵ فلش-لایت ✔️
فلش جمینی ۲.۰ ✔️

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