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. يُفضَّل استخدام هذا الخيار عندما يكون المسار قد تم احتسابه مسبقًا. ويكون الرمز المميّز صالحًا لمدة 10 دقائق.
    • ‫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 بتنسيق Unicode للمستخدم، مثل 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

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

النتيجة

تمثيل 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"
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"
reviewsUrl

string

رابط لعرض مراجعات هذا المكان على "خرائط Google"
photosUrl

string

رابط لعرض صور هذا المكان على "خرائط Google"

تحديد المصدر

تمثيل JSON 
{
  "title": string,
  "url": string
}
الحقول
title

string

العنوان الذي سيتم عرضه في المصدر
url

string

عنوان URL الذي سيتم ربطه بمصدر المحتوى

DetourSummary

تمثيل JSON 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
الحقول
detourDuration

string (Duration format)

مدة الرحلة الإضافية المطلوبة للانعطاف إلى هذا المكان من المسار الرئيسي لا يتم ضبط هذه القيمة إذا تم تحديد المسار من خلال encoded_polyline.

تمثّل هذه السمة مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s"، مثلاً: "3.5s".
localizedDetourDistance

string

المسافة الإضافية المطلوبة للانعطاف إلى هذا المكان من المسار الرئيسي، منسَّقة للعرض بلغة الطلب (مثلاً "1.2 ميل" أو "1.9 كم").

المدة

تمثيل JSON 
{
  "seconds": string,
  "nanos": integer
}
الحقول
seconds

string (int64 format)

الثواني الموقَّعة للفترة الزمنية يجب أن تتراوح القيمة بين ‎-315,576,000,000 و‎+315,576,000,000، بما في ذلك طرفي النطاق. ملاحظة: يتم احتساب هذه الحدود من: 60 ثانية/دقيقة * 60 دقيقة/ساعة * 24 ساعة/يوم * 365.25 يوم/سنة * 10000 سنة
nanos

integer

تشير هذه السمة إلى أجزاء الثانية الموقَّعة بدقة النانو ثانية للفترة الزمنية. يتم تمثيل المدد التي تقل عن ثانية واحدة بحقل seconds بقيمة 0 وحقل nanos موجب أو سالب. بالنسبة إلى المدد التي تبلغ ثانية واحدة أو أكثر، يجب أن تكون القيمة غير الصفرية لحقل nanos من العلامة نفسها لحقل seconds. يجب أن تتراوح القيمة بين ‎-999,999,999 و‎+999,999,999، بما في ذلك طرفي النطاق.

التعليقات التوضيحية للأدوات

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

إلى جانب سلسلة العنوان، يتم تحديد التلميحات المنطقية التالية على النحو التالي:

  • ‫readOnlyHint: إذا كانت القيمة "صحيح"، لا تعدّل الأداة بيئتها. القيمة التلقائية: false
  • ‫destructiveHint: إذا كانت القيمة "صحيح"، يمكن للأداة تنفيذ إجراءات مدمّرة. إذا كانت القيمة "خطأ"، يمكن للأداة تنفيذ إجراءات إضافية فقط. القيمة التلقائية: true
  • ‫idempotentHint: إذا كانت القيمة "صحيح"، لن يؤدي استدعاء الأداة بشكل متكرّر باستخدام الوسيطات نفسها إلى أي تأثير إضافي على بيئتها. القيمة التلقائية: false
  • ‫openWorldHint: إذا كانت القيمة "صحيح"، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة "خطأ"، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، أداة بحث الويب هي أداة عالم مفتوح، بينما أداة الذاكرة ليست كذلك.

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