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

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

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

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

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

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

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

  • 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" والوحدات METRIC تلقائيًا.