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 (شیء - اختیاری): از این مورد برای اولویت‌بندی نتایج نزدیک به یک منطقه جغرافیایی خاص استفاده کنید.

    • قالب: {"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 برای فراخوانی ابزار MCP search_places را نشان می‌دهد.

درخواست Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

پیام درخواست برای SearchText.

SearchTextRequest

نمایش JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "includeExtendedDetails": boolean,

  // 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.
}
فیلدها
textQuery

string

الزامی. پُرسمان نوشتاری.
languageCode

string

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

برای مثال، «en» برای انگلیسی.

فهرست فعلی زبان‌های پشتیبانی‌شده: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

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

برای مثال، «US» برای ایالات متحده.

برای اطلاعات بیشتر، به https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html مراجعه کنید.

توجه داشته باشید که کدهای منطقه ۳ رقمی درحال‌حاضر پشتیبانی نمی‌شوند.
pageSize

integer

اختیاری. حداکثر تعداد مکان‌هایی که باید برگردانده شود، تا ۵ مکان. سرویس ممکن است کمتر از این مقدار را برگرداند. مقدار پیش‌فرض ۵ است.
includeExtendedDetails

boolean

اختیاری. شامل جزئیات گسترده مکان در پاسخ است.

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

false (پیش‌فرض) را برای جستجوهای استاندارد کاوش (مثلاً غذاها، انواع فروشگاه)، جستجوهای مکان/نشانی، اطلاعات تماس، ساعت کاری، و فراداده/امکانات رفاهی استاندارد بگذارید.

فعال کردن این فیلد باعث تأخیر بیشتر می‌شود.

فیلد اتحادیه _location_bias.

_location_bias فقط می‌تواند یکی از موارد زیر باشد:
locationBias

object (LocationBias)

منطقه‌ای اختیاری برای سوگیری نتایج جستجو به آن. اگر مکان صریحی در text_query وجود داشته باشد، به‌جای این فیلد برای سوگیری نتایج جستجو استفاده خواهد شد.

LocationBias

نمایش JSON 
{
  "circle": {
    object (Circle)
  }
}
فیلدها
circle

object (Circle)

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

دایره

نمایش JSON 
{
  "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.
}
فیلدها
center

object (LatLng)

الزامی. نقطه مرکزی دایره.

فیلد اتحادیه _radius_meters.

_radius_meters فقط می‌تواند یکی از موارد زیر باشد:
radiusMeters

number

شعاع دایره به متر. شعاع باید در محدوده ۵۰٬۰۰۰ متر باشد.

LatLng

نمایش JSON 
{
  "latitude": number,
  "longitude": number
}
فیلدها
latitude

number

عرض جغرافیایی به درجه. باید در محدوده [-90.0, +90.0] باشد.
longitude

number

طول جغرافیایی برحسب درجه. باید در محدوده [-180.0, +180.0] باشد.

طرح خروجی

پیام پاسخ برای SearchText.

SearchTextResponse

نمایش JSON 
{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "contentToken": string
}
فیلدها
places[]

object (PlaceView)

فقط خروجی. فهرست مکان‌هایی که در خلاصه ذکر شده‌اند.
summary

string

فقط خروجی. خلاصه‌ای به زبان طبیعی از نتایج جستجو. خلاصه ممکن است حاوی نقل‌قول‌های مبتنی بر صفر مانند «[0]»، «[1]»، «[2]» و غیره باشد. این نقل‌قول‌ها به مکان‌های مربوطه در فیلد places نگاشت می‌شوند.
contentToken

string

فقط خروجی. یک کد امنیتی رمزگذاری‌شده که بافت جستجو را دربرمی‌گیرد و می‌تواند به سرویس‌های پرداز تصویری Google Maps، کیت‌های توسعه نرم‌افزار، یا «ابزار کار میانای کاربر عامل‌گرای Maps»‏ (A2UI) ارسال شود تا مؤلفه‌های میانای کاربر تعاملی را برای نتایج جستجوی برگردانده‌شده نمایش دهد.

PlaceView

نمایش JSON 
{
  "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.
}
فیلدها
place

string

نام منبع مکان اصلی، در قالب «places/{id}».
id

string

شناسه مکانِ مکان اصلی.
googleMapsLinks

object (GoogleMapsLinks)

پیوندهایی برای راه‌اندازی کنش‌های مختلف Google Maps.
attribution

object (Attribution)

ذکر منبع الزامی برای نمایش با مکان.

فیلد اتحادیه _location.

_location فقط می‌تواند یکی از موارد زیر باشد:
location

object (LatLng)

موقعیت این مکان.

LatLng

نمایش JSON 
{
  "latitude": number,
  "longitude": number
}
فیلدها
latitude

number

عرض جغرافیایی به درجه. باید در محدوده [-90.0, +90.0] باشد.
longitude

number

طول جغرافیایی برحسب درجه. باید در محدوده [-180.0, +180.0] باشد.
نمایش JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
فیلدها
directionsUrl

string

پیوندی برای نشان دادن مسیرهای رسیدن به آن مکان. پیوند فقط مکان مقصد را پر می‌کند و از حالت سفر پیش‌فرض DRIVE استفاده می‌کند.
placeUrl

string

پیوندی برای نمایش این مکان.
writeAReviewUrl

string

پیوندی برای نوشتن مرور برای این مکان در Google Maps.
reviewsUrl

string

پیوندی برای نمایش مرورهای این مکان در Google Maps.
photosUrl

string

پیوندی برای نمایش عکس‌های این مکان در Google Maps.

اِسناد

نمایش JSON 
{
  "title": string,
  "url": string
}
فیلدها
title

string

عنوان نمایش داده‌شده برای ارجاع.
url

string

نشانی وب برای پیوند دادن به اِسناد.

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

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

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

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

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