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 (مصفوفة من العناصر - اختياري): ما يصل إلى 10 محطات توقّف يجب المرور بها بالترتيب بين نقطة الانطلاق والوجهة. التنسيق نفسه المستخدَم في origin. هذه الميزة غير متاحة مع TRANSIT. يجب تضمين المحطات التي طلبها المستخدم فقط.

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

اختيارية: محطات التوقف الوسيطة بين نقطة الانطلاق والوجهة التي يجب المرور بها بالترتيب يمكن استخدام 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 
{
  "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، بما في ذلك طرفي النطاق.

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

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

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، ما يؤدي إلى زيادة التكلفة الواردة في الفاتورة وزمن الاستجابة. لا يتوفّر هذا الخيار إلا للعملاء المدرَجين في القائمة المسموح بها. وفي حال عدم إضافته إلى القائمة المسموح بها، سيتم ضبط الطلب على ROUTING_PREFERENCE_TRAFFIC_UNAWARE.

مخطط النتائج

‫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: ❌