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

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

توضّح هذه الصفحة خيارات الطلبات، بما في ذلك خيارات Pro، ومحتوى الردّ، وكيفية فوترة الطلبات. للاطّلاع على المخطّط الكامل للأدوات، يُرجى مراجعة مرجع compute_routes.

خيارات الطلب

Option الوصف
‫origin، destination الحقل مطلوب. وكل منها يمثّل نقطة على المسار: address (عنوان يمكن لشخص عادي قراءته أو رمز Plus Code) أو place_id أو lat_lng. يمكنك المزج بين التنسيقات، مثل عنوان لنقطة الانطلاق ورقم تعريف مكان للوجهة.
travel_mode وسيلة النقل: DRIVE (تلقائي) أو WALK أو BICYCLE أو TRANSIT لا تزال مسارات "WALK" في مرحلة تجريبية، وقد لا تتوفّر أحيانًا أرصفة واضحة أو مسارات للمشاة. يجب عرض هذا التحذير للمستخدم لجميع مسارات المشي التي تعرضها في تطبيقك.
routing_preference كيفية استخدام بيانات حركة المرور لحساب المسار: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (تلقائي) أو ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، وهو خيار Pro. لا يتوفّر "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL" لـ "WALK" أو "BICYCLE". يُرجى الاطّلاع على التوجيه المستند إلى حركة المرور.
intermediate_waypoints محطات توقّف مرتّبة بين نقطة الانطلاق والوجهة ويمر المسار من خلالها بالترتيب المحدّد. يمكن أن يتضمّن الطلب ما يصل إلى 10 نقاط على المسار، أو من 11 إلى 25 نقطة على المسار كـ خيار Pro. إذا تجاوز الطلب 25، يظهر الخطأ INVALID_ARGUMENT. لا تتيح مسارات النقل العام استخدام نقاط وسيطة على المسار.
departure_time أو arrival_time وقت المغادرة من نقطة الانطلاق أو الوصول إلى الوجهة، كطابع زمني وفقًا لمعيار RFC 3339 يُرجى ضبط قيمة واحدة كحدّ أقصى. يتم ضبط القيمة تلقائيًا على المغادرة في الوقت الحالي. بالنسبة إلى TRANSIT، يمكن أن يصل الوقت إلى 7 أيام في الماضي أو 100 يوم في المستقبل. بالنسبة إلى وسائل النقل الأخرى، لا يمكن أن يكون الوقت في الماضي ويمكن أن يصل إلى 365 يومًا في المستقبل.
compute_alternative_routes عندما تكون قيمة السمة true، تتضمّن الاستجابة مسارات بديلة بالإضافة إلى المسار المقترَح، في حال توفّر بدائل. القيمة التلقائية هي false.
include_polyline عندما تكون قيمة المَعلمة true، يتضمّن كل مسار في الردّ السمة encodedPolyline. القيمة التلقائية هي false.
location_bias خط عرض وخط طول يحدّدان كيفية حلّ النقاط النصية على المسار، على سبيل المثال لإزالة الغموض عن عنوان معيّن.

خيارات Pro

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

خيار Pro حالات الاستخدام
تم ضبط موقع routing_preference في العنوان ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL يسأل المستخدم عن حركة المرور أو الازدحام أو مدة الرحلة التي تأخذ في الاعتبار حركة المرور الحالية. يُرجى الاطّلاع على التوجيه المستند إلى حركة المرور.
من 11 إلى 25 intermediate_waypoints يتطلّب المسار أكثر من 10 محطات بين نقطة الانطلاق والوجهة.

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

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

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

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

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

مثال

يطلب الطلب التالي مسار قيادة يراعي حركة المرور مع محطة توقف وسيطة واحدة وخطوط متعدّدة مرمّزة. ويتم تحصيل رسومها ضمن رمز التخزين التعريفي 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
}

الردّ

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

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

خيارات Pro خلال فترة التوفّر المحدود للجمهور العام

خلال فترة التوفّر العام المحدود، لا تتوفّر خيارات Pro إلا للمشاريع المدرَجة في القائمة المسموح بها في Pro. إذا لم يكن مشروعك مدرجًا في القائمة المسموح بها بعد:

  • يتم التعامل مع ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL على أنّه ROUTING_PREFERENCE_TRAFFIC_UNAWARE، وتتم فوترة الطلب ضمن رمز التخزين التعريفي لـ Essentials.
  • إذا كان الطلب يتضمّن أكثر من 10 نقاط وسيطة على المسار، سيظهر الخطأ INVALID_ARGUMENT ("الحد الأقصى المسموح به هو 10 نقاط وسيطة على المسار").

لطلب الوصول، يُرجى الاطّلاع على خيارات Pro خلال فترة التوفّر العام المحدود.

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

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

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

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

الحدود

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