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

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