MCP Tools Reference: mapstools.googleapis.com

ابزار: search_along_route

وقتی کاربر می‌خواهد مکان‌ها، کسب‌وکارها، یا نقاط جالب را درطول مسیر سفر پیدا کند (مثلاً «پمپ بنزین در مسیرم به تاهو»، «کافی‌شاپ‌های بین سان‌فرانسیسکو و سن خوزه»)، این ابزار را فراخوانی کنید. فراخوانی این ابزار هزینه بیشتری نسبت‌به search_places دارد، بنابراین هنگام جستجو در نزدیکی یک مکان به‌جای جستجو درطول مسیر، از search_places استفاده کنید.

الزامات ورودی (بسیار مهم):

  1. text_query (رشته - اجباری): شرحی به زبان طبیعی از آنچه باید درطول مسیر جستجو شود.

    • نمونه‌ها: 'ev chargers'، 'coffee'، 'vegetarian restaurants'، 'rest stops'.

  2. مشخصات مسیر (اجباری - دقیقاً یکی از موارد زیر را ارائه دهید):

    • retrieval_token (رشته): retrieval_token برگردانده‌شده توسط تماس compute_routes قبلی برای مسیر DRIVE. هرگاه مسیر قبلاً محاسبه شده باشد، این گزینه را ترجیح دهید. کد به‌مدت ۱۰ دقیقه معتبر است.
    • route_endpoints (شیء): origin و destination مسیر. هرکدام باید بااستفاده از یکی‌از address، lat_lng، یا place_id ارائه شود.
      • مثال: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline (رشته): چندخطی کدبندی‌شده‌ای که نشان‌دهنده مسیر DRIVE است.

  3. travel_mode (enum - اختیاری): DRIVE (پیش‌فرض)، WALK، یا BICYCLE. ‫WALK و BICYCLE فقط با route_endpoints پشتیبانی می‌شوند. ‫TRANSIT پشتیبانی نمی‌شود.

  4. routing_preference (enum - اختیاری):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (پیش‌فرض): مسیر و مسیرهای فرعی را بدون ترافیک زنده محاسبه می‌کند. کمترین تأخیر.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: درصورت دردسترس بودن، از شرایط ترافیک زنده استفاده می‌کند. برای WALK یا BICYCLE پشتیبانی نمی‌شود. این را «فقط» زمانی تنظیم کنید که کاربر درباره ترافیک، ازدحام، یا زمان‌های انحراف مسیر تنظیم‌شده براساس ترافیک سؤال می‌کند. تأخیر بیشتری ایجاد می‌کند.

  5. include_extended_details (مقدار منطقی - اختیاری): فقط زمانی روی true تنظیم کنید که درخواست به اطلاعات آماری بازبینی کیفی، گزینه‌ها یا پیشنهادهای منو خاص، اتمسفر، نکته‌های بازدیدکننده یا شلوغی، دردسترس بودن شارژر خودرو برقی، قیمت بنزین، یا دیگر جزئیات کیفی غنی نیاز داشته باشد. پیش‌فرض‌ها به false. فعال کردن آن ممکن است تأخیر را افزایش دهد.

  6. ‫language_code (رشته - اختیاری): زبان خلاصه نتایج و جزئیات مکان، برای مثال، en،‏ ja،‏ en-US. پیش‌فرض‌ها به en-US.

  7. ‫region_code (رشته - اختیاری): کد منطقه CLDR یونی‌کد کاربر، مثلاً US، CA.

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

  • هر نتیجه شامل یک detour_summary (درصورت دردسترس بودن) است که مسافت اضافی (localized_detour_distance) و زمان اضافی (detour_duration) ناشی از توقف در آن مکان را توصیف می‌کند، مگراینکه مسیر به‌عنوان encoded_polyline ارائه شده باشد. از آن برای مقایسه گزینه‌ها استفاده کنید.
  • پاسخ summary ممکن است حاوی ارجاع‌های صفرپایه (مثلاً «[0]») باشد که به ورودی‌های results ارجاع می‌دهند.
  • برونداد مستندشده باید بااستفاده از فیلد attribution هر results[].place (درصورت دردسترس بودن) به منبع نسبت داده شود.

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

درخواست 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_along_route",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

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

SearchAlongRouteRequest

نمایش JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "routingPreference": enum (RoutingPreference),
  "includeExtendedDetails": boolean,
  "travelMode": enum (RouteTravelMode),

  // Union field route_spec can be only one of the following:
  "encodedPolyline": string,
  "retrievalToken": string,
  "routeEndpoints": {
    object (RouteEndpoints)
  }
  // End of list of possible types for union field route_spec.
}
فیلدها
textQuery

string

الزامی. پُرسمان جستجوی زبان طبیعی (برای مثال، «شارژرهای خودرو برقی»، «قهوه»).
languageCode

string

اختیاری. زبان خلاصه و جزئیات مکان. به‌طور پیش‌فرض روی «en-US» تنظیم شده است.
regionCode

string

اختیاری. کد کشور/منطقه (CLDR) مکان (مثلاً «US»).
routingPreference

enum (RoutingPreference)

اختیاری. اولویت اختیاری مسیریابی که نحوه استفاده از داده‌های ترافیک را مشخص می‌کند. پیش‌فرض TRAFFIC_UNAWARE است.
includeExtendedDetails

boolean

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

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

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

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

enum (RouteTravelMode)

اختیاری. حالت سفر مورداستفاده برای محاسبه مسیر و مسیرهای انحرافی را مشخص می‌کند. پیش‌فرض‌ها به DRIVE. ‫WALK و BICYCLE فقط با route_endpoints پشتیبانی می‌شوند. ‫TRANSIT پشتیبانی نمی‌شود.
فیلد اتحادیه route_spec. مشخصات مسیر: یا مسیر موجود، یا توکن مسیر، یا نقاط پایانی مبدأ/مقصد. route_spec فقط می‌تواند یکی از موارد زیر باشد:
encodedPolyline

