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

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

تحتوي صفيفة 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 على الحقل placeID الذي يحتوي على الموقع الجغرافي كرقم تعريف مكان والحقل type الذي يحدد نوع الموقع الجغرافي، مثل street_address أو premise أو airport.

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

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

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

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