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

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

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

  • الخطوط المتعددة المراعيَة لحركة المرور، التي تحتوي على معلومات عن أحوال حركة المرور على طول المسار يتم التعبير عن أحوال حركة المرور من حيث فئات السرعة (NORMAL وSLOW وTRAFFIC_JAM) السارية على فاصل زمني معيّن من الخط المتعدّد. يتم تحصيل رسوم طلبات الخطوط المتعددة المراعية للزحام وفقًا لسعر Routes Preferred. مزيد من المعلومات عن الفوترة لواجهة برمجة التطبيقات 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.

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

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'

ضبط جودة Polyline

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

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