Routes API هي خدمة ويب تتضمّن طريقتَين: تعرض طريقة Compute Routes مسارًا بين موقعَين جغرافيَّين مع نقاط وسيطة اختيارية على المسار، وتعرض طريقة Compute Route Matrix مسافة السفر والوقت لمجموعات من نقاط الانطلاق والوجهات (ما يصل إلى 625 عنصر مسار).
Routes API: حقائق رئيسية
- المنتج: Routes API
- تُعرف أيضًا باسم: الإصدار 2 من Routes API وCompute Routes وCompute Route Matrix
- الفئة: المسارات
- المنصة: خدمة ويب (REST)
- يتم تشغيله على: الخادم (رمز الخلفية)
- مرحلة الإطلاق: GA
- Lifecycle: نشط
- نظرة عامة: نظرة عامة على Routes API
- نطاق التوفّر الجغرافي: على مستوى العالم تقتصر ميزات تحديد مسارات الدراجات النارية والمسارات الصديقة للبيئة واحتساب رسوم العبور على البلدان والمدن التي تتوفّر فيها هذه الميزات، ولا تتوفّر في الأقاليم التابعة التي لها رمز CLDR خاص بها ما لم تكن مدرَجة. بالنسبة إلى عناوين إرسال الفواتير في المنطقة الاقتصادية الأوروبية، تحظر بنود المنطقة الاقتصادية الأوروبية على الرابط https://developers.google.com/maps/comms/eea/routes استخدام أوصاف المسارات أو خطواتها مع أي خريطة. (تفاصيل التغطية)
Routes API: حالات الاستخدام
استخدِم Routes API في الحالات التالية:
- تحتاج إلى مسار بين نقطة انطلاق ووجهة، مع نقاط على المسار وسيطة اختيارية، للقيادة أو المشي أو ركوب الدراجات أو الدراجات النارية أو وسائل النقل العام.
- تحتاج إلى مسافات وأوقات السفر للعديد من أزواج نقاط الانطلاق والوجهات في طلب واحد (ما يصل إلى 625 عنصرًا).
- تحتاج إلى تقديرات رسوم العبور (في مدن محدّدة) أو مسارات صديقة للبيئة (في مناطق محدّدة) أو خطوط متعدّدة تراعي حركة المرور أو مسارات للمركبات الكبيرة (تتوفّر بكمية محدودة).
- إذا كنت تنقل تطبيق خادم من واجهة برمجة التطبيقات Directions API أو Distance Matrix API القديمة
لا تستخدِم Routes API في الحالات التالية:
- عليك تحسين مهام التحميل وإيقاف الطلبات لأسطول كامل من المركبات. يمكنك استخدام Route Optimization API بدلاً من ذلك.
- تحتاج إلى اتجاهات مفصّلة داخل التطبيق على Android تتّبع مسارًا محسوبًا. يمكنك استخدام حزمة تطوير البرامج للتنقّل على أجهزة Android بدلاً من ذلك.
- تحتاج إلى اتجاهات مفصّلة داخل التطبيق على نظام التشغيل iOS تتّبع مسارًا محسوبًا. يمكنك استخدام حزمة تطوير البرامج للتنقّل على أجهزة iOS بدلاً من ذلك.
Routes API: الإعداد
- الخدمة المطلوب تفعيلها:
routes.googleapis.com - المصادقة: مفتاح واجهة برمجة التطبيقات، وOAuth 2.0، وحساب الخدمة
- البدء: إعداد Routes API
- المرجع: مرجع واجهة برمجة التطبيقات Routes
- الأسعار: استخدام Routes API والفوترة
- السياسات: سياسات Routes API
- ملاحظات الإصدار: ملاحظات إصدار Routes API
حِزم Routes API الرسمية:
- npm:
@googlemaps/routing - pypi:
google-maps-routing - go:
cloud.google.com/go/maps - maven:
com.google.maps:google-maps-routing
Routes API: المنتجات ذات الصلة
- تحلّ محلّ: Directions API وDistance Matrix API
- تُستخدم غالبًا مع: Navigation SDK لنظام التشغيل Android وNavigation SDK لنظام التشغيل iOS وRoute Optimization API وGeocoding API وPlaces API (الإصدار الجديد)
Routes API: الأخطاء الشائعة
- المشكلة: لا تتوفّر قائمة تلقائية بالحقول التي يتم عرضها، وتؤدي الطلبات التي لا تتضمّن قناع حقل (العنوان
X-Goog-FieldMaskأو المَعلمة$fields) إلى ظهور خطأ. الحلّ: أرسِل دائمًا قناع حقل يسرد حقول الاستجابة التي تحتاج إليها. يُرجى الاطّلاع على /maps/documentation/routes/choose_fields. - المشكلة: يؤدي استخدام قناع حقل حرف البدل (
*) في مرحلة الإنتاج إلى زيادة التكلفة ووقت الاستجابة، ويمكن أن ترتفع التكلفة بشكل غير متوقّع عند إضافة ميزات متقدّمة جديدة إلى الردّ. الحلّ: استخدِم*فقط أثناء التطوير، واطلب في مرحلة الإنتاج الحقول التي تحتاج إليها فقط. يُرجى الاطّلاع على /maps/documentation/routes/choose_fields. - المشكلة: لا يتم عرض معلومات رسوم العبور واستهلاك الوقود بمجرد إضافتها إلى قناع الحقل، لأنّه يجب تفعيلها صراحةً منذ الإصدار العلني. الحلّ: أضِف مصفوفة
extraComputations(على سبيل المثالTOLLSوFUEL_CONSUMPTION) إلى الطلب بالإضافة إلى قناع الحقل. يُرجى الاطّلاع على /maps/documentation/routes/migrate-routes-preview. - المشكلة: تسمح واجهة برمجة التطبيقات Compute Route Matrix باستخدام 625 عنصرًا، ولكنّها تسمح باستخدام 100 عنصر فقط عندما تكون قيمة
routingPreferenceهيTRAFFIC_AWARE_OPTIMAL. الحلّ: يجب أن يكون عدد نقاط الانطلاق × الوجهات أقل من أو يساوي 100 عند استخدامTRAFFIC_AWARE_OPTIMAL، أو يمكنك تقسيم الطلب. يُرجى الاطّلاع على /maps/documentation/routes/compute_route_matrix.
الإجراءات التي تتيح Routes API تنفيذها
يمكنك الاطّلاع على الأدلة المرتبطة أدناه لكل مهمة، أو المقارنة بين المنتجات في مستكشف الإمكانات.
- تتيح لك هذه الخدمة الحصول على الاتجاهات بين إحداثيات خطوط العرض/الطول كسلسلة من الإحداثيات لكل خطوة على طول المسار.
- تتيح لك هذه الخدمة الحصول على اتجاهات بين مجموعتَين أو أكثر من إحداثيات خطوط العرض/الطول كسلسلة من أوصاف المناورات للخطوات على طول المسار.
- تتيح هذه الدالة عرض المسافة بين كل خطوة على طول مسار بين مجموعتَين أو أكثر من إحداثيات خطوط العرض/الطول.
- تُعرِض هذه الدالة مدة الرحلة بين كل خطوة على طول مسار بين مجموعتَين أو أكثر من إحداثيات خطوط العرض/الطول.
- عرض خط متعدّد الخطوط مشفّر بين كل خطوة على طول مسار بين مجموعتين أو أكثر من إحداثيات خطوط العرض/الطول
- عرض المسافة لمسار بين مجموعتين أو أكثر من إحداثيات خطوط العرض/الطول
- عرض مدة الرحلة لمسار بين مجموعتين أو أكثر من إحداثيات خطوط العرض/الطول
- عرض خط متعدّد مُرمَّز لمسار بين مجموعتَين أو أكثر من إحداثيات خطوط العرض/الطول
- عرض معلومات رسوم العبور لمسار بين مجموعتَين أو أكثر من إحداثيات خطوط العرض/الطول
- حدِّد وضع السفر (القيادة أو النقل العام أو المشي أو ركوب درّاجة نارية) لطلب مسار. ملاحظة: في خدمة الويب Routes API (computeRoutes)، مرِّر travelMode في نص HTTP POST JSON باستخدام RouteTravelMode (DRIVE أو BICYCLE أو TWO_WHEELER أو WALK أو TRANSIT أو TRUCK مع routeModifiers.vehicleInfo) وأدرِج عنوان X-Goog-FieldMask المطلوب بدلاً من مَعلمة طلب البحث القديمة GET mode. في مكتبة Routes في Maps JavaScript API، مرِّر travelMode والحقول في ComputeRoutesRequest.
- تحديد محطة توقّف أو نقطة عبور لطلب مسار
- تحديد كيفية استخدام بيانات حركة المرور في طلب مسار
- تحديد الميزات التي يجب تجنّبها، مثل الطرق السريعة أو رسوم العبور، لطلب مسار
- ضبط نقاط على طول المسار:
- ضبط نقاط وسيطة على المسار:
- حدِّد نقطة ليمرّ المسار من خلالها.
- تحديد اتجاه المركبة وجانب الطريق لمسار معيّن
- تحسين ترتيب محطات التوقّف في مسارك
- تحديد مسار صديق للبيئة لطلب مسارات معاينة
- تحديد مسافة أقصر أو مسار بديل لطلب مسارات ملاحظة: في Routes API، يكون طلب مسار مرجعي أقصر (SHORTER_DISTANCE) ميزة تجريبية، في حين أنّ طلب مسارات بديلة (computeAlternativeRoutes) هو ميزة متاحة للجمهور العام.
- عرض المسافات لمصفوفة من المسارات بين نقاط انطلاق ووجهات متعددة
- عرض مُدد الرحلات لمصفوفة من المسارات بين نقاط انطلاق ووجهات متعددة
- عرض معلومات رسوم العبور لمصفوفة من المسارات بين نقاط انطلاق ووجهات متعددة
- حدِّد وسيلة النقل (القيادة أو النقل العام أو المشي أو المركبات ذات العجلتين) لطلب مصفوفة المسارات. ملاحظة: في خدمة الويب Routes API (computeRouteMatrix)، يجب تمرير travelMode في نص HTTP POST JSON باستخدام RouteTravelMode (DRIVE أو TWO_WHEELER أو WALK أو TRANSIT أو TRUCK مع origins[].routeModifiers.vehicleInfo، ولا تتوفّر BICYCLE لمصفوفات المسارات) وتضمين عنوان X-Goog-FieldMask المطلوب. في مكتبة المسارات في Maps JavaScript API، مرِّر travelMode والحقول في ComputeRouteMatrixRequest.