string

رشته چندخطی کدبندی‌شده‌ای که نشان‌دهنده مسیر است. https://developers.google.com/maps/documentation/utilities/polylinealgorithm را ببینید
retrievalToken

string

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

object (RouteEndpoints)

نقاط پایانی صریح مسیر (مبدأ و مقصد).

RouteEndpoints

نمایش JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
فیلدها
origin

object (Waypoint)

الزامی. نقطه شروع (نشانی، شناسه مکان، یا مختصات جغرافیایی).
destination

object (Waypoint)

الزامی. نقطه مقصد (نشانی، شناسه مکان، یا مختصات جغرافیایی).

نقطه مسیر

نمایش JSON 
{

  // Union field location_type can be only one of the following:
  "latLng": {
    object (LatLng)
  },
  "placeId": string,
  "address": string
  // End of list of possible types for union field location_type.
}
فیلدها
فیلد اتحادیه location_type. روش‌های مختلف برای نمایش مکان. location_type فقط می‌تواند یکی از موارد زیر باشد:
latLng

object (LatLng)

نقطه‌ای که بااستفاده از مختصات جغرافیایی مشخص شده است.
placeId

string

«شناسه مکان» مرتبط با نقطه‌مسیر.
address

string

نشانی قابل‌خواندن برای انسان یا کد پلاس. برای جزئیات، به https://plus.codes بروید.

LatLng

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

number

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

number

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

RoutingPreference

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

شمارشی‌ها
ROUTING_PREFERENCE_UNSPECIFIED هیچ اولویت مسیریابی‌ای مشخص نشده است. پیش‌فرض‌ها به ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE مسیرها را بدون درنظر گرفتن شرایط ترافیک زنده محاسبه می‌کند. زمانی مناسب است که شرایط ترافیک اهمیتی نداشته باشد یا قابل‌اعمال نباشد. استفاده از این مقدار کمترین تأخیر را ایجاد می‌کند.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

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

این مقدار باعث فعال شدن سطح Pro و افزایش هزینه صورت‌حساب و تأخیر می‌شود.

RouteTravelMode

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

شمارشی‌ها
ROUTE_TRAVEL_MODE_UNSPECIFIED حالت سفر مشخص نشده است. پیش‌فرض‌ها به DRIVE.
DRIVE سفر با خودرو سواری.
WALK پیاده سفر کنید. توجه: مسیرهای WALK در مرحله بتا هستند و ممکن است گاهی پیاده‌روهای تمیز یا مسیرهای عابر پیاده را نشان ندهند. باید این هشدار را برای همه پیاده‌روی‌هایی که در برنامه‌تان نمایش می‌دهید به کاربر نشان دهید.
BICYCLE سفر با دوچرخه.
TRANSIT با حمل‌ونقل عمومی سفر کنید.

طرح برونداد

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

SearchAlongRouteResponse

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

object (Result)

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

string

فقط خروجی. خلاصه نتایج جستجو و معاوضه‌های انحراف مسیر به زبان طبیعی. ممکن است حاوی نقل‌قول‌های صفرپایه (مثلاً «[0]»، «[1]») باشد که به ورودی‌های مربوطه در فهرست results ارجاع می‌دهند.
contentToken

string

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

نتیجه

نمایش JSON 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
فیلدها
place

object (PlaceView)

فقط خروجی. جزئیات مربوط به مکان پیدا‌شده درطول مسیر.
detourSummary

object (DetourSummary)

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

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

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

DetourSummary

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

string (Duration format)

مدت سفر اضافی لازم برای انحراف از مسیر اصلی به این مکان. اگر مسیر با encoded_polyline مشخص شده باشد، این مقدار تنظیم نمی‌شود.

مدت‌زمان به ثانیه با حداکثر نه رقم اعشار، که به «s» ختم می‌شود. مثال: "3.5s".
localizedDetourDistance

string

مسافت اضافی لازم برای انحراف به این مکان از مسیر اصلی، قالب‌بندی‌شده برای نمایش به زبان درخواست (مثلاً «۱٫۲ مایل» یا «۱٫۹ کیلومتر»).

مدت

نمایش JSON 
{
  "seconds": string,
  "nanos": integer
}
فیلدها
seconds

string (int64 format)

ثانیه‌های علامت‌دار بازه زمانی. باید از ‎-۳۱۵٬۵۷۶٬۰۰۰٬۰۰۰ تا ‎+۳۱۵٬۵۷۶٬۰۰۰٬۰۰۰ (شامل این دو عدد) باشد. توجه: این حدود از این فرمول محاسبه شده است: ۶۰ ثانیه/دقیقه * ۶۰ دقیقه/ساعت * ۲۴ ساعت/روز * ۳۶۵٫۲۵ روز/سال * ۱۰۰۰۰ سال
nanos

integer

کسرهای علامت‌دار ثانیه در وضوح نانوثانیه از بازه زمانی. مدت‌های کمتر از یک ثانیه با فیلد 0 seconds و فیلد مثبت یا منفی nanos نشان داده می‌شود. برای مدت‌های یک ثانیه یا بیشتر، مقدار غیرصفر برای فیلد nanos باید علامت یکسانی با فیلد seconds داشته باشد. باید از ‎-۹۹۹٬۹۹۹٬۹۹۹ تا ‎+۹۹۹٬۹۹۹٬۹۹۹ (شامل این دو عدد) باشد.

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

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

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

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

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