مراجعة استجابة المسار

عندما تحسب 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

بالنسبة إلى كل موقع في الطلب (أصل أو وجهة أو نقطة وسيطة) تم تحديده على أنه سلسلة عنوان أو كرمز Plus Codes، تحاول واجهة برمجة التطبيقات العثور على الموقع الأكثر صلة والذي له رقم تعريف مكان مطابق. يحتوي كل عنصر في مصفوفة geocodingResults على الحقل placeID الذي يتضمّن الموقع الجغرافي كمعرّف مكان وحقل type يحدّد نوع الموقع الجغرافي، مثل street_address أو premise أو airport.

تحتوي صفيف geocodingResults على ثلاثة حقول:

• origin: إذا تم تحديده كسلسلة عنوان أو كرمز Plus Code، معرّف المكان لنقطة الانطلاق وبخلاف ذلك، يتم حذف هذا الحقل من الرد.

• ‫destination: إذا تم تحديده كسلسلة عنوان أو رمز Plus Code، رقم تعريف المكان للوجهة بخلاف ذلك، يتم حذف هذا الحقل من الردّ.

• intermediates: مصفوفة تحتوي على معرّف المكان لأي نقاط طريق وسيطة محددة كسلسلة عنوان أو كرمز Plus Codes. إذا حدّدت نقطة اتّجاه وسيطة باستخدام معرّف مكان أو إحداثيات خط العرض وخط الطول، سيتم حذفها من الاستجابة. استخدِم السمة 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 Meile".

في ما يلي مثال على ما تراه في القيم المترجَمة:

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

في حال عدم تحديد اللغة أو نظام الوحدات، تستنتج واجهة برمجة التطبيقات اللغة والوحدات على النحو التالي:

• تستنتج طريقة ComputeRoutes الموقع الجغرافي ووحدات المسافة من نقطة التوقف الأصلية. لذلك، بالنسبة إلى طلب التوجيه في الولايات المتحدة، تفترض واجهة برمجة التطبيقات أنّ اللغة هي en-US والوحدات هي IMPERIAL.
• يتم ضبط طريقة ComputeRouteMatrix تلقائيًا على اللغة ‎"en-US" والوحدات المترية.