عندما تحتسب Routes API مسارًا، تأخذ نقاط الطرق ومعلَمات الضبط التي تقدّمها كمدخلات. تعرض واجهة برمجة التطبيقات بعد ذلك استجابة تتضمّن المسار التلقائي ومسارًا بديلاً واحدًا أو أكثر
يمكن أن يتضمّن ردّك أنواعًا مختلفة من المسارات وبيانات أخرى، استنادًا إلى الحقول التي تطلبها:
لتضمين هذا في الرد | اطّلِع على هذا المستند. |
---|---|
المسار الأكثر توفيرًا للوقود أو الطاقة استنادًا إلى نوع محرّك المركبة | ضبط المسارات الصديقة للبيئة |
ما يصل إلى ثلاثة مسارات بديلة | طلب مسارات بديلة |
الخطوط المتعددة لمسار كامل ولكل جزء من المسار ولكل خطوة في الساق. | طلب الخطوط المتعددة للمسارات |
رسوم العبور المقدَّرة، مع مراعاة أي خصومات على رسوم العبور أو تصاريح المرور المتاحة للسائق أو المركبة. | حساب رسوم العبور |
ردود مترجَمة حسب رموز اللغات ووحدة القياس (لغة بريطانية أو مترية) | طلب قيم مترجَمة |
لتنسيق تعليمات التنقّل كسلسلة HTML نصية، أضِف السمة HTML_FORMATTED_NAVIGATION_INSTRUCTIONS إلى السمة extraComputations . |
عمليات حسابية إضافية |
للحصول على القائمة الكاملة لخيارات الإدخال، راجع خيارات المسار المتاحة ونص الطلب.
باستخدام الرد، يمكنك تزويد عملائك بالمعلومات الضرورية لتحديد المسار المناسب لمتطلباتهم.
لمحة عن أقنعة الحقول
عند استدعاء طريقة لحساب مسار، يجب عليك تحديد قناع حقل يحدد الحقول التي تريد عرضها في الاستجابة. لا توجد قائمة افتراضية للحقول المعروضة. إذا حذفت هذه القائمة، ستعرض الطرق خطأ.
تعرض الأمثلة في هذا المستند كائن الاستجابة بالكامل بدون وضع أقنعة الحقول في الاعتبار. في بيئة الإنتاج، لن يتضمّن ردّك سوى الحقول التي تحدّدها صراحةً في قناع الحقل.
ولمزيد من المعلومات، اطّلِع على اختيار المعلومات المطلوب عرضها.
لمحة عن عرض حقوق الطبع والنشر
يجب تضمين بيان حقوق الطبع والنشر التالي عند عرض النتائج للمستخدمين:
Powered by Google, ©YEAR Google
مثال:
Powered by Google, ©2023 Google
لمحة عن المسارات والأرجل والخطوات
قبل النظر إلى الرد الذي تعرضه Routes API، يجب أن تكون على دراية بالمكوّنات التي تشكّل مسارًا:
قد يحتوي الرد على معلومات حول كل من مكونات المسار التالية:
المسار: الرحلة الكاملة من نقطة الطريق المصدر، خلال أي نقاط طريق وسيطة، إلى نقطة الطريق الوجهة. يتكون المسار من رجل واحدة أو أكثر.
ساق: المسار من نقطة طريق واحدة في المسار إلى نقطة الطريق التالية في المسار. تتألف كل رِجل من واحدة أو أكثر من الخطوات المنفصلة.
يحتوي المسار على مرحلة منفصلة للمسار من كل نقطة طريق إلى الأخرى. على سبيل المثال، إذا كان المسار يحتوي على نقطة طريق واحدة لنقطة انطلاق واحدة ونقطة وسيطة واحدة لوجهة، فإن المسار يحتوي على نقطة واحدة. لكل نقطة طريق إضافية تضيفها إلى المسار بعد نقطة الانطلاق والوجهة، وتسمى نقطة وسيطة وسيطة، تضيف واجهة برمجة التطبيقات مرحلة منفصلة.
لا تضيف واجهة برمجة التطبيقات نقطة لنقطة وسيطة للتمرير. على سبيل المثال، يحتوي المسار الذي يحتوي على نقطة طريق انطلاق ونقطة طريق وسيطة عابرة ونقطة طريق للوجهة على نقطة واحدة فقط من نقطة الانطلاق إلى الوجهة، بينما يمر عبر نقطة الطريق. للحصول على مزيد من المعلومات حول نقاط الطريق لتمرير الفيديو، يُرجى الاطّلاع على تحديد نقطة اتصال لتمرير الفيديو.
الخطوة: تعليمة واحدة على طول ساق المسار. الخطوة هي الوحدة الذرية للمسار. على سبيل المثال، يمكن أن تشير الخطوة إلى "الشارع الرئيسي إلى اليسار".
ماذا يتضمّن الردّ؟
يحتوي كائن 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
لطلب معيّن لضبط لغة المسار بوضوح من قائمة اللغات المتاحة. تقوم Google في الغالب بتحديث اللغات المتوافقة، لذا قد لا تكون هذه القائمة شاملة.إذا لم يكن الاسم متاحًا باللغة المحددة، ستستخدم واجهة برمجة التطبيقات أقرب تطابق.
يمكن أن تؤثر اللغة المحددة على مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها والترتيب الذي يتم عرضها به. يفسر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة بلغة ما وليس بلغة أخرى. على سبيل المثال، utca وtér مرادفان لكلمة "شارع" باللغة المجرية.
التعرّف على مصفوفة نتائج الترميز الجغرافي
بالنسبة إلى كل موقع جغرافي في الطلب (المصدر أو الوجهة أو نقطة الطريق الوسيطة) تم تحديده على أنه سلسلة عنوان أو باعتباره رمز علامة الجمع، تحاول واجهة برمجة التطبيقات العثور على الموقع الجغرافي الأكثر صلة والذي يحتوي على رقم تعريف مكان مطابق. يحتوي كل عنصر من عناصر المصفوفة geocodingResults
على الحقل placeID
الذي يحتوي على الموقع الجغرافي كرقم تعريف مكان والحقل type
الذي يحدد نوع الموقع الجغرافي، مثل street_address
أو premise
أو airport
.
تحتوي مصفوفة geocodingResults
على ثلاثة حقول:
origin
: إذا تم تحديدها كسلسلة عنوان أو رمز Plus، فإنها تشير إلى رقم تعريف المكان الأصلي. وبخلاف ذلك، سيتم حذف هذا الحقل من الرد.destination
: إذا تم تحديدها كسلسلة عنوان أو رمز Plus، تكون هذه السمة هي رقم تعريف المكان للوجهة. وبخلاف ذلك، يتم حذف هذا الحقل من الرد.intermediates
: مصفوفة تحتوي على رقم تعريف المكان لأي نقاط مسار وسيطة محددة كسلسلة عنوان أو كرمز Plus. وإذا حددت نقطة طريق وسيطة باستخدام معرّف المكان أو إحداثيات خطي الطول والعرض، سيتم حذفها من الرد. استخدِم السمة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.