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

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

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

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

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

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

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

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

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

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

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

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

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

Powered by Google, ©YEAR Google

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

Powered by Google, ©2023 Google

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

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

المسار والمرحلة والخطوة

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

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

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

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

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

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

محتوى الرد

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

بالنسبة إلى كل موقع جغرافي في الطلب (المصدر أو الوجهة أو نقطة المرور الوسيطة) تم تحديده كسلسلة عنوان أو رمز 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" ووحدات القياس METRIC.