MCP Tools Reference: mapstools.googleapis.com

الأداة: compute_routes

تحسب هذه الخدمة مسارات السفر بين نقطة انطلاق ووجهة، ويمكن أن تتضمّن محطات توقّف وسيطة. تعرض المسافة والمدة لكل مسار.

متطلبات الإدخال (مهمة):

  1. ‫origin وdestination (عنصران - إلزاميان): يجب تقديم كل منهما باستخدام أحد الخيارات التالية فقط:

    • ‫address (سلسلة، مثل 'Eiffel Tower, Paris'): يتم حلّ الأماكن المسمّاة والمعالم والأنشطة التجارية مباشرةً، لذا لا تستدعِ search_places أولاً لمجرد الترميز الجغرافي لنقطة على المسار. يجب تضمين أي مدينة أو منطقة أو بلد ذكره المستخدم.
    • lat_lng (عنصر، {"latitude": number, "longitude": number}).
    • ‫place_id (سلسلة، مثل 'ChIJOwE_Id1w5EAR4Q27FkL6T_0')، على سبيل المثال من search_places.

  2. intermediate_waypoints (مصفوفة من العناصر - اختياري): ما يصل إلى 25 محطة توقّف للمرور بها، بالترتيب، بين نقطة الانطلاق والوجهة. التنسيق نفسه المستخدَم في origin. هذه الميزة غير متاحة مع TRANSIT. يجب تضمين المحطات التي طلبها المستخدم فقط، لأنّ تحديد أكثر من 10 نقاط على المسار سيؤدي إلى زيادة التكلفة وزمن الاستجابة.

  3. ‫travel_mode (تعداد - اختياري): DRIVE (تلقائي) أو WALK أو BICYCLE أو TRANSIT

  4. التوقيت (اختياري - اضبط قيمة واحدة على الأكثر): طوابع زمنية بتنسيق RFC 3339 مع فارق عن التوقيت العالمي المنسَّق، مثل '2026-09-19T08:00:00-07:00'. يتم ضبط الإعدادات التلقائية على المغادرة الآن. بالنسبة إلى TRANSIT، يمكن أن يصل الوقت إلى 7 أيام في الماضي أو إلى 100 يوم في المستقبل. بالنسبة إلى الأوضاع الأخرى، يمكن أن يصل الوقت إلى 365 يومًا في المستقبل ويجب ألا يكون في الماضي.

    • departure_time: يُستخدَم عندما يذكر المستخدم وقت مغادرته (مثلاً، "غدًا في الساعة 8 صباحًا").
    • arrival_time: يُستخدَم هذا المعامل عندما يحدّد المستخدم وقت الوصول (مثلاً، "أريد الوصول بحلول الساعة 9 صباحًا").

  5. ‫routing_preference (enum - اختياري):

    • ‫ROUTING_PREFERENCE_TRAFFIC_UNAWARE (تلقائي): يتجاهل حركة المرور المباشرة والحوادث وحالات الإغلاق. أقل وقت استجابة
    • ‫ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: يستخدم أحوال حركة المرور المباشرة عندما تكون متاحة. لا يتوفّر هذا الخيار لـ WALK أو BICYCLE. يجب ضبط هذه القيمة فقط عندما يسأل المستخدم عن حركة المرور أو الازدحام أو الوقت المقدّر للوصول المعدّل حسب حركة المرور. ويؤدي ذلك إلى زيادة التكلفة ووقت الاستجابة.

  6. location_bias (عنصر - اختياري): {"latitude": number, "longitude": number} يُستخدَم لإزالة الغموض عن أسماء الأماكن في عناوين النقاط على المسار. إذا كان الاسم غامضًا (مثل "الربيع") ولم يحدّد المستخدم منطقة، يجب الاحتفاظ بالاسم كما هو في address وضبط location_bias على المنطقة المقصودة بدلاً من تخمين منطقة.

  7. compute_alternative_routes (قيمة منطقية - اختيارية): يتم ضبطها على true فقط عندما يطلب المستخدم خيارات أو بدائل للمسار. الإعداد التلقائي هو false، والذي يعرض المسار المقترَح فقط.

  8. include_polyline (قيمة منطقية - اختياري): يتم ضبطه على true فقط عندما تكون هندسة المسار (encoded_polyline) مطلوبة. القيمة التلقائية هي false.

تعليمات طلب استخدام الأداة:

  • إذا لم يتم تحديد نقطة الانطلاق أو الوجهة، يجب أن تطلب من المستخدم توضيح ذلك قبل استدعاء الأداة.
  • بالنسبة إلى الأسئلة من نوع "ما المسافة بين "أ" و"ب"؟"، استخدِم "ب" كـ origin و"أ" كـ destination.

