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

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

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

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

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

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

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

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

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

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

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

Powered by Google, ©YEAR Google

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

Powered by Google, ©2023 Google

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

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

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

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

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

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

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

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

محتوى الرد

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

تحتوي مصفوفة 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

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

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

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

• ‫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" ووحدات القياس المترية.