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

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

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

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

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

گزینه شرح
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

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

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

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

جزئیات گسترده جا

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

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

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

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

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

مثال

درخواست زیر حداکثر ۸ مکان را با جزئیات گسترده درخواست می‌کند. این مورد تحت 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
}

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

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 · $$$) غذاخوری صمیمی با نور شمع که مرورکنندگان آن را رمانتیک اما در آخر هفته‌ها شلوغ توصیف می‌کنند. غذاهای برجسته شامل تالیاتله آل راگو، بوراتا، و تیرامیسو است. رزرو کردن توصیه می‌شود؛ مشتریان بدون رزرو می‌توانند انتظار ۳۰ تا ۴۵ دقیقه انتظار در عصر جمعه و شنبه را داشته باشند، و پارکینگ خیابانی محدود است.

پاسخ

پاسخ حاوی این موارد است:

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

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

گزینه‌های Pro درطول «دسترسی عمومی محدودشده»

درطول «دسترسی عمومی محدود»، گزینه‌های Pro فقط برای پروژه‌های موجود در فهرست مجاز Pro دردسترس است. اگر پروژه‌تان هنوز در فهرست مجاز نیست، گزینه‌های Pro به‌جای رد شدن، نادیده گرفته می‌شوند:

  • ‫include_extended_details به‌عنوان false درنظر گرفته می‌شود.
  • مقادیر page_size بالاتر از ۵، ازجمله مقادیر بالاتر از ۱۰، به ۵ کاهش می‌یابد.

درخواست تحت شناسه Essentials صورت‌حساب می‌شود. برای درخواست دسترسی، گزینه‌های Pro درطول «دسترسی عمومی محدودشده» را ببینید.

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

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

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