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

عندما تحتسب 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. بالنسبة إلى كل موقع جغرافي في الطلب (أصل أو وجهة أو نقطة وسيطة) حدّدته كسلسلة عنوان أو كرمز Plus Codes، تُجري واجهة برمجة التطبيقات بحثًا عن معرّف المكان. يحتوي كل عنصر من هذه الصفيفة على معرّف المكان المقابل للموقع. لا يتم تضمين المواقع الجغرافية في الطلب المحددة على أنها رقم تعريف مكان أو كإحداثيات خطوط الطول/العرض. إذا حددت جميع المواقع باستخدام معرّفات الأماكن أو إحداثيات خطوط العرض والطول، لن يتم تقديم هذا الصفيف.

• 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 Codes، هذا يعني رقم تعريف المكان للأصل. وبخلاف ذلك، يتم حذف هذا الحقل من الرد.

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

• 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 ميل".

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

{ "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.