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

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

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

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

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

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

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

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

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

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

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

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

Powered by Google, ©YEAR Google

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

Powered by Google, ©2023 Google

حول المسارات والساقَين والخطوات

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

المسار والساق والخطوة.

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

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

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

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

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

  • الخطوة: هي تعليمات واحدة على طول مسار المسار. الخطوة هي الأكثر الوحدة الذرية للمسار. على سبيل المثال، يمكن أن تشير إحدى الخطوات إلى "تشغيل الزر الرئيسي لليسار" Street''.

ماذا يظهر في الردّ

كائن JSON التي تمثّل استجابة واجهة برمجة التطبيقات تتضمّن المواقع الإلكترونية ذات المستوى الأعلى التالية:

  • routes، مصفوفة من العناصر من النوع المسار. تحتوي المصفوفة 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، حيث يكون كل عنصر مصفوفة من النوع المسار. يمثل كل عنصر مصفوفة مسارًا كاملاً من المصدر إلى الوجهة. تشير رسالة الأشكال البيانية تعرض واجهة برمجة التطبيقات دائمًا مسارًا واحدًا على الأقل يسمى المسار التلقائي.

يمكنك طلب مسارات إضافية. إذا طلبت مسارًا صديقًا للبيئة، فيمكن أن تحتوي المصفوفة على عنصرين هما: المسار الافتراضي والمسار الصديق للبيئة. أو ضبط 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 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 ميل".

في ما يلي مثال على ما تراه في القيم المترجَمة:

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

إذا لم تحدّد اللغة أو نظام الوحدة، تستنتج واجهة برمجة التطبيقات اللغة والوحدات على النحو التالي:

  • تستنتج الطريقة ComputeRoutes الموقع الجغرافي والمسافة. من نقطة طريق الأصل. لذلك بالنسبة لطلب التوجيه في الولايات المتحدة، يجب أن تعمل واجهة برمجة التطبيقات تستنتج لغة en-US وIMPERIAL وحدة.
  • يتم ضبط طريقة ComputeRouteMatrix تلقائيًا على اللغة ‎"en-US" والوحدات المترية.