طلب الخطوط المتعددة للمسارات

الترميز المتعدد الخطوط هو خوارزمية ضغط مع فقدان البيانات تتيح لك تخزين سلسلة من الإحداثيات، مثل مسار، كسلسلة واحدة. تحوِّل عملية الترميز قيمة ثنائية إلى سلسلة من رموز الأحرف لأحرف ASCII باستخدام مخطط ترميز base64. للحصول على وصف كامل لعملية الترميز، يُرجى الاطّلاع على تنسيق خوارزمية الخطوط المتعددة المشفّرة.

تعرض طريقة computeRoutes (REST) والطريقة ComputeRoutes (gRPC) المسار الذي يمثله خط متعدد كجزء من الاستجابة. تعرض واجهات برمجة التطبيقات هذه نوعين من الخطوط المتعددة:

  • يمثل الخط المتعدّد الأساسي (تلقائي) مسارًا ولكن بدون معلومات حركة المرور المضمّنة في الخط المتعدد. تتم فوترة الطلبات التي تعرض خطوطًا متعددة أساسية مقابل سعر المسارات الأساسية. مزيد من المعلومات حول الفوترة لواجهة برمجة تطبيقات Routes.

  • الخطوط المتعددة الواعية لحركة المرور تحتوي على معلومات حول أحوال حركة المرور على طول المسار. يتم التعبير عن ظروف حركة المرور من خلال فئات السرعة (NORMAL، SLOW، TRAFFIC_JAM) السارية على فترة زمنية محددة للخط المتعدد. وتتم فوترة طلبات الخطوط المتعددة مدركة لحركة المرور وفقًا لسعر المسار المفضّل. مزيد من المعلومات حول الفوترة لواجهة برمجة تطبيقات Routes لمعرفة التفاصيل، يُرجى الاطّلاع على ضبط جودة الخطوط المتعددة.

لمزيد من المعلومات عن الخطوط المتعددة، راجع:

طلب خط متعدد أساسي لمسار أو ساق أو خطوة

يتم تمثيل الخط المتعدد بكائن الخطوط المتعددة (REST) أو الخط المتعدد (gRPC). يمكنك عرض خط متعدد في الاستجابة على مستوى المسار والساق والخطوة.

حدِّد الخط المتعدد الذي تريد عرضه باستخدام قناع حقل الاستجابة:

  • على مستوى المسار، يمكنك عرض خط متعدد في الاستجابة من خلال تضمين routes.polyline في قناع حقل الاستجابة.

  • على مستوى الساق، يمكنك عرض خط متعدد في استجابة كل مرحلة من المسار من خلال تضمين routes.legs.polyline.

  • على مستوى الخطوة، عليك عرض خط متعدد في الاستجابة لكل خطوة في الساق من خلال تضمين routes.legs.steps.polyline.

على سبيل المثال، لعرض خط متعدد للمسار بالكامل ولكل ساق ولكل خطوة في كل ساق:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

يعرض هذا الطلب الاستجابة التالية التي تتضمن الخطوط المتعددة للمسار، ولكل مرحلة من المسار، ولكل خطوة من الساق:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
              "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
          }
        },
          "steps": [
              {
                  "polyline": {
                      "encodedPolyline": "kclcF...@sC@YIOKI"
                  }
              },
              {
                  "polyline": {
                      "encodedPolyline": "wblcF~...SZSF_@?"
                  }
              },
              ...
      ],
      "distanceMeters": 56901,
      "duration": "2420s",
      "polyline": {
        "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
      }
    }
  ]
}

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

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

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "intermediates": [
    { "address": "450 Serra Mall, Stanford, CA 94305, USA"},
  ],
  "travelMode": "DRIVE",
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

