جستجوی مکان‌ها

ابزار search_places به مدل زبانی بزرگ امکان می‌دهد مکان‌ها را در Google Maps ازطریق پرسمان زبان طبیعی پیدا کند. این ابزار خلاصه‌ای از مکان‌های منطبق را که با هوش مصنوعی تولید شده است برمی‌گرداند. برای هر مکانی که خلاصه به آن اشاره می‌کند، شناسه مکان، مختصات طول/عرض جغرافیایی، پیوندهای Google Maps، و ارجاع را نیز برمی‌گرداند.

می‌توانید search_places را ازطریق سرور MCP یا به‌عنوان روش REST searchText فراخوانی کنید. این صفحه گزینه‌های درخواست، ازجمله گزینه‌های Pro، محتوای پاسخ، و نحوه صدور صورت‌حساب برای درخواست‌ها را شرح می‌دهد. برای مشاهده طرح‌واره‌های کامل، به search_places مرجع MCP و searchText مرجع REST مراجعه کنید.

گزینه‌های درخواست

«مدل زبانی بزرگ» این گزینه‌ها را هنگام فراخوانی ابزار، براساس درخواست کاربر و شرح ابزار تنظیم می‌کند. می‌توانید با دستورالعمل‌های خودتان بر گزینه‌هایی که مدل استفاده می‌کند تأثیر بگذارید؛ کنترل استفاده از Pro را ببینید.

جدول زیر گزینه‌های درخواست برای search_places را شرح می‌دهد:

گزینه شرح
text_query الزامی. پرسمان جستجو—برای مثال، coffee shops near Golden Gate Park. پرسمان باید حاوی اطلاعات مکان کافی باشد تا ابهامی وجود نداشته باشد، یا درخواست باید شامل location_bias باشد.
location_bias دایره‌ای (center و radius_meters اختیاری، تا ۵۰٬۰۰۰ متر) برای سوگیری نتایج به‌سمت آن. اگر text_query نام مکان صریحی را ذکر کند، از آن مکان استفاده می‌شود.
language_code زبان خلاصه—برای مثال، en یا ja. به‌طور پیش‌فرض انگلیسی است.
region_code کد منطقه CLDR کاربر—برای مثال، US. بر نام‌های مکان مختص منطقه تأثیر می‌گذارد و می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.
page_size حداکثر تعداد مکان‌ها برای برگرداندن. پیش‌فرض ۵ است. مقادیر ۶ تا ۱۰ گزینه Pro هستند. مقادیر بالاتر از ۱۰ خطای INVALID_ARGUMENT را برمی‌گرداند. ممکن است سرویس مکان‌های کمتری نسبت‌به تعداد درخواست‌شده برگرداند.
include_extended_details وقتی true، خلاصه شامل جزئیات گسترده مکان است. این یک گزینه Pro است. پیش‌فرض‌ها به false.

گزینه‌های Pro

دو گزینه Maps Grounding Pro SKU را انتخاب می‌کنند. درخواستی که از یکی یا هر دو استفاده می‌کند تحت شناسه کالا Pro صورت‌حساب می‌شود:

گزینه Pro زمان استفاده از آن
include_extended_details روی true تنظیم شد درخواست کاربر به جزئیات گسترده مکان نیاز دارد، مثل اطلاعات آماری از مرورها، موارد برجسته منو، جو، یا نکته‌های بازدیدکنندگان.
page_size از ۶ تا ۱۰ کاربر می‌خواهد بیش‌از ۵ مکان را مقایسه کند.

درخواست‌هایی که از هیچ‌کدام از این گزینه‌ها استفاده نمی‌کنند، ازجمله درخواست‌هایی با page_size از ۱ تا ۵، تحت «واحد نگهداری موجودی» Essentials صورت‌حساب می‌شوند.

جزئیات گسترده مکان

وقتی درخواست کاربر به بینش‌های کیفی، شرایط هم‌زمان، یا مشخصه‌های تخصصی نیاز دارد، include_extended_details را روی true تنظیم کنید، مثلاً:

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

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

برای جستجوهای استاندارد، آن را روی false (پیش‌فرض) بگذارید: غذاها یا انواع فروشگاه، نشانی‌ها، اطلاعات تماس، ساعت کاری، و امکانات رفاهی استاندارد. تکمیل درخواست‌های دارای جزئیات بیشتر، طولانی‌تر است.

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

مثال

درخواست MCP زیر حداکثر ۸ مکان را با جزئیات گسترده درخواست می‌کند. تحت SKU نسخه Pro صورت‌حساب صادر می‌شود:

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

مثال زیر همان درخواست را به روش searchText REST ارسال می‌کند:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

API_KEY را با کلید میانای API خودتان جایگزین کنید.

بدون جزئیات گسترده، خلاصه هر مکان را در یک یا دو جمله توصیف می‌کند:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) A candlelit, intimate dining room that reviewers describe as romantic but loud on weekends. غذاهای برجسته شامل تالیاتله آل راگو، بوراتا، و تیرامیسو است. رزرو کردن توصیه می‌شود؛ مشتریان بدون رزرو می‌توانند انتظار ۳۰ تا ۴۵ دقیقه انتظار در عصر جمعه و شنبه را داشته باشند، و پارکینگ کنار خیابان محدود است.

پاسخ

پاسخ حاوی فیلدهای زیر است:

  • summary: خلاصه‌ای از نتایج جستجو به زبان طبیعی. ممکن است حاوی نقل‌قول‌های مبتنی بر صفر باشد، مانند [0]، که به ورودی‌های places نگاشت می‌شوند.
  • places[]: مکان‌های ذکرشده در خلاصه. هر مکان شامل موارد زیر است:
    • ‫place: نام منبع مکان، در قالب places/{id}.
    • ‫id: شناسه مکان. می‌توانید از آن با دیگر میاناهای برنامه‌سازی کاربردی Google Maps Platform استفاده کنید، مثلاً برای نشان دادن مکان روی نقشه.
    • ‫location: مختصات طول/ عرض جغرافیایی مکان.
    • googleMapsLinks: پیوندهای Google Maps برای مکان (placeUrl)، مسیرها (directionsUrl)، مرورها (reviewsUrl)، عکس‌ها (photosUrl)، و نوشتن مرور (writeAReviewUrl).
    • ‫attribution: ارجاعی که باید با مکان نشان دهید. الزامات ذکر منبع را ببینید.
  • contentToken: یک نشان تجسم داده عاملی (پیش‌نمایش) که به شما امکان می‌دهد مکان‌ها را در پاسخ با کیت میانای کاربر «جاها» بدون هزینه اضافی نمایش دهید. وقتی پاسخ شامل حداقل یک مکان باشد، برگردانده می‌شود.

پاسخ برای هر دو SKU و برای MCP و REST ساختار یکسانی دارد. برای جزئیات فیلد، به مرجع search_places مراجعه کنید.

صورت‌حساب و سهمیه‌ها

هر درخواست search_places یک رویداد قابل‌صورت‌حساب است:

اگر مکان‌های برگرفته از پاسخ search_places را با «کیت میانای کاربر جاها» نمایش می‌دهید، می‌توانید از نشان تجسم داده‌های عاملی (پیش‌نمایش) استفاده کنید تا آن درخواست‌های «کیت میانای کاربر جاها» صورت‌حساب نشوند.

سهمیه search_places برای هر پروژه ۳۰۰ پُرسمان در دقیقه است که بین هر دو SKU مشترک است. برای قیمت‌گذاری، جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند را ببینید.