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

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

القيمتان 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