البحث على طول المسار

تتيح أداة search_along_route لنموذج لغوي كبير العثور على أماكن على طول مسار السفر من طلب بلغة طبيعية، مثل محطات شحن المركبات الكهربائية في الطريق إلى بحيرة تاهو أو المقاهي بين سان فرانسيسكو وسان خوسيه. تعرض الأداة ملخّصًا من إنشاء الذكاء الاصطناعي للأماكن المطابقة والمفاضلات بينها. بالنسبة إلى كل مكان مذكور في الملخّص، يتضمّن الردّ أيضًا رقم تعريف المكان وإحداثيات خطوط العرض/الطول وروابط إلى "خرائط Google" ومصادر المعلومات المطلوبة ومقاييس الانحراف عن المسار.

كل طلب search_along_route هو خيار Pro ويتم تحصيل رسومه ضمن رمز التخزين التعريفي لـ Maps Grounding Pro.

يمكنك استدعاء search_along_route من خلال خادم MCP أو كطريقة REST في searchAlongRoute. توضّح هذه الصفحة خيارات الطلب وكيفية تحديد مسار ومحتوى الردّ وكيفية فوترة الطلبات. للاطّلاع على المخططات الكاملة، يُرجى مراجعة مرجع MCP الخاص بـ search_along_route ومرجع REST الخاص بـ searchAlongRoute.

خيارات الطلب

يضبط النموذج اللغوي الكبير هذه الخيارات عند استدعاء الأداة، استنادًا إلى طلب المستخدم ووصف الأداة. يمكنك التأثير في الخيارات التي يستخدمها النموذج من خلال تعليماتك الخاصة، راجِع التحكّم في استخدام Pro.

يوضّح الجدول التالي خيارات الطلبات في search_along_route:

Option	الوصف
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 سابقة (صالحة لمدة 10 دقائق)	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. يكون هذا الرمز المميّز صالحًا لمدة 10 دقائق، ويُشفِّر المسار المحسوب، بما في ذلك أي محطات توقّف وسيطة. عندما يتابع المستخدم بطلب أماكن على طول هذا المسار، يمكن للنموذج اللغوي الكبير تمرير قيمة retrievalToken كـ retrieval_token في search_along_route.

تفاصيل المكان الموسّعة

اضبط include_extended_details على true عندما يتطلّب طلب المستخدم إحصاءات نوعية أو ظروف في الوقت الفعلي أو سمات متخصّصة على طول المسار، مثل:

• آراء المراجعين: إحصاءات مستندة إلى المراجعات، وآراء العملاء، وملاحظاتهم
• عروض محددة: أصناف قائمة الطعام أو الأطباق أو المأكولات المتخصّصة أو المشروبات أو أهم ميزات النشاط التجاري
• الأجواء: الديكور الداخلي أو المظهر الجمالي أو الأجواء أو الحالة المزاجية
• نصائح عملية للزوّار وبيانات في الوقت الفعلي: ما إذا كان يجب الحجز مسبقًا، وأوقات الانتظار، ومدى ازدحام المكان، ومدى توفّر شواحن المركبات الكهربائية، وأسعار الوقود، ومواقف السيارات، والمرافق

اترك include_extended_details مضبوطًا على false (الإعداد التلقائي) لعمليات البحث العادية على طول المسار، مثل العثور على محطات الوقود أو أماكن الاستراحة أو المقاهي حسب الموقع الجغرافي وساعات العمل ووقت الانعطاف. تستغرق الطلبات التي تتضمّن تفاصيل موسّعة وقتًا أطول لإكمالها، ولكنّها لا تضيف أي رسوم إضافية لأنّ كل طلب من search_along_route يتم تحصيل رسومه ضمن رمز التخزين التعريفي Pro.

ملاحظة: تخضع الملخّصات التي تتضمّن إحصاءات من المراجعات لمتطلبات تحديد المصدر لمصادر "خرائط Google". يتضمّن كل مكان في الردّ googleMapsLinks.reviewsUrl، وهو رابط يؤدي إلى مراجعات المكان على "خرائط Google".

أمثلة

يبحث طلب 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.

يرسل المثال التالي الطلب الأول إلى طريقة REST‏ searchAlongRoute:

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 بمفتاح واجهة برمجة التطبيقات.

الردّ

يحتوي الردّ على الحقول التالية:

• summary: ملخّص بلغة طبيعية لنتائج البحث والمفاضلات بين المسارات البديلة قد يحتوي على اقتباسات تستند إلى الصفر، مثل [0]، والتي يتم ربطها بإدخالات في results.
• ‫results[]: قائمة الأماكن المذكورة في الملخّص مرتبة حسب الأهمية يتضمّن كل إدخال ما يلي:
  • ‫place: تفاصيل حول المكان:
    • ‫place: اسم المورد الخاص بالمكان، بالتنسيق places/{id}.
    • ‫id: تمثّل هذه السمة رقم تعريف المكان. ويمكنك استخدامها مع واجهات برمجة التطبيقات الأخرى في "منصة خرائط Google"، مثل عرض المكان على خريطة.
    • ‫location: تشير إلى إحداثيات خط العرض/خط الطول للمكان.
    • ‫googleMapsLinks: روابط إلى "خرائط Google" للمكان (placeUrl) والاتجاهات (directionsUrl) والمراجعات (reviewsUrl) والصور (photosUrl) وكتابة مراجعة (writeAReviewUrl)
    • attribution: مصدر المعلومات الذي يجب عرضه مع المكان يُرجى الاطّلاع على متطلبات الإسناد.
  • ‫detourSummary: مدة الرحلة والمسافة الإضافيتان المطلوبتان للتوقف في هذا المكان على طول المسار:
    • ‫localizedDetourDistance: المسافة الإضافية منسَّقة بلغة الطلب، مثل "1.2 mi" أو "1.9 km"
    • ‫detourDuration: مدة الرحلة الإضافية كسلسلة مدة، مثل "180s". لا يتم ضبط هذا الحقل عند تحديد المسار باستخدام encoded_polyline.
• ‫contentToken: رمز مميّز لعرض البيانات بشكل مرئي باستخدام الذكاء الاصطناعي الوكيل (نسخة حصرية) يتيح لك عرض الأماكن في الردّ باستخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن بدون أي تكلفة إضافية يتم عرض هذه الحالة عندما يتضمّن الردّ مكانًا واحدًا على الأقل.

للاطّلاع على تفاصيل الحقول الكاملة، يُرجى مراجعة مرجع 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 باستخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن، يمكنك استخدام الرمز المميّز لعرض البيانات المستند إلى الوكيل (نسخة حصرية) لكي لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن هذه.

تبلغ حصة search_along_route ‏300 طلب بحث في الدقيقة لكل مشروع. للاطّلاع على الأسعار، يُرجى مراجعة جدول الأسعار الرئيسي وجدول الأسعار في الهند.