MCP Tools Reference: mapstools.googleapis.com

ابزار: search_places

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

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

  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 استفاده کنید که مختصات به صراحت ارائه شده باشند یا اگر استنباط یک مکان از زمینه شناخته شده کاربر برای نتایج بهتر مناسب و ضروری باشد.

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

درخواست کرل 
                  
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 tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

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

درخواست متن جستجو

نمایش JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "pageToken": 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.
}
فیلدها
textQuery

string

الزامی. عبارت متنی.

languageCode

string

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

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

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

regionCode

string

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

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

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

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

pageSize

integer

اختیاری. حداکثر تعداد مکان‌هایی که می‌توان برگرداند. سرویس ممکن است کمتر از این مقدار را برگرداند.

pageToken

string

اختیاری. یک توکن صفحه، که از فراخوانی قبلی SearchText دریافت شده است. این توکن را برای بازیابی صفحه بعدی ارائه دهید.

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

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

locationBias

object ( LocationBias )

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

موقعیت مکانی

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

object ( Circle )

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

دایره

نمایش JSON 
{
  "center": {
    object (google.type.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 ( google.type.LatLng )

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

_radius_meters میدان اتحادیه.

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

radiusMeters

number

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

لات‌لنگ

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

number

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

longitude

number

طول جغرافیایی بر حسب درجه. باید در محدوده [-۱۸۰.۰، +۱۸۰.۰] باشد.

طرحواره خروجی

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

متن جستجوپاسخ

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

object ( PlaceView )

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

summary

string

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

nextPageToken

string

اختیاری. توکنی که می‌تواند به عنوان page_token برای بازیابی صفحه بعدی ارسال شود.

نمای مکان

نمایش JSON 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (google.type.LatLng)
  }
  // End of list of possible types for union field _location.
}
فیلدها
place

string

نام منبع مکان اصلی، به فرمت "places/{id}".

id

string

شناسه مکان مربوط به مکان اصلی.

googleMapsLinks

object ( GoogleMapsLinks )

لینک‌هایی برای فعال کردن اقدامات مختلف نقشه‌های گوگل.

میدان اتحادیه _location .

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

location

object ( google.type.LatLng )

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

لات‌لنگ

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

number

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

longitude

number

طول جغرافیایی بر حسب درجه. باید در محدوده [-۱۸۰.۰، +۱۸۰.۰] باشد.

نمایش JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
فیلدها
directionsUrl

string

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

placeUrl

string

لینکی برای نمایش این مکان.

writeAReviewUrl

string

لینکی برای نوشتن نقد و بررسی این مکان در نقشه گوگل.

reviewsUrl

string

پیوندی برای نمایش نظرات مربوط به این مکان در نقشه‌های گوگل.

photosUrl

string

پیوندی برای نمایش نظرات مربوط به این مکان در نقشه‌های گوگل.

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

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