مثال على استدعاء الأداة: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

تعليمات الردّ:

  • عند طلب مسارات بديلة، يتم ترتيب المسارات من الأكثر إلى الأقل اقتراحًا.
  • إذا كانت السمة routes فارغة، أخبِر المستخدم بأنّه لم يتم العثور على أي مسار. لا تخمِّن المسار.
  • للعثور على أماكن على طول مسار DRIVE، مرِّر retrieval_token الخاص بالمسار إلى search_along_route. ويكون الرمز المميّز صالحًا لمدة 10 دقائق.
  • اذكر فقط الحقائق التي تعرضها الأداة. لا تخترع اتجاهات مفصّلة أو خطوط نقل عام أو محطات أو أرصفة أو عمليات نقل.
  • يجب أن تتم نسبة الناتج المستند إلى المصدر إلى المصدر باستخدام حقل attribution لكل مسار عندما يكون متاحًا.

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام curl لاستدعاء أداة MCP‏ compute_routes.

طلب 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": "compute_routes",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

ComputeRoutesRequest.

ComputeRoutesRequest

تمثيل JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  },
  "travelMode": enum (RouteTravelMode),
  "intermediateWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "routingPreference": enum (RoutingPreference),
  "locationBias": {
    object (LatLng)
  },
  "includePolyline": boolean,
  "computeAlternativeRoutes": boolean,

  // Union field timing can be only one of the following:
  "departureTime": string,
  "arrivalTime": string
  // End of list of possible types for union field timing.
}
الحقول
origin

object (Waypoint)

الحقل مطلوب. نقطة الانطلاق على المسار
destination

object (Waypoint)

الحقل مطلوب. نقطة على المسار للوجهة
travelMode

enum (RouteTravelMode)

اختياريّ. تحدّد هذه السمة وسيلة النقل.
intermediateWaypoints[]

object (Waypoint)

اختياريّ. محطات التوقف الوسيطة بين نقطة الانطلاق والوجهة التي يجب المرور بها بالترتيب يمكن استخدام ما يصل إلى 25 نقطة على المسار.

سيؤدي تحديد أكثر من 10 نقاط وسيطة على المسار إلى زيادة التكلفة وزيادة وقت الاستجابة. لا يمكن استخدام النقاط على المسار المتوسطة عندما تكون قيمة travel_mode هي TRANSIT.
routingPreference

enum (RoutingPreference)

اختياريّ. تحدّد هذه المَعلمة كيفية استخدام بيانات حركة المرور لحساب المسار. لا يمكن استخدام ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL عندما تكون قيمة travel_mode هي WALK أو BICYCLE. بالنسبة إلى "TRANSIT"، يتيح هذا الإعداد بيانات النقل العام في الوقت الفعلي، مثل التأخيرات والإلغاءات.
locationBias

object (LatLng)

اختياريّ. موقع جغرافي لتوجيه نتائج البحث نحوه، على سبيل المثال لإزالة الغموض عن طلبات البحث النصية عن النقاط على المسار
includePolyline

boolean

اختياريّ. ما إذا كان سيتم تضمين الخطوط المتعدّدة المرمّزة في مسارات الاستجابة القيمة التلقائية هي false. عند ضبط السمة على true، يتم عرض Route.encoded_polyline.
computeAlternativeRoutes

boolean

اختياريّ. ما إذا كان سيتم احتساب مسارات بديلة بالإضافة إلى المسار المقترَح تكون القيمة التلقائية false، وفي هذه الحالة يتم عرض المسار المقترَح فقط. عند ضبطها على "صحيح"، يتم عرض جميع المسارات المتاحة، مع العلم أنّ البدائل قد لا تكون متاحة لكل طلب.
حقل الربط timing تحدّد وقت المغادرة من نقطة الانطلاق أو الوصول إلى النقطة النهائية على المسار. يتم ضبط القيمة تلقائيًا على وقت المغادرة الحالي في حال عدم تحديد أي قيمة. بالنسبة إلى "TRANSIT"، يجب أن يكون الوقت قبل 7 أيام على الأكثر في الماضي وبعد 100 يوم على الأكثر في المستقبل. بالنسبة إلى وسائل النقل الأخرى، يجب ألا يكون الوقت في الماضي ويجب ألا يتجاوز 365 يومًا في المستقبل. يمكن أن يكون التعليق timing إحدى القيم التالية فقط:
departureTime

string (Timestamp format)

اختياريّ. تشير إلى أنّه يجب احتساب المسار استنادًا إلى وقت المغادرة.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
arrivalTime

