عندما تحتسب Routes API مسارًا، تأخذ نقاط الطرق ومَعلمات الضبط التي تقدّمها كإدخال. بعد ذلك، تعرض واجهة برمجة التطبيقات استجابة تتضمن المسار التلقائي ومسارًا بديلاً أو أكثر.
يمكن أن يتضمن ردك أنواعًا مختلفة من المسارات وبيانات أخرى، بناءً على الحقول التي تطلبها:
لتضمين هذا في الرد | الاطّلاع على هذه المستندات |
---|---|
المسار الأكثر كفاءة في استهلاك الوقود أو الطاقة حسب نوع محرّك المركبة | ضبط المسارات الصديقة للبيئة |
ما يصل إلى ثلاثة مسارات بديلة | طلب مسارات بديلة |
الخط المتعدد لمسار كامل ولكل خطوة من المسار ولكل خطوة في الساق. | طلب الخطوط المتعددة للمسارات |
الرسوم المقدَّرة، مع مراعاة أي خصومات على أسعار العبور أو تصاريح متاحة للسائق أو المركبة | احتساب رسوم العبور |
ردود مترجَمة حسب رموز اللغة ووحدة القياس (لغة بريطانية أو مترية). | طلب قيم مترجَمة |
لتنسيق تعليمات التنقّل كسلسلة نص HTML، أضِف السمة HTML_FORMATTED_NAVIGATION_INSTRUCTIONS إلى السمة extraComputations . |
عمليات حسابية إضافية |
للحصول على القائمة الكاملة لخيارات الإدخال، راجع خيارات المسارات المتاحة ونص الطلب.
باستخدام الرد، يمكنك تزويد عملائك بالمعلومات الضرورية لتحديد المسار المناسب لمتطلباتهم.
لمحة عن أقنعة الحقول
عند استدعاء طريقة لحساب مسار، يجب عليك تحديد قناع حقل يحدد الحقول التي تريد عرضها في الاستجابة. لا توجد قائمة افتراضية للحقول المعروضة. إذا حذفت هذه القائمة، ستعرض الطرق خطأً.
تعرض الأمثلة في هذا المستند كائن الاستجابة بالكامل بدون أخذ أقنعة الحقل في الاعتبار. في بيئة الإنتاج، لن يتضمن ردّك سوى الحقول التي تحدّدها صراحةً في قناع الحقل.
لمزيد من المعلومات، راجِع اختيار المعلومات المطلوب عرضها.
لمحة عن عرض حقوق الطبع والنشر
يجب تضمين بيان حقوق الطبع والنشر التالي عند عرض النتائج للمستخدمين:
Powered by Google, ©YEAR Google
مثال:
Powered by Google, ©2023 Google
لمحة عن المسارات والأرجل والخطوات
قبل الاطّلاع على الردّ الذي توفّره واجهة برمجة تطبيقات Routes، يجب أن تكون على دراية بالمكوّنات التي تشكّل المسار:
قد تحتوي ردك على معلومات حول كل من مكونات المسار التالية:
المسار: الرحلة الكاملة من نقطة الاتجاه في نقطة الانطلاق، مرورًا بأي نقاط وسيطة وسيطة، إلى نقطة الطريق المقصودة. يتكون المسار من ساق واحدة أو أكثر.
محطة: المسار من نقطة طريق في مسار إلى نقطة وسيطة تالية في المسار. وتتألف كل ساق من خطوة منفصلة أو أكثر.
يحتوي المسار على نقطة منفصلة للمسار من كل نقطة طريق إلى أخرى. على سبيل المثال، إذا كان المسار يحتوي على نقطة طريق ذات منشأ واحد ونقطة طريق بوجهة واحدة، يحتوي المسار على محطة واحدة. تُضيف واجهة برمجة التطبيقات نقطة منفصلة لكل نقطة طريق إضافية تضيفها إلى المسار بعد نقطة الانطلاق والوجهة، وتُعرف باسم نقطة طريق وسيطة.
لا تضيف واجهة برمجة التطبيقات نقطة لنقطة وسيطة للتمرير. على سبيل المثال، يحتوي المسار الذي يحتوي على نقطة وسيطة لنقطة انطلاق، ونقطة طريق وسيطة عابرة، ونقطة طريق للوجهة على نقطة واحدة فقط من نقطة الأصل إلى الوجهة، بينما تمر بالنقطة الوسيطة. للحصول على مزيد من المعلومات حول نقاط طريق المرور، يُرجى الاطّلاع على القسم تحديد نقطة طريق لتمرير المحتوى.
الخطوة: تعليمات واحدة على طول الجزء السفلي من المسار. الخطوة هي الوحدة الذرية للمسار. على سبيل المثال، قد تشير الخطوة إلى "الاتجاه لليسار في الشارع الرئيسي".
محتوى الرد
يحتوي كائن JSON الذي يمثّل استجابة واجهة برمجة التطبيقات على خصائص المستوى الأعلى التالية:
routes
، وهي مصفوفة من العناصر من النوع Route. تحتوي مصفوفةroutes
على عنصر واحد لكل مسار تعرضه واجهة برمجة التطبيقات. ويمكن أن تحتوي المصفوفة على خمسة عناصر كحد أقصى: المسار التلقائي والمسار الصديق للبيئة وما يصل إلى ثلاثة مسارات بديلة.geocodingResults
، وهي مصفوفة من العناصر من نوع GeocodingResults. بالنسبة إلى كل موقع جغرافي في الطلب (الأصل أو الوجهة أو نقطة طريق وسيطة) حدَّدته على أنّه سلسلة عنوان أو رمز موقع جغرافي، تُجري واجهة برمجة التطبيقات عملية بحث عن رقم تعريف المكان. يحتوي كل عنصر من هذه الصفيفة على معرّف المكان المقابل لموقع ما. لا يتم تضمين المواقع في الطلب المحددة على أنها رقم تعريف مكان أو كإحداثيات خطوط الطول/العرض. إذا حدّدت جميع المواقع الجغرافية باستخدام أرقام تعريف الأماكن أو إحداثيات خطوط الطول والعرض، لن يتم تقديم هذه الصفيفة.fallbackInfo
، من النوع FallbackInfo إذا لم تتمكّن واجهة برمجة التطبيقات من احتساب مسار من جميع خصائص الإدخال، قد تتراجع عن استخدام طريقة حسابية مختلفة. عند استخدام الوضع الاحتياطي، يحتوي هذا الحقل على معلومات مفصّلة حول الاستجابة الاحتياطية. وبخلاف ذلك، لن يتم ضبط هذا الحقل.
يكون الرد على النحو التالي:
{ // The routes array. "routes": [ { object (Route) } ], // The place ID lookup results. "geocodingResults": [ { object (GeocodedWaypoint) } ], // The fallback property. "fallbackInfo": { object (FallbackInfo) } }
فك تشفير صفيف المسارات
تحتوي الاستجابة على المصفوفة routes
، حيث يكون كل عنصر من عناصر الصفيف من النوع
Route.
يمثل كل عنصر صفيف مسارًا كاملاً من نقطة الانطلاق إلى الوجهة. تعرض واجهة برمجة التطبيقات دائمًا مسارًا واحدًا على الأقل، يُسمى المسار الافتراضي.
يمكنك طلب مسارات إضافية. إذا طلبت مسارًا صديقًا للبيئة، يمكن أن تحتوي المصفوفة على عنصرين: المسار التلقائي والمسار الصديق للبيئة. يمكنك بدلاً من ذلك ضبط السمة computeAlternativeRoutes
على
true
في الطلب لإضافة ما يصل إلى ثلاثة مسارات بديلة إلى الاستجابة.
يتم التعرف على كل مسار في المصفوفة باستخدام خاصية الصفيف routeLabels
:
القيمة | الوصف |
---|---|
DEFAULT_ROUTE |
تحدِّد المسار التلقائي. |
FUEL_EFFICIENT |
تحدِّد المسار الصديق للبيئة. |
DEFAULT_ROUTE_ALTERNATE |
يشير إلى مسار بديل. |
تحتوي مصفوفة legs
على تعريف كل مرحلة من المسار. تحتوي الخصائص المتبقية، مثل distanceMeters
وduration
وpolyline,
، على معلومات حول المسار ككل:
{ "routeLabels": [ enum (RouteLabel) ], "legs": [ { object (RouteLeg) } ], "distanceMeters": integer, "duration": string, "routeLabels": [string], "staticDuration": string, "polyline": { object (Polyline) }, "description": string, "warnings": [ string ], "viewport": { object (Viewport) }, "travelAdvisory": { object (RouteTravelAdvisory) } "routeToken": string }
بسبب ظروف القيادة الحالية وعوامل أخرى، يمكن أن يكون المسار التلقائي
والمسار الصديق للبيئة متطابقَين. في هذه الحالة، تحتوي مصفوفة routeLabels
على كلا التصنيفين: DEFAULT_ROUTE
وFUEL_EFFICIENT
.
{ "routes": [ { "routeLabels": [ "DEFAULT_ROUTE", "FUEL_EFFICIENT" ], … } ] }
التعرّف على صفيفة الساقين
يحتوي كل route
في الاستجابة على المصفوفة legs
حيث يكون كل عنصر من عناصر المصفوفة legs
من النوع RouteLeg.
تحدد كل نقطة في الصفيف المسار من نقطة طريق إلى نقطة الطريق التالية على طول المسار. يحتوي المسار دائمًا على ساق واحدة على الأقل.
تتضمن السمة legs
تعريف كل خطوة على الساق في المصفوفة steps
. وتحتوي السمات المتبقية، مثل distanceMeters
وduration
وpolyline
، على معلومات حول الساق.
{ "distanceMeters": integer, "duration": string, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "steps": [ { object (RouteLegStep) } ], "travelAdvisory": { object (RouteLegTravelAdvisory) } }
فهم صفيف الخطوات
تحتوي كل مرحلة في الإجابة على مصفوفة steps
حيث يكون كل عنصر من عناصر المصفوفة steps
من النوع
RouteLegStep.
الخطوة تتجاوب مع تعليمة واحدة على طول الساق. تحتوي الساق دائمًا
على خطوة واحدة على الأقل.
يشتمل كل عنصر في مصفوفة steps
على السمة navigationInstruction
من النوع
NavigationInstruction
الذي يحتوي على التعليمات الخاصة بالخطوات. مثال:
"navigationInstruction": { "maneuver": "TURN_LEFT", "instructions": "Turn left toward Frontage Rd" }
قد يحتوي instructions
على معلومات إضافية عن الخطوة. على سبيل المثال:
"navigationInstruction": { "maneuver": "TURN_SLIGHT_LEFT", "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days" }
توضّح السمات المتبقية في الخطوة معلومات عن الخطوة، مثل distanceMeters
وduration
وpolyline
:
{ "distanceMeters": integer, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "navigationInstruction": { object (NavigationInstruction) } }
حدِّد لغة تعليمات الخطوة.
تعرض واجهة برمجة التطبيقات معلومات المسار باللغة المحلية، ويتم تحويلها صوتيًا إلى نص برمجي يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. يتم عرض جميع مكونات العنوان باللغة نفسها.
استخدِم المَعلمة
languageCode
لأي طلب لضبط لغة المسار بوضوح من قائمة اللغات المتوافقة. يتم في الغالب تحديث اللغات المعتمدة، لذا قد لا تكون هذه القائمة شاملةوإذا لم يكن الاسم متاحًا باللغة المحددة، ستستخدم واجهة برمجة التطبيقات أقرب تطابق.
يمكن أن تؤثر اللغة المحددة على مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها والترتيب الذي تظهر به. يفسِّر الترميز الجغرافي الاختصارات بشكل مختلف استنادًا إلى اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة للغة معيّنة وليس بلغة أخرى. على سبيل المثال، utca وtér مرادفان لكلمة الشارع باللغة المجرية.
التعرّف على مصفوفة نتائج الترميز الجغرافي
بالنسبة إلى كل موقع جغرافي في الطلب (الأصل أو الوجهة أو نقطة طريق وسيطة) تم تحديده على أنّه سلسلة عنوان أو رمز علامة الجمع، تحاول واجهة برمجة التطبيقات العثور على الموقع الجغرافي الأكثر صلة والذي له رقم تعريف مكان مطابق. يحتوي كل عنصر في مصفوفة
geocodingResults
على الحقل placeID
الذي يحتوي على الموقع الجغرافي كرقم تعريف مكان والحقل type
الذي يحدّد نوع الموقع الجغرافي، مثل street_address
أو premise
أو airport
.
تحتوي مصفوفة geocodingResults
على ثلاثة حقول:
origin
: إذا تم تحديده كسلسلة عنوان أو كرمز Plus، يكون رقم تعريف المكان الأصلي. وبخلاف ذلك، سيتم حذف هذا الحقل من الرد.destination
: إذا تم تحديده كسلسلة عنوان أو كرمز Plus، يكون رقم تعريف المكان للوجهة. وبخلاف ذلك، يتم حذف هذا الحقل من الرد.intermediates
: مصفوفة تحتوي على رقم تعريف المكان لأي نقاط طريق وسيطة محددة كسلسلة عنوان أو كرمز زائد. في حال تحديد نقطة وسيطة وسيطة باستخدام معرّف مكان أو إحداثيات خط العرض وخط الطول، سيتم حذفها من الإجابة. استخدِم السمةintermediateWaypointRequestIndex
في الردّ لتحديد نقطة الطريق المتوسطة في الطلب التي تتوافق مع رقم تعريف المكان في الردّ.
"geocodingResults": { "origin": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "destination": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "intermediates": [ { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string }, { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string } ] }
فهم قيم الردود المترجَمة
قيم الاستجابة المترجَمة هي حقل استجابة إضافي يوفر نصًا مترجمًا لقيم المعلمات المعروضة. يتم توفير نص مترجم لمدة الرحلة والمسافة ونظام الوحدات (مقياس أو إمبراطوري). ويمكنك طلب قيم مترجَمة باستخدام قناع حقل، ويمكنك تحديد اللغة ونظام الوحدات أو استخدام القيم التي تستنتجها واجهة برمجة التطبيقات. لمعرفة التفاصيل، يُرجى الاطّلاع على LocalizedValues.
على سبيل المثال، إذا حددت رمز لغة للوحدات الألمانية (de) والإمبراطورية، فستحصل على قيمة distanceMeters
للعدد 49889.7، وستحصل أيضًا على نص مترجم يوفر قياس المسافة بالوحدات الألمانية والإمبراطورية، هكذا "31 ميل".
في ما يلي مثال لما يمكن أن تراه في القيم المترجمة:
{ "localized_values": { "distance": { "text": "31,0 Meile/n" }, "duration": { "text": 38 Minuten}. "static_duration": { "text": 36 Minuten}. } }
إذا لم تحدّد اللغة أو نظام الوحدات، تستنتج واجهة برمجة التطبيقات اللغة والوحدات على النحو التالي:
- تستنتج الطريقة
ComputeRoutes
الموقع الجغرافي ووحدات المسافة من نقطة الطريق المصدر. إذًا في ما يخص طلب التوجيه في الولايات المتحدة، تستنتج واجهة برمجة التطبيقات لغةen-US
وIMPERIAL
وحدة. - يتم ضبط الطريقة
ComputeRouteMatrix
تلقائيًا على لغة "en-US" ووحدات METRIC.