جستجو در طول مسیر

ابزار search_along_route به مدل زبانی بزرگ امکان می‌دهد مکان‌های موجود در مسیر سفر را ازطریق پُرسمان زبان طبیعی پیدا کند، مثلاً ایستگاه‌های شارژ خودرو برقی در مسیر دریاچه تاهو یا قهوه‌سراهای بین سان‌فرانسیسکو و سن خوزه. این ابزار خلاصه‌ای تولیدشده با هوش مصنوعی از مکان‌های منطبق و معاوضه‌های انحراف مسیر آن‌ها را برمی‌گرداند. برای هر جای ذکرشده در خلاصه، پاسخ همچنین شامل شناسه جا، مختصات طول/عرض جغرافیایی، پیوندهای Google Maps، ارجاع لازم، و سنجه‌های انحراف مسیر است.

هر درخواست search_along_route یک گزینه Pro است و تحت شناسه محصول Maps Grounding Pro صورت‌حساب می‌شود.

می‌توانید search_along_route را ازطریق سرور MCP یا به‌عنوان روش REST searchAlongRoute فراخوانی کنید. این صفحه گزینه‌های درخواست، نحوه مشخص کردن مسیر، محتوای پاسخ، و نحوه صدور صورت‌حساب برای درخواست‌ها را شرح می‌دهد. برای طرح‌واره‌های کامل، به مرجع MCP‏ search_along_route و مرجع REST‏ searchAlongRoute مراجعه کنید.

گزینه‌های درخواست

«مدل زبانی بزرگ» این گزینه‌ها را هنگام فراخوانی ابزار، براساس درخواست کاربر و شرح ابزار تنظیم می‌کند. می‌توانید با دستورالعمل‌های خودتان بر گزینه‌هایی که مدل استفاده می‌کند تأثیر بگذارید؛ کنترل استفاده از Pro را ببینید.

جدول زیر گزینه‌های درخواست برای search_along_route را شرح می‌دهد:

گزینه شرح
text_query الزامی. پرسمان جستجوی زبان طبیعی برای مکان‌های موجود در مسیر—برای مثال، ev chargers، coffee، یا vegetarian restaurants.
‫retrieval_token، route_endpoints، یا encoded_polyline الزامی. مسیری که باید درطول آن جستجو شود. یکی از این سه فیلد را در هر درخواست مشخص کنید. مشخص کردن مسیر را ببینید.
travel_mode اختیاری. حالت حمل‌ونقل استفاده‌شده برای محاسبه مسیر و مسیرهای انحرافی: DRIVE (پیش‌فرض)، WALK، یا BICYCLE. ‫WALK و BICYCLE فقط با route_endpoints پشتیبانی می‌شوند. ‫TRANSIT پشتیبانی نمی‌شود. مسیرهای WALK در مرحله بتا هستند و ممکن است گاهی پیاده‌روها یا مسیرهای عابر پیاده را به‌طور واضح نشان ندهند. باید این هشدار را برای همه مسیرهای پیاده‌روی که در برنامه‌تان نمایش می‌دهید به کاربر نشان دهید.
routing_preference اختیاری. نحوه استفاده از داده‌های ترافیک برای محاسبه زمان مسیر و مسیر انحرافی: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (پیش‌فرض) یا ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL از شرایط ترافیک زنده (درصورت دردسترس بودن) استفاده می‌کند و برای WALK یا BICYCLE پشتیبانی نمی‌شود.
include_extended_details اختیاری. وقتی true، خلاصه شامل جزئیات گسترده مکان می‌شود، مثل اطلاعات آماری از مرورها، گزینه‌های منو، جو، نکته‌های بازدیدکنندگان، دردسترس بودن شارژر خودرو برقی، یا قیمت بنزین. پیش‌فرض‌ها به false.
language_code اختیاری. کد زبان BCP-47 برای خلاصه و فاصله انحراف بومی‌سازی‌شده—برای مثال، en-US یا ja. پیش‌فرض‌ها به en-US.
region_code اختیاری. کد منطقه CLDR دوحرفی کاربر—برای مثال، US یا CA. بر نام‌های مکان مختص منطقه تأثیر می‌گذارد و می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.

