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

عندما تحسب 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	يشير الرمز I إلى مسار بديل.

تحتوي مصفوفة 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 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" والوحدات المترية.