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

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

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

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

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

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

• ضبط الجودة مقابل وقت الاستجابة للحصول على معلومات حول ضبط جودة الخط المتعدد
• يصف تنسيق خوارزمية Polyline المشفر الخوارزمية لترميز خط متعدد.

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

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

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

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

Android

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));

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

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;

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