مشخص کردن مسیر

هر درخواست search_along_route باید مسیر را بااستفاده از یکی از سه فیلد ناسازگار با یکدیگر مشخص کند. تنظیم بیش‌از یک فیلد مسیر، یا حذف هر سه فیلد، خطای INVALID_ARGUMENT را برمی‌گرداند.

جدول زیر سه روش مشخص کردن مسیر را مقایسه می‌کند:

گزینه مسیر قالب ورودی حالت‌های سفر پشتیبانی‌شده برگرداندن با هزینه detourDuration زمان استفاده از آن
retrieval_token رشته retrievalToken از پاسخ compute_routes قبلی (به‌مدت ۱۰ دقیقه معتبر است) DRIVE بله نماینده قبلاً compute_routes را برای مسیر رانندگی، ازجمله مسیرهای دارای توقف‌های میانی، فراخوانی کرده است و کاربر مکان‌های موجود در آن مسیر را درخواست می‌کند.
route_endpoints شیء با نقطه‌مسیرهای origin و destination (address، place_id، یا lat_lng) DRIVE، WALK، BICYCLE بله کاربر درخواست می‌کند مکان‌های بین دو موقعیت مکانی را در یک مرحله بدون تماس با compute_routes پیدا کند، یا مسیر از پیاده‌روی یا دوچرخه‌سواری استفاده می‌کند.
encoded_polyline رشته چندخطی کدبندی‌شده که نشان‌دهنده مسیر رانندگی است DRIVE نه (فقط localizedDetourDistance برمی‌گرداند) برنامه شما ازقبل چندخطی مسیر از منبع دیگری، مثل Routes API، دارد.

زنجیره compute_routes و search_along_route

وقتی درخواست compute_routes از حالت سفر DRIVE استفاده می‌کند، هر مسیر در پاسخ شامل فیلد retrievalToken است. این کد به‌مدت ۱۰ دقیقه معتبر است و مسیر محاسبه‌شده را، ازجمله هرگونه توقف میانی، کدبندی می‌کند. وقتی کاربر با درخواست مکان‌های موجود در آن مسیر پیگیری می‌کند، مدل زبانی بزرگ می‌تواند مقدار retrievalToken را به‌عنوان retrieval_token در search_along_route ارسال کند.

جزئیات گسترده مکان

وقتی درخواست کاربر به اطلاعات آماری کیفی، شرایط هم‌زمان، یا مشخصه‌های تخصصی درطول مسیر نیاز دارد، include_extended_details را روی true تنظیم کنید، مانند:

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

برای جستجوهای استاندارد درطول مسیر، مثل پیدا کردن جایگاه سوخت، استراحتگاه، یا قهوه‌سرا براساس مکان، ساعت کاری، و زمان انحراف از مسیر، include_extended_details را روی false (پیش‌فرض) تنظیم کنید. تکمیل درخواست‌های دارای جزئیات گسترده بیشتر طول می‌کشد، اما هزینه اضافی ندارند زیرا هر درخواست search_along_route قبلاً تحت شناسه Pro صورت‌حساب شده است.

مثال‌ها

درخواست MCP زیر ایستگاه‌های شارژ خودرو برقی را بین سان‌فرانسیسکو و دریاچه تاهو بااستفاده از route_endpoints و مسیریابی با آگاهی از ترافیک جستجو می‌کند:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "fast EV chargers with a coffee shop nearby",
      "route_endpoints": {
        "origin": {"address": "San Francisco, CA"},
        "destination": {"address": "Lake Tahoe, CA"}
      },
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

