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

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

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

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

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

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

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

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