string (Timestamp format)

اختياريّ. تشير إلى أنّه يجب احتساب المسار استنادًا إلى وقت الوصول.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"

النقطة الوسيطة

تمثيل 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].

الطابع الزمني

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

string (int64 format)

تشير هذه السمة إلى عدد ثواني التوقيت العالمي المنسق (UTC) المنقضية منذ بداية حقبة يونكس 1970-01-01T00:00:00Z. يجب أن تتراوح القيمة بين ‎-62135596800 و253402300799، بما في ذلك طرفي النطاق (ما يعادل ‎0001-01-01T00:00:00Z إلى ‎9999-12-31T23:59:59Z).
nanos

integer

تشير هذه السمة إلى أجزاء الثانية غير السالبة بدقة النانو ثانية هذا الحقل هو جزء النانو ثانية من المدة، وليس بديلاً للثواني. يجب أن تظل قيم الثواني السالبة التي تحتوي على كسور تحتوي على قيم نانو ثانية غير سالبة يتم احتسابها للأمام في الوقت المناسب. يجب أن تتراوح القيمة بين 0 و999,999,999، بما في ذلك طرفي النطاق.

RouteTravelMode

مجموعة من القيم المستخدَمة لتحديد وسيلة السفر

عمليات التعداد
ROUTE_TRAVEL_MODE_UNSPECIFIED لم يتم تحديد أي وضع سفر. القيمة التلقائية هي DRIVE.
DRIVE التنقّل باستخدام سيارة ركاب
WALK التنقّل سيرًا على الأقدام ملاحظة: مسارات WALK في مرحلة تجريبية، وقد لا تتوفّر أحيانًا أرصفة أو مسارات واضحة للمشاة. يجب عرض هذا التحذير للمستخدم في جميع مسارات المشي التي تعرضها في تطبيقك.
BICYCLE التنقّل بالدراجة
TRANSIT التنقّل باستخدام وسائل النقل العام

RoutingPreference

مجموعة من القيم التي تحدّد العوامل التي يجب أخذها في الاعتبار عند احتساب المسار

عمليات التعداد
ROUTING_PREFERENCE_UNSPECIFIED لم يتم تحديد أي إعدادات مفضّلة للتوجيه. القيمة التلقائية هي ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE تحسب المسارات بدون أخذ أحوال حركة المرور في الوقت الفعلي في الاعتبار. هذا الخيار مناسب عندما لا تكون أحوال حركة المرور مهمة أو لا تنطبق. يؤدي استخدام هذه القيمة إلى تقليل وقت الاستجابة إلى أدنى حد.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

تحسب المسارات مع مراعاة أحوال حركة المرور في الوقت الفعلي، عندما تكون بيانات حركة المرور متاحة. بالنسبة إلى TRANSIT، يتم استخدام بيانات النقل العام في الوقت الفعلي، مثل التأخيرات والإلغاءات، عندما تكون متاحة.

ستؤدي هذه القيمة إلى تفعيل فئة Pro، ما يؤدي إلى زيادة التكلفة الواردة في الفاتورة وزمن الاستجابة.

مخطط النتائج

‫ComputeRoutesResponse:

ComputeRoutesResponse

تمثيل JSON 
{
  "routes": [
    {
      object (Route)
    }
  ]
}
الحقول
routes[]

object (Route)

يحتوي على المسارات بين نقطة الانطلاق والوجهة المطلوبة، مرتّبة من الأكثر اقتراحًا إلى الأقل اقتراحًا. يتم عرض مسار واحد فقط ما لم يتم ضبط ComputeRoutesRequest.compute_alternative_routes على "صحيح".

مسار

تمثيل JSON 
{
  "distanceMeters": integer,
  "duration": string,
  "attribution": {
    object (Attribution)
  },
  "encodedPolyline": string,
  "retrievalToken": string
}
الحقول
distanceMeters

integer

مسافة السفر للمسار، بالمتر
duration

string (Duration format)

المدة الزمنية اللازمة للتنقّل في المسار

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

object (Attribution)

يجب عرض مصدر البيانات مع المسار.
encodedPolyline

string

خطوط متعدّدة مشفّرة للمسار يُرجى الاطّلاع على https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

رمز مميّز يمكن استخدامه لاسترداد هذا المسار المحدّد في الأدوات اللاحقة، مثل SearchAlongRoute. الرمز صالح لمدة 10 دقائق.

المدة

تمثيل 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، بما في ذلك طرفي النطاق.

تحديد المصدر

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

string

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

string

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

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

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

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

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

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