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

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

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

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

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

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

يتم تمثيل الخطوط المتعددة بكائن Polyline (REST) أو Polyline (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"
      }
    }
  ]
}

جودة الخطوط المتعددة

ويمكن توضيح جودة الخطوط المتعددة بالعبارات التالية:

  • دقة النقطة العائمة للنقاط

    يتم تحديد النقاط كقيم لخطوط الطول والعرض، ويتم تمثيلها بتنسيق نقطة عائمة أحادية الدقة. يعمل هذا بشكل جيد مع القيم الصغيرة (التي يمكن تمثيلها بدقة)، لكن الدقة تقل مع زيادة القيم بسبب أخطاء تقريب النقطة العائمة.

    في طريقة computeRoutes (REST) وComputeRoutes، يتم التحكّم في ذلك من خلال polylineEncoding.

  • عدد النقاط التي يتكوّن منها الخط المتعدد

    كلما زاد عدد النقاط، كان الخطوط المتعددة أكثر سلاسة (خاصة في المنحنيات).

    في طريقة computeRoutes (REST) وComputeRoutes، يتم التحكّم في ذلك من خلال polylineQuality.

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

يمكنك استخدام خيار طلب 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'

إعداد جودة الخطوط المتعددة

تحدّد السمة polylineQuality جودة الخطوط المتعددة على أنّها HIGH_QUALITY أو OVERVIEW (الخيار التلقائي). في حال استخدام OVERVIEW، يتم إنشاء الخط المتعدد باستخدام عدد صغير من النقاط ويستغرق وقت استجابة طلبه أقل من HIGH_QUALITY.

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

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "polylineQuality": "HIGH_QUALITY",
  "polylineEncoding": "ENCODED_POLYLINE",
  "departureTime": "2023-10-15T15:01:23.045123456Z",
  ...
}

طلب خط متعدد الإدراك لحركة المرور

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

تحتوي الخطوط المتعددة الواعية بحركة المرور على معلومات عن أحوال حركة المرور على طول المسار. يتم التعبير عن ظروف حركة المرور من حيث فئات السرعة (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 للخرائط بفرصة تحديد منطق تعيين مخصص بين فئات السرعة ومخطّطات العرض المتعدد الخطوط. وكمثال على ذلك، يمكن للمرء أن يقرر عرض السرعة "NORMAL" كخط أزرق سميك على الخريطة، فيما قد تظهر السرعة "بطيئة" كخط برتقالي سميك، على سبيل المثال.

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