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

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

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

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

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

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

يتم تمثيل الخطوط المتعددة بكائن الخطوط المتعددة (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"
      }
    }
  ]
}

جودة الخطوط المتعددة

ويمكن وصف جودة الخطوط المتعددة بالمصطلحات التالية:

  • دقة النقطة العائمة للنقاط

    يتم تحديد النقاط كقيم لخطوط الطول والعرض، والتي يتم تمثيلها بتنسيق النقطة العائمة أحادية الدقة. هذا يعمل بشكل جيد مع القيم الصغيرة (التي يمكن تمثيلها بدقة)، ولكن تقل الدقة مع زيادة القيم بسبب أخطاء تقريب النقطة العائمة.

    في طريقة 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'

ضبط جودة Poyline

تحدّد السمة 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.

مثال على عرض خطوط متعدّدة

أتيحت لمستخدمي حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط 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