ما هي أهمية نقل البيانات إلى Routes API؟

المطوّرون في المنطقة الاقتصادية الأوروبية

توفّر Routes API أداءً محسّنًا لاحتساب الاتجاهات والمسافة ومدة الرحلة، ما يجعلها بديلاً مناسبًا للتطبيقات التي تستخدم Directions API وDistance Matrix API. معظم وظائف Routes API متوافقة مع الأنظمة القديمة لكلّ من Directions API وDistance Matrix API.

استخدِم هذا الدليل للتعرّف على الاختلافات الرئيسية بين Routes API والمنتجات التي يحلّ محلّها، بالإضافة إلى كيفية التعامل مع التغييرات اللازمة. لمزيد من التفاصيل حول ميزات Routes API الأخرى، يُرجى الاطّلاع على نظرة عامة على المنتج.

التحسينات الرئيسية

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

زيادة الحدود القصوى المسموح بها للطلبات

Routes API Compute Route Matrix
  • الحد الأقصى هو 625 عنصرًا، ما لم تحدّد TRAFFIC_AWARE_OPTIMAL.
  • الحد الأقصى هو 100 عنصر مع TRAFFIC_AWARE_OPTIMAL. اطّلِع على إعدادات التوجيه المحسّنة.
  • يمكن استخدام 50 نقطة مرور كحدّ أقصى (نقاط انطلاق + وجهات) باستخدام رقم تعريف المكان.
Distance Matrix API
  • يمكنك إدخال 25 مصدرًا أو 25 وجهة كحدّ أقصى لكل طلب.
  • الحد الأقصى هو 100 عنصر (عدد المصادر × عدد الوجهات) لكل طلب من جهة الخادم.

ردود أسرع على الطلبات

توفّر ميزة "حساب مصفوفة المسارات" تحسينات زمن الاستجابة التالية:

  • تلقّي عناصر البث من الردّ قبل احتساب المصفوفة بأكملها
  • استخدِم أقنعة الحقول لتخصيص تفاصيل الردود، واطلب البيانات التي تحتاجها فقط، وهي أفضل ممارسة تساعد أيضًا في خفض التكلفة.
  • تحسين عمليات احتساب المسارات للزيارات، ما يتيح لك الموازنة بين جودة البيانات ووقت الاستجابة.

تحسينات على التوجيه

توفّر ميزة "حساب المسار" تحسينات التوجيه التالية:

  • معلومات عن رسوم المرور بالإضافة إلى المسافة والوقت المقدَّر للوصول
  • مسارات المركبات ذات العجلتين
  • تأهُّل نقاط التوقف المؤقت من أجل السلامة
  • تحسين دقة الوقت المقدَّر للوصول من خلال تحديد اتجاه السفر وجانب الطريق لنقاط الطريق

طلب البيانات التي تحتاج إليها فقط

يمكنك الآن تحديد الحقول التي تريد عرضها، ما يقلّل من وقت المعالجة وتكاليف الفوترة.

Routes API
Compute Routes
Compute Route Matrix 		يجب أن تستخدم طلباتك قناع حقل لتحديد الحقول التي تريد عرضها في الرد. يضمن إخفاء الحقول عدم طلب بيانات غير ضرورية، ما يؤدي إلى تجنُّب وقت المعالجة ورسوم الفوترة غير الضرورية.
لمزيد من المعلومات، يُرجى الاطّلاع على اختيار الحقول التي سيتم عرضها.
Directions API
Distance Matrix API 		تعرِض هذه السمة قائمة تلقائية بالحقول، حتى إذا لم يكن تطبيقك بحاجة إليها بشكل صارم. ويمكن أن يؤدي ذلك إلى إضاعة وقت المعالجة وتحمّل رسوم فوترة غير ضرورية.

تحسين عمليات احتساب المسارات المتعلقة بحركة المرور

تتيح واجهة Routes API ثلاثة خيارات مفضّلة للتوجيه يمكنك استخدامها للموازنة بين وقت استجابة الطلب وجودة البيانات عند طلب معلومات حول حركة المرور.

لمزيد من المعلومات، يُرجى الاطّلاع على ضبط الجودة مقابل وقت الاستجابة.

TRAFFIC_UNAWARE
(تلقائي)		 يستخدم متوسط بيانات حركة المرور غير المرتبطة بالوقت، وليس بيانات حركة المرور المباشرة، لاحتساب المسار، ما يؤدي إلى أقل وقت استجابة. هذا الإعداد مكافئ للحالة التي لا يتم فيها استخدام بيانات حركة المرور في Directions API وDistance Matrix API.
TRAFFIC_AWARE
(جديد)		 جودة بيانات حركة المرور المباشرة محسّنة لتحقيق أفضل أداء وتقليل وقت الاستجابة على عكس TRAFFIC_AWARE_OPTIMAL، يطبّق هذا الإعداد تحسينات لتقليل وقت الاستجابة بشكل كبير. هذا الإعداد جديد أيضًا في Routes API وليس له أي مكافئ في Directions API أو Distance Matrix API.
TRAFFIC_AWARE_OPTIMAL بيانات شاملة وعالية الجودة حول حركة المرور يؤدي هذا الإعداد إلى أعلى وقت استجابة وهو يعادل الإعداد departure_time في Directions API وDistance Matrix API.
يتطابق هذا الخيار مع الوضع المستخدَم في maps.google.com وفي تطبيق "خرائط Google" للأجهزة الجوّالة.

مقارنة احتساب المسار

يقارن الجدول التالي بين خيارات التوجيه بين خدمات Routes API وDirections API وDistance Matrix API.

خيار عدد الزيارات Routes API Directions API
Distance Matrix API		 وقت الاستجابة
ما مِن بيانات لحركة المرور في الوقت الفعلي TRAFFIC_UNAWARE لم يتم ضبط موقع واحد (departure_time). أسرع وقت استجابة بين الأوضاع الثلاثة
تطبيق أحوال حركة المرور المباشرة TRAFFIC_AWARE بدون مكافئ

تمت إضافة وضع جديد من خلال Routes API. ويوفّر وقت استجابة أسرع قليلاً من TRAFFIC_UNAWARE، ولكن بجودة أقل قليلاً في تقدير الوقت.

تكون مدة الاستجابة فيه أقل بكثير من TRAFFIC_AWARE_OPTIMAL.
تطبيق بيانات شاملة وعالية الجودة لحركة المرور في الوقت الفعلي TRAFFIC_AWARE_OPTIMAL مجموعة مواقع (departure_time)

وهو يعادل الوضع المستخدَم في maps.google.com وفي تطبيق "خرائط Google" للأجهزة الجوّالة.

بالنسبة إلى Compute Route Matrix، لا يمكن أن يتجاوز عدد العناصر في الطلب (عدد نقاط الانطلاق × عدد نقاط الوصول) 100.

الاختلافات الرئيسية

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

الاتصال بخدمة واحدة بدلاً من اثنتين

Routes API فعِّل خدمة واحدة فقط في API Console لكي يتمكّن تطبيقك من استخدام Compute Routes وCompute Route Matrix.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الإعداد في وحدة تحكّم واجهات Google API.
Directions API
Distance Matrix API 		فعِّل خدمتَين: Directions API وDistance Matrix API كخدمتَين منفصلتَين في API Console.

استخدام طلبات HTTPS POST

Routes API مرِّر المَعلمات في نص الطلب أو في العناوين كجزء من طلب HTTP POST.
للاطّلاع على أمثلة، يُرجى الرجوع إلى:
- حساب مسار
- حساب مصفوفة مسارات
Directions API
Distance Matrix API 		مرِّر مَعلمات عنوان URL باستخدام طلب HTTP GET.

الاختلافات في الردود على الوقت المقدّر للوصول

تعرض واجهة Routes API الوقت المقدَّر للوصول وتستخدم السمة duration في الرد بشكل مختلف عن خدمتي Directions API وDistance Matrix API، كما هو موضّح في الجدول أدناه.

نوع الإعلان النصي الموسّع Routes API Directions API
Distance Matrix API
وقت مقدَّر للوصول لا يعتمد على حركة المرور ولا على الوقت

اضبطها باستخدام TRAFFIC_UNAWARE.

  • يتم تضمين الوقت المقدّر للوصول في سمة الاستجابة duration.
  • تحتوي سمتَا الاستجابة duration وstaticDuration على القيمة نفسها.

يتوافق مع عدم ضبط departure_time في الطلب.

  • يتم تضمين الوقت المقدّر للوصول في سمة الاستجابة duration.
  • لا يتم عرض سمة الاستجابة duration_in_traffic.
وقت وصول مقدَّر يأخذ في الاعتبار حركة المرور في الوقت الفعلي

اضبطها باستخدام TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL.

  • يتم تضمين الوقت المقدَّر للوصول مع مراعاة حركة المرور في الوقت الفعلي في سمة الاستجابة duration.
  • تحتوي السمة staticDuration في الرد على مدة التنقّل على طول المسار بدون أخذ حالة حركة المرور في الاعتبار.
  • لم يعُد يتم عرض السمة duration_in_traffic.

اضبط القيمة باستخدام departure_time في الطلب.

  • يتم تضمين الوقت المقدَّر للوصول مع مراعاة حركة المرور في الوقت الفعلي في سمة الاستجابة duration_in_traffic.

نقاط طريق متعددة

لم يعُد عليك تحويل إحداثيات خطوط الطول والعرض إلى نقاط طريق متعددة الخطوط باستخدام هذه الخدمة التي تتيح نص طلب POST، وبالتالي لم تعُد تتأثر بحدود سلسلة عناوين URL. حلّ بعض مستخدمي Distance Matrix API مشكلة حدود الطلبات من خلال تحويل نقاط خطوط الطول والعرض إلى نقاط توقّف في خطوط متعدّدة الأضلاع.

العناوين المنسَّقة (الترميز الجغرافي العكسي)

لا توفّر واجهة Routes API عناوين منسَّقة في الردّ. للحصول على عناوين منسَّقة، استخدِم Geocoding API المصمَّمة لحالة الاستخدام هذه والتي توفّر نتائج بجودة أعلى.

وسائل النقل المتاحة

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

تنسيق XML كاستجابة

لا توفّر واجهة Routes API تنسيق XML كشكل استجابة. يمكنك العثور على عدد من أدوات تحويل JSON إلى XML على الإنترنت، والتي من المفترض أن تناسب أغراضك.