ابزار 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 یک رویداد قابلصورتحساب است:
- درخواستی که از هیچ گزینه Pro استفاده نمیکند تحت واحد نگهداری موجودی Maps Grounding Essentials صورتحساب میشود.
- درخواستی که از گزینه Pro استفاده میکند تحت واحد نگهداری موجودی Maps Grounding Pro صورتحساب میشود. استفاده از هر دو گزینه در یک درخواست، هزینه را تغییر نمیدهد. برای قیمتگذاری Pro، مقایسه Essentials، Pro، و «پایهمندسازی با Google Maps» را ببینید.
اگر مکانهای برگرفته از پاسخ search_places را با «کیت میانای کاربر جاها» نمایش میدهید،
میتوانید از
نشان تجسم دادههای عاملی
(پیشنمایش) استفاده کنید تا آن درخواستهای «کیت میانای کاربر جاها» صورتحساب نشوند.
سهمیه search_places برای هر پروژه ۳۰۰ پُرسمان در دقیقه است که بین هر دو SKU مشترک است. برای قیمتگذاری،
جدول قیمتگذاری اصلی و
جدول قیمتگذاری هند را ببینید.