MCP Tools Reference: mapstools.googleapis.com

ابزار: search_places

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

شرایط لازم ورودی (بحرانی):

1. text_query (رشته - الزامی): پُرسمان جستجوی اصلی. این باید به‌وضوح مشخص کند که کاربر به‌دنبال چه چیزی است.

   • نمونه‌ها: 'restaurants in New York'،‏ 'coffee shops near Golden Gate Park'،‏ 'SF MoMA'،‏ '1600 Amphitheatre Pkwy, Mountain View, CA, USA'،‏ 'pets friendly parks in Manhattan, New York'،‏ 'date night restaurants in Chicago'،‏ 'accessible public libraries in Los Angeles'.
   • برای جزئیات مکان خاص: مشخصه درخواستی (برای نمونه، 'Google Store Mountain View opening hours'، 'SF MoMa phone number'، 'Shoreline Park Mountain View address') را اضافه کنید.

2. location_bias (object - اختیاری): از این برای اولویت‌بندی نتایج نزدیک به یک منطقه جغرافیایی خاص استفاده کنید.

   • قالب: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • کاربرد:
     • برای گرایش به شعاع ۵ کیلومتری: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • برای گرایش شدید به نقطه مرکزی: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (حذف radius_meters).

3. language_code (رشته - اختیاری): زبانی که خلاصه نتایج جستجو به آن نمایش داده می‌شود.

   • قالب: کد زبان دوحرفی (ISO 639-1)، که به‌صورت اختیاری با یک خط زیر و کد کشور دوحرفی (ISO 3166-1 alpha-2) دنبال می‌شود، برای نمونه، en، ja، en_US، zh_CN، es_MX. اگر کد زبان ارائه نشود، نتایج به زبان انگلیسی خواهد بود.

4. region_code (رشته - اختیاری): کد منطقه CLDR یونی‌کد کاربر. این پارامتر برای نمایش جزئیات مکان، مانند نام مکان ویژه منطقه، درصورت وجود، استفاده می‌شود. این پارامتر می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.

   • قالب: کد کشور دوحرفی (ISO 3166-1 alpha-2)، برای نمونه، US، CA.

دستورالعمل‌های «فراخوانی ابزار»:

• اطلاعات مکان (حیاتی): جستجو باید حاوی اطلاعات مکان کافی باشد. اگر مکان مبهم است (برای نمونه، فقط «پیتزافروشی‌ها»)، باید آن را در text_query مشخص کنید (برای نمونه، «پیتزافروشی‌ها در تهران») یا از پارامتر location_bias استفاده کنید. درصورت نیاز برای رفع ابهام، نام شهر، ایالت/استان، و منطقه/کشور را اضافه کنید.

• همیشه تا حد امکان text_query خاص و غنی از بافتار ارائه دهید.

• فقط درصورتی از location_bias استفاده کنید که مختصات به‌طور صریح ارائه شده باشد یا استنباط مکان از بافتار شناخته‌شده کاربر مناسب و برای نتایج بهتر ضروری باشد.

• برونداد زمینه‌ای باید بااستفاده از اطلاعات فیلد attribution درصورت دردسترس بودن به منبع نسبت داده شود.

نمونه کد زیر نحوه استفاده از curl برای فراخوانی ابزار search_places MCP را نشان می‌دهد.

طرح‌واره ورودی

{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}

{
  "circle": {
    object (Circle)
  }
}

{
  "center": {
    object (LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}

{
  "latitude": number,
  "longitude": number
}

طرح‌واره برونداد

{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string
}

{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}

{
  "latitude": number,
  "longitude": number
}

{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}

{
  "title": string,
  "url": string
}

حاشیه‌نویسی ابزار

گزارمان‌های ابزار برای توصیف خطر اولیه یک ابزار معین به کارخواهان MCP ارسال می‌شود. اکثر کارخواه‌ها این نشانه‌ها را به‌عنوان نامطمئن درنظر می‌گیرند، اما می‌توان از آن‌ها برای تصمیم‌گیری درباره زمان ارسال پیام‌واره تأیید به کاربر استفاده کرد.

به‌همراه رشته عنوان، نشان‌های بولی زیر به این صورت تعریف می‌شوند:

• ‫readOnlyHint: اگر درست باشد، ابزار محیطش را تغییر نمی‌دهد. پیش‌فرض: نادرست.
• ‫destructiveHint: اگر درست باشد، ابزار می‌تواند کنش‌های مخرب انجام دهد. اگر نادرست باشد، ابزار فقط می‌تواند کنش‌های افزودنی انجام دهد. پیش‌فرض: درست.
• idempotentHint: اگر درست باشد، فراخوانی مکرر ابزار با همان آرگومان‌ها تأثیر اضافه‌ای بر محیط آن نخواهد داشت. پیش‌فرض: نادرست.
• ‫openWorldHint: اگر درست باشد، ابزار می‌تواند با «دنیای باز» نهادهای خارجی تعامل داشته باشد. اگر نادرست باشد، ابزار فقط می‌تواند با نهادهای داخلی تعامل داشته باشد. برای مثال، ابزار جستجوی وب دنیای باز است، اما ابزار حافظه دنیای باز نیست.

راهنمایی مخرب: ❌ | راهنمایی خودتوان: ❌ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