يعرض هذا الطلب ساقَين، لكل منهما خط متعدد فريد، وخط متعدد للمسار بالكامل:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
            "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "kclcFfqch...YIOKI"
                }
            },
        ...
        },
        {
          "polyline": {
            "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "uypeFbo`jVgJq...PoBiC"
                }
            },
        ...
        }
      ],
      "distanceMeters": 68403,
      "duration": "3759s",
      "polyline": {
          "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE"
      }
    }
  ]
}

إعداد نوع الترميز المتعدد الخطوط

استخدِم خيار الطلب polylineEncoding للتحكّم في نوع الخطوط المتعددة. تحدّد السمة polylineEncoding كيفية ترميز الخط المتعدد إما على الشكل ENCODED_POLYLINE (الخيار التلقائي)، أي استخدام خوارزمية الترميز المتعدد الخطوط أو GEO_JSON_LINESTRING، أي استخدام تنسيق GeoJSON LineString.

على سبيل المثال، في نص الطلب:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "polylineEncoding": "ENCODED_POLYLINE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

طلب خطوط متعدّدة مدركة للزيارات

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

تحتوي الخطوط المتعددة الواعية لحركة المرور على معلومات حول أحوال حركة المرور على طول الطريق. يتم التعبير عن ظروف حركة المرور من خلال فئات السرعة (NORMAL، SLOW، TRAFFIC_JAM) لفترة زمنية محددة من الخطوط المتعددة للاستجابة. ويتم تحديد الفواصل الزمنية من خلال فهارس لنقاط البداية (الشاملة) والنهاية (حصرية).

على سبيل المثال، توضِّح الاستجابة التالية عدد زيارات NORMAL بين نقطتَي الخطوط المتعددة 2 و4:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

لتقديم طلب لحساب خطوط متعدّدة مدركة للزيارات، اضبط الخصائص التالية في الطلب:

  • اضبط حقل الصفيف extraComputations على TRAFFIC_ON_POLYLINE لتفعيل حساب عدد الزيارات.

  • اضبط السمة travelMode على DRIVE أو TWO_WHEELER. تعرض طلبات أي وضع سفر آخر خطأ.

  • حدِّد الخيار المفضّل للتوجيه TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL في الطلب. لمزيد من المعلومات، يُرجى الاطّلاع على ضبط الجودة مقابل وقت الاستجابة.

  • يمكنك ضبط قناع حقل الاستجابة الذي يحدِّد عرض خصائص الاستجابة:

    • على مستوى المسار، اعرض جميع معلومات السفر في الرد عن طريق تضمين routes.travelAdvisory في قناع حقل الاستجابة. لعرض معلومات حركة المرور فقط، حدد routes.travelAdvisory.speedReadingIntervals

    • على مستوى الساق، اعرض جميع معلومات السفر في استجابة لكل مرحلة من المسار من خلال تضمين routes.legs.travelAdvisory. لعرض معلومات حركة المرور فقط، حدِّد routes.legs.travelAdvisory.speedReadingIntervals.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "extraComputations": ["TRAFFIC_ON_POLYLINE"],
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

مثال على ردّ لخطوط متعدّدة مدركة للزيارات

في الاستجابة، يتم ترميز بيانات حركة المرور في الخط المتعدد ويتم تضمينها في الحقل travelAdvisory، من النوع كائن RouteLegTravelAdvisory (كل مرحلة) والكائن RouteTravelAdvisory (مسار).

مثال:

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        // Traffic data for the leg.
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      // Traffic data for the route.
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

يتضمّن كل من RouteTravelAdvisory وRouteLegTravelAdvisory حقل صفيف يُسمّى speedReadingIntervals ويحتوي على معلومات عن سرعة حركة المرور. ويتم تمثيل كل كائن في الصفيف من خلال كائن SpeedReadingInterval (REST) أو SpeedReadingInterval (gRPC).

يتضمّن عنصر SpeedReadingInterval قراءة السرعة لفاصل مسار، مثل NORMAL أو SLOW أو TRAFFIC_JAM. تغطي مصفوفة الكائنات الكاملة الخط المتعدد للمسار بدون تداخل. ونقطة البداية لفاصل زمني محدد هي نفسها نقطة نهاية الفاصل السابق.

يتم وصف كل مهلة من خلال startPolylinePointIndex وendPolylinePointIndex وفئة السرعة المقابلة لها. لاحظ أن عدم وجود فهرس البدء ضمن الفاصل يتجاوب مع الفهرس 0 وفقًا لممارسات proto3.

القيمتان startPolylinePointIndex وendPolylinePointIndex ليستا متتاليتين دائمًا. مثال:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

وفي هذه الحالة، كانت ظروف الزيارات هي نفسها من الفهرس 2 إلى الفهرس 4.

عرض الخطوط المتعددة الواعية بحركة المرور باستخدام حزمة تطوير البرامج (SDK) لـ "خرائط Google"

نوصي بعرض الخطوط المتعددة المرصودة لحركة المرور على الخريطة باستخدام الميزات المتنوعة التي تقدمها حزم SDK لخرائط Google، بما في ذلك الألوان والخطوط والأنماط المخصصة على طول امتدادات الخطوط المتعددة. لمزيد من التفاصيل عن استخدام الخطوط المتعددة، راجِع ميزات الخطوط المتعددة لنظام التشغيل Android وميزات الخطوط المتعددة لنظام التشغيل iOS.

مثال على عرض الخطوط المتعددة

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

تضيف المقتطفات التالية خطوطًا زرقاء سميكة بها أجزاء جيوديسية من ملبورن إلى بيرث. لمزيد من المعلومات، يُرجى الاطّلاع على تخصيص أشكال الظهور (لنظام التشغيل Android) وتخصيص الخط المتعدد (لنظام التشغيل iOS).

Android

Java

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Kotlin

val line: Polyline = map.addPolyline(
  PolylineOptions()
    .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
    .width(25f)
    .color(Color.BLUE)
    .geodesic(true)
)

iOS

Objective-C

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.strokeColor = .blue;
polyline.geodesic = YES;
polyline.map = mapView;

Swift

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView