أفضل الممارسات لاستخدام Isochrones API

التنعيم والدقة

يمكنك تخصيص مظهر المضلّعات الناتجة ودقتها باستخدام المَعلمتَين polygon_fidelity وenable_smoothing. على الرغم من أنّ هذه الخيارات مستقلة، إلا أنّها تعمل معًا لتحديد الشكل النهائي.

  • ‫polygonFidelity (polygon_fidelity): دقة الشاشة يتحكّم في حجم خلايا الشبكة المكانية الأساسية المستخدَمة لاحتساب المنطقة التي يمكن الوصول إليها.

    • LOW: تستخدم أكبر خلايا الشبكة (تمتد على مئات الأمتار). هذا الخيار هو الأفضل لتغطية مساحات كبيرة بدون فجوات وتقليل عدد الرؤوس، ما يؤدي إلى شكل عام يمكن أن يبالغ في تقدير المساحة التي يمكن الوصول إليها على طول ممرات الطرق الضيقة.
    • MEDIUM: دقة متوازنة وحجم حمولة متوازن.
    • HIGH: تستخدم هذه القيمة أصغر خلايا الشبكة (حوالي 100 إلى 150 مترًا). يؤدي ذلك إلى ملاءمة أكثر إحكامًا لشبكة الطرق، مع المزيد من الرؤوس، ولكن قد ينتج عنه ثقوب داخلية حيث تكون شبكة الطرق متناثرة.
    • الإعداد التلقائي (POLYGON_FIDELITY_UNSPECIFIED): في حال عدم تحديد الدقة، تختار الخدمة الدقة تلقائيًا استنادًا إلى وضع السفر والمدة، وذلك باستخدام خلايا أدق للمدد القصيرة وWALK، وخلايا أكبر للمدد الطويلة. لمقارنة خطوط تساوي الزمن عبر مُدد أو أوضاع سفر مختلفة، اضبط polygonFidelity بشكل صريح بحيث تستخدم الدقة نفسها.

    أحجام الخلايا تقريبية. قد يتم تعميم خطوط تساوي الزمن الكبيرة جدًا للحفاظ على حجم الاستجابة قابلاً للإدارة.

  • enableSmoothing (enable_smoothing): الجمالية يتحكّم هذا الخيار في ما إذا كان سيتم تقريب الحواف المتدرّجة لخلايا الشبكة المحدّدة حسب الدقة.
    • false (أوّلي): لعرض الحدود المحاذية للشبكة تظهر الحواف خشنة أو متدرجة، مما يعكس خلايا الشبكة. وهو الأفضل للدقة التحليلية، مثل اختبارات النقطة في المضلع الصارمة.
    • true (Smoothed): لتقريب الزوايا مع الحفاظ على مساحة كل حلقة تقريبًا الأفضل للعرض المرئي على الخرائط. بما أنّ الحدود لم تعُد تتبع خلايا الشبكة، لا تستخدِمها لإجراء اختبارات صارمة لتحديد ما إذا كانت النقاط تقع داخل المضلّع.

كيفية تفاعلهما: يحدّد مستوى الدقة التفاصيل الأساسية التي تعمل عليها خوارزمية التنعيم.

  • دقة عالية + تجانس: ينتج عن هذا الخيار شكل مفصّل ذو مظهر طبيعي يتّبع نهايات الطرق عن كثب.
  • دقة منخفضة + تجانس: ينتج عن ذلك شكل "نقطة" واسع ومعمّم.

حجم الحمولة وعرضها

يمكن أن تحتوي خطوط التساوي الكبيرة (خاصةً الطلبات الطويلة المدة التي تتضمّن دقة HIGH) على عشرات الآلاف من الإحداثيات، ويمكن أن يكون ردّ JSON غير المضغوط مئات الكيلوبايت أو أكثر.

  • النطاق الترددي: يُرجى العِلم أنّ حجم استجابة JSON يكون كبيرًا في الطلبات ذات المدة القصوى والدقة العالية.
  • العرض: يؤثر عرض المضلّعات المفصّلة للغاية في أداء العميل. لتقليل عدد الرؤوس وحجم الحمولة، اختَر polygonFidelity: MEDIUM أو LOW، أو بسِّط الشكل الهندسي على العميل قبل العرض باستخدام خوارزمية تبسيط الخطوط، مثل Douglas-Peucker.

وقت الاستجابة ومهلات العميل

تزداد مهلة الاستجابة مع حجم شبكة الطرق التي يتم اجتيازها: تكون المدد القصيرة ووضعَي WALK وBICYCLE هي الأسرع، بينما تستغرق طلبات DRIVE وTWO_WHEELER الطويلة (خاصةً مع TRAFFIC_AWARE) أطول وقت.

  • مهلة العميل المقترَحة: اضبط المواعيد النهائية لعميل HTTP أو gRPC على 30 ثانية على الأقل لكي لا يتم إلغاء الطلبات الطويلة قبل الأوان بسبب مهلة قصيرة للعميل.

معالجة الأخطاء

تنفيذ منطق إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي والتشويش لردود الحدّ الأقصى لمعدّل الطلبات 429 RESOURCE_EXHAUSTED وأخطاء الخادم 5xx لا تُعِد محاولة إرسال أخطاء العميل 400 أو 403 أو 404 بدون تغيير طلبك:

  • INVALID_ARGUMENT (400): يُرجى التأكّد من أنّ قيمة travelDuration تقع بين 1s و3600s (DRIVE/TWO_WHEELER) أو 7200s (WALK/BICYCLE)، وأنّه لم يتم حذف قيمة location وأنّها ليست (0, 0) (أو أنّ قيمة place هي رقم تعريف مكان صالح)، وأنّ قيمة TRAFFIC_AWARE تُستخدَم فقط مع DRIVE أو TWO_WHEELER. يتم التعامل مع السمة latitude أو longitude المحذوفة على أنّها 0.0، لذا فإنّ حذف إحداهما فقط لا يؤدي عادةً إلى حدوث خطأ 400 (ما لم تكن القيمة الأخرى أيضًا 0.0). تحقَّق من كلتا القيمتين إذا ظهر خط التساوي الزمني في المكان الخطأ.
  • PERMISSION_DENIED (403): تأكَّد من تضمين مفتاح واجهة برمجة التطبيقات أو رمز OAuth المميّز ومن تفعيل Isochrones API والفوترة في مشروع على السحابة الإلكترونية على Google Cloud.
  • ‫NOT_FOUND (404): تعذّر تحديد الموقع الجغرافي لـ "place"، أو تعذّر ربط نقطة الانطلاق بطريق قريب يمكن استخدامه في وضع السفر (على بُعد 200 متر تقريبًا أو أقل لـ "WALK" و"BICYCLE").
  • ‫RESOURCE_EXHAUSTED (429): تجاوز مشروعك حصة الطلبات في الدقيقة (الحدّ التلقائي هو 300 طلب في الدقيقة). يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.