حساب المسارات

تعرض أداة compute_routes مسارًا بين نقطة انطلاق ووجهة لوسيلة نقل معيّنة. يتضمّن الردّ مسافة المسار ومدته. يتم احتساب المسارات تلقائيًا بدون معلومات حركة المرور في الوقت الفعلي. يضيف الإصدار Pro ميزة تحديد المسارات التي تأخذ في الاعتبار حركة المرور المباشرة والمسارات التي تتضمّن المزيد من المحطات الوسيطة.

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

خيارات الطلب

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

خيارات Pro

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

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

تحديد المسارات استنادًا إلى حركة المرور

يتم احتساب المسارات تلقائيًا بدون أحوال حركة المرور المباشرة (ROUTING_PREFERENCE_TRAFFIC_UNAWARE). ويوفّر هذا الإعداد أقل وقت استجابة. وهي مناسبة للطلبات التي لا تهمّ فيها حركة المرور أو لا تنطبق عليها، مثل مسارات المشي أو التخطيط التقريبي.

اضبط routing_preference على ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL لاحتساب المسار ومدته مع أحوال حركة المرور الحالية، عندما تكون بيانات حركة المرور متاحة. يمكنك استخدامها عندما يسأل المستخدم عن المدة التي تستغرقها الرحلة بالسيارة في الوقت الحالي. بالنسبة إلى مسارات TRANSIT، يستخدم هذا الإعداد بيانات النقل العام في الوقت الفعلي، مثل التأخيرات والإلغاءات، عندما تكون متاحة. ولا يتوفّر للمسارات WALK أو BICYCLE، وتعرِض هذه الطلبات الخطأ INVALID_ARGUMENT. هذا خيار Pro، لذا تتم فوترة الطلب ضمن رمز التخزين التعريفي لـ Pro. يضيف هذا الخيار أيضًا وقت استجابة.

مثال

يطلب طلب MCP التالي مسار قيادة يراعي حركة المرور مع محطة توقف وسيطة واحدة وخط متعدّد الخطوط مُشفَّر. ويتم تحصيل رسومها ضمن رمز التخزين التعريفي لـ Pro:

{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      "origin": {"address": "Ferry Building, San Francisco, CA"},
      "destination": {"address": "Golden Gate Park, San Francisco, CA"},
      "intermediate_waypoints": [
        {"address": "Palace of Fine Arts, San Francisco, CA"}
      ],
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_polyline": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

يرسل المثال التالي الطلب نفسه إلى طريقة REST‏ computeRoutes:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "origin": {"address": "Ferry Building, San Francisco, CA"},
  "destination": {"address": "Golden Gate Park, San Francisco, CA"},
  "intermediateWaypoints": [
    {"address": "Palace of Fine Arts, San Francisco, CA"}
  ],
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includePolyline": true
}' \
"https://mapstools.googleapis.com/v1:computeRoutes"

استبدِل API_KEY بمفتاح واجهة برمجة التطبيقات.

الردّ

يتضمّن الردّ routes[]، مرتّبة من الأكثر إلى الأقل اقتراحًا. يتم عرض مسار واحد فقط ما لم يتم ضبط compute_alternative_routes على true. يتضمّن كل مسار ما يلي:

• ‫distanceMeters: مسافة المسار بالأمتار
• ‫duration: الوقت اللازم لسلك المسار باستخدام ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، يتم احتساب المدة وفقًا لأحوال حركة المرور.
• ‫encodedPolyline: مسار الرحلة على شكل خطوط متعدّدة مرمّزة، عندما تكون قيمة include_polyline هي true. ويمكنك استخدامها لرسم المسار على خريطة باستخدام واجهات برمجة تطبيقات أخرى في "منصة خرائط Google".
• ‫retrievalToken: رمز مميّز مبهم يتم عرضه لمسارات DRIVE (صالح لمدة 10 دقائق) ويمكنك تمريره إلى search_along_route للعثور على أماكن على طول هذا المسار بدون إعادة إرسال النقاط على المسار.
• ‫attribution: مصدر المعلومات الذي يجب عرضه مع المسار. يُرجى الاطّلاع على متطلبات الإسناد.

الفوترة والحصص

كل طلب من compute_routes هو حدث واحد قابل للفوترة:

• يتم إصدار فاتورة بالطلبات التي لا تستخدم أيّ خيارات Pro ضمن رمز التخزين التعريفي لـ Maps Grounding Essentials.
• يتم تحرير فاتورة للطلب الذي يستخدم خيار Pro ضمن رمز التخزين التعريفي لـ Maps Grounding Pro. لا يؤدي استخدام كلا خيارَي Pro في طلب واحد إلى تغيير الرسوم. للاطّلاع على أسعار Pro، يُرجى مراجعة مقارنة بين Essentials وPro و"استخدام خرائط Google كمصدر".

لا يؤدي طلب مسارات بديلة أو شكل متعدّد الخطوط أو وقت مغادرة أو وقت وصول أو وسيلة نقل مختلفة إلى تغيير رمز التخزين التعريفي.

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

الحدود

• يمكن أن يتضمّن الطلب 25 نقطة على المسار كحدّ أقصى، وتُعدّ النقاط من 11 إلى 25 خيارًا احترافيًا. ويؤدي الطلب الذي يتضمّن عددًا أكبر من ذلك إلى ظهور الخطأ INVALID_ARGUMENT.
• لا تتيح مسارات النقل العام استخدام نقاط على المسار وسيطة. يؤدي طلب النقل العام الذي يتضمّن نقاطًا وسيطة على المسار إلى ظهور خطأ INVALID_ARGUMENT.
• لا تتوفّر ميزة "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL" لمسارات المشي أو ركوب الدراجات.
• بالنسبة إلى مسارات النقل العام، يمكن أن تكون أوقات المغادرة وأوقات الوصول قبل 7 أيام أو بعد 100 يوم. بالنسبة إلى وسائل النقل الأخرى، لا يمكن أن تكون في الماضي ويمكن أن تكون قبل 365 يومًا.
• يجب أن تكون إحداثيات النقاط على المسار ضمن الحدود الجغرافية الصالحة (خط العرض من ‎-90 إلى 90، وخط الطول من ‎-180 إلى 180).
• لا تعرض الأداة الاتجاهات المفصّلة أو الأقسام أو تفاصيل خطوط النقل العام.