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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

لتضمين ذلك في الردّ يُرجى الاطّلاع على هذه المستندات
المسار الأقل استهلاكًا للوقود أو الطاقة استنادًا إلى نوع محرّك المركبة ضبط المسارات الصديقة للبيئة
ما يصل إلى ثلاثة مسارات بديلة طلب مسارات بديلة
الخطوط المتعدّدة لمسار كامل، ولكل جزء من المسار، ولكل خطوة من جزء. طلب خطوط متعدّدة للمسار
رسوم العبور المقدّرة، مع الأخذ في الاعتبار أي خصومات على أسعار رسوم العبور أو بطاقات المرور المتاحة للسائق أو المركبة احتساب رسوم العبور
الردود المترجَمة حسب رموز اللغة ووحدة القياس (النظام الإمبراطوري أو النظام المتري) طلب القيم المترجَمة
لتنسيق تعليمات التنقّل كسلسلة نصية بتنسيق HTML، أضِف HTML_FORMATTED_NAVIGATION_INSTRUCTIONS إلى extraComputations. عمليات حسابية إضافية

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

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

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

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

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

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

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

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

Powered by Google, ©YEAR Google

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

Powered by Google, ©2023 Google

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

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

المسار والجزء والخطوة

قد يتضمّن الردّ معلومات عن كلّ من مكوّنات المسار التالية:

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

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

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

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

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

محتوى الردّ

يحتوي عنصر JSON الذي يمثّل الردّ من واجهة برمجة التطبيقات على السمات التالية ذات المستوى الأعلى:

  • ‫routes، مصفوفة من عناصر من النوع Route. تحتوي مصفوفة routes على عنصر واحد لكل مسار تعرضه واجهة برمجة التطبيقات. يمكن أن تحتوي المصفوفة على خمسة عناصر كحد أقصى: المسار التلقائي والمسار الصديق للبيئة وما يصل إلى ثلاثة مسارات بديلة.

  • ‫geocodingResults، مصفوفة من العناصر من النوع GeocodingResults. لكل موقع جغرافي في الطلب (نقطة الانطلاق أو الوجهة أو نقطة على المسار متوسطة) حدّدته على أنّه سلسلة عنوان أو رمز Plus Code، تُجري واجهة برمجة التطبيقات عملية بحث عن رقم تعريف المكان. يحتوي كل عنصر في هذه المصفوفة على رقم تعريف المكان المقابل لموقع جغرافي. لا يتم تضمين المواقع الجغرافية في الطلب المحدّد على أنّها رقم تعريف مكان أو إحداثيات خطوط العرض/الطول. إذا حدّدت جميع المواقع الجغرافية باستخدام أرقام تعريف الأماكن أو إحداثيات خطوط العرض والطول، لن يتم توفير هذه المصفوفة.

  • ‫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 Code، تحاول واجهة برمجة التطبيقات العثور على الموقع الجغرافي الأكثر صلة الذي يتضمّن رقم تعريف مكان مطابقًا. يحتوي كل عنصر في مصفوفة 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" والوحدات المترية تلقائيًا.