تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

ملاحظة: يتم ترميز الرموز الخاصة في الخطوط المتعددة التي تعرضها واجهة برمجة التطبيقات REST API باستخدام ترميز JSON. لعرض هذه الخطوط المتعددة في أداة الترميز المتعدد الخطوط التفاعلية، عليك أولاً عدم تخطيها. تتوفّر العديد من الأدوات المساعدة لتنفيذ عملية إزالة ترميز JSON، مثل Freeformatter.

طلب خط متعدّد الأضلاع أساسي لمسار أو رحلة أو خطوة

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

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

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

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

ضبط جودة 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 وفقًا للممارسات المتعلّقة بالنموذج الأوّلي 3.

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

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

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

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

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

مثال على عرض Polyline

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