مثال زیر از retrieval_token از پاسخ قبلی compute_routes استفاده می‌کند:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "coffee shops",
      "retrieval_token": "RETRIEVAL_TOKEN"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
}

RETRIEVAL_TOKEN را با رشته retrievalToken که توسط compute_routes برگردانده شده است جایگزین کنید.

نمونه زیر اولین درخواست را به روش searchAlongRoute REST ارسال می‌کند:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "fast EV chargers with a coffee shop nearby",
  "routeEndpoints": {
    "origin": {"address": "San Francisco, CA"},
    "destination": {"address": "Lake Tahoe, CA"}
  },
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchAlongRoute"

API_KEY را با کلید میانای API خودتان جایگزین کنید.

پاسخ

پاسخ حاوی فیلدهای زیر است:

  • summary: خلاصه زبان طبیعی از نتایج جستجو و معاوضه‌های انحراف مسیر. ممکن است حاوی نقل‌قول‌های مبتنی بر صفر باشد، مثل [0]، که به ورودی‌های results نگاشت می‌شود.
  • ‫results[]: فهرست رتبه‌بندی‌شده مکان‌های ذکرشده در خلاصه. هر ورودی شامل موارد زیر است:
    • place: جزئیات مربوط به مکان:
      • ‫place: نام منبع مکان، در قالب places/{id}.
      • ‫id: شناسه مکان. می‌توانید از آن با دیگر میاناهای برنامه‌سازی کاربردی Google Maps Platform استفاده کنید، مثلاً برای نشان دادن مکان روی نقشه.
      • ‫location: مختصات طول/ عرض جغرافیایی مکان.
      • googleMapsLinks: پیوندهای Google Maps برای مکان (placeUrl)، مسیرها (directionsUrl)، مرورها (reviewsUrl)، عکس‌ها (photosUrl)، و نوشتن مرور (writeAReviewUrl).
      • ‫attribution: ارجاعی که باید با مکان نشان دهید. الزامات ذکر منبع را ببینید.
    • detourSummary: مدت سفر و مسافت اضافی لازم برای توقف در این مکان درطول مسیر:
      • localizedDetourDistance: فاصله اضافی قالب‌بندی‌شده به زبان درخواست، مثلاً "1.2 mi" یا "1.9 km".
      • ‫detourDuration: مدت سفر اضافی به‌صورت رشته مدت، مثل "180s". وقتی مسیر با encoded_polyline مشخص شده باشد، این فیلد تنظیم نمی‌شود.
  • contentToken: یک نشان تجسم داده عاملی (پیش‌نمایش) که به شما امکان می‌دهد مکان‌ها را در پاسخ با کیت میانای کاربر «جاها» بدون هزینه اضافی نمایش دهید. وقتی پاسخ شامل حداقل یک مکان باشد، برگردانده می‌شود.

برای جزئیات کامل فیلد، به مرجع search_along_route مراجعه کنید.

صورت‌حساب و سهمیه‌ها

هر درخواست search_along_route یک رویداد قابل‌صورت‌حساب تحت واحد نگهداری موجودی Maps Grounding Pro است. تنظیم include_extended_details روی true یا routing_preference روی ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL هزینه اضافی ندارد. اگر نماینده شما ابتدا compute_routes را فراخوانی کند و سپس retrieval_token را به search_along_route ارسال کند، هر فراخوانی ابزار به‌عنوان یک درخواست جداگانه صورت‌حساب می‌شود.

اگر مکان‌های پاسخ search_along_route را با «کیت میانای کاربر جاها» نمایش می‌دهید، می‌توانید از نشان تجسم داده‌های عامل‌گرا (پیش‌نمایش) استفاده کنید تا آن درخواست‌های «کیت میانای کاربر جاها» صورت‌حساب نشوند.

سهمیه search_along_route برای هر پروژه ۳۰۰ پُرسمان در دقیقه است. برای قیمت‌گذاری، جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند را ببینید.