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

عندما تحسب واجهة Routes API مسارًا، تستخدم نقاط المرور ومَعلمات الإعداد التي تقدّمها كمدخلات. بعد ذلك، تعرض واجهة برمجة التطبيقات ردًا يتضمّن المسار الافتراضي ومسارًا بديلاً واحدًا أو أكثر.

يمكن أن يتضمّن الرد أنواعًا مختلفة من المسارات وبيانات أخرى، استنادًا إلى الحقول التي تطلبها:

للاطّلاع على القائمة الكاملة لخيارات الإدخال، يُرجى الرجوع إلى خيارات المسار المتاحة ونص الطلب.

باستخدام الردّ، يمكنك تزويد عملائك بالمعلومات اللازمة لاختيار المسار المناسب لمتطلباتهم.

لمحة عن أقنعة الحقول

عند استدعاء طريقة لاحتساب مسار، يجب تحديد قناع حقل يحدّد الحقول التي تريد عرضها في الردّ. لا تتوفّر قائمة تلقائية بالحقول التي يتم عرضها. إذا حذفت هذه القائمة، ستعرض الطرق خطأً.

تعرض الأمثلة الواردة في هذا المستند عنصر الاستجابة بالكامل بدون أخذ أقنعة الحقول في الاعتبار. في بيئة الإنتاج، لن تتضمّن استجابتك سوى الحقول التي تحدّدها صراحةً في قناع الحقل.

لمزيد من المعلومات، يُرجى الاطّلاع على اختيار المعلومات التي سيتم عرضها.

لمحة عن عرض حقوق الطبع والنشر

يجب تضمين بيان حقوق الطبع والنشر التالي عند عرض النتائج للمستخدمين:

Powered by Google, ©YEAR Google

على سبيل المثال:

Powered by Google, ©2023 Google

لمحة عن المسارات والمقاطع والخطوات

قبل الاطّلاع على الردّ الذي تعرضه واجهة Routes API، يجب أن تكون على دراية بالمكوّنات التي تشكّل مسارًا:

قد يتضمّن ردّك معلومات حول كلّ عنصر من عناصر المسار هذه:

• المسار: الرحلة بأكملها من نقطة الانطلاق، مرورًا بأي نقاط توقف وسيطة، إلى نقطة الوصول يتألف المسار من مرحلة واحدة أو أكثر.

• المرحلة: هي المسار من نقطة طريق في مسار إلى نقطة الطريق التالية في المسار. يتكوّن كل جزء من خطوة واحدة أو أكثر.

  يحتوي المسار على جزء منفصل للمسار من كل نقطة طريق إلى النقطة التالية. على سبيل المثال، إذا كان المسار يحتوي على نقطة انطلاق واحدة ونقطة وصول واحدة، سيتضمّن المسار رحلة واحدة. بالنسبة إلى كل نقطة على المسار إضافية تضيفها إلى المسار بعد نقطة الانطلاق والوجهة، تُسمى نقطة على المسار وسيطة، تضيف واجهة برمجة التطبيقات جزءًا منفصلاً.

  لا تضيف واجهة برمجة التطبيقات جزءًا من الرحلة لنقطة طريق وسيطة مباشرة. على سبيل المثال، يتضمّن المسار الذي يحتوي على نقطة انطلاق ونقطة على المسار وسيطة ونقطة على المسار وجهة، جزءًا واحدًا فقط من نقطة الانطلاق إلى الوجهة، مع المرور بنقطة على المسار. لمزيد من المعلومات حول نقاط المرور، راجِع تحديد نقطة مرور.

• الخطوة: هي تعليمات فردية على طول جزء من مسار. الخطوة هي أصغر وحدة في المسار. على سبيل المثال، يمكن أن تشير إحدى الخطوات إلى "الانعطاف يسارًا في شارع Main".

محتوى الردّ

يحتوي عنصر 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:

تحتوي مصفوفة 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 Code، تمثّل هذه السمة المعرّف الخاص بالمكان الذي تمثّله الوجهة. بخلاف ذلك، يتم حذف هذا الحقل من الرد.

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