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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

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

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

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

يتم تمثيل الخط المتعدد الأضلاع بواسطة كائن 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.

عرض خطوط متعددة الأضلاع تراعي حركة المرور باستخدام "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google"

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

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

يمكن لمستخدمي Maps 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

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

استخدِم Places API Text Search للبحث على طول مسار محسوب. يمكنك تمرير خط متعدد الأضلاع مشفّر لمسار تم حسابه مسبقًا من واجهة برمجة التطبيقات Compute Routes في Routes API إلى طلب البحث النصي. تحتوي الاستجابة بعد ذلك على أماكن تتطابق مع معايير البحث وتقع أيضًا بالقرب من المسار المحدّد. لمعرفة التفاصيل، يُرجى الاطّلاع على البحث على طول طريق.

على سبيل المثال، لعرض المقاهي على طول المسار بين نقطة الانطلاق والوجهة:

Node.js

const API_KEY = 'YOUR_API_KEY';
const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes';
const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';



function init(){
    const routes_request = {
        "origin":{
            "address": "1600 Amphitheatre Parkway, Mountain View, CA"
        },
        "destination":{
            "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
        },
        "travelMode": "DRIVE"
    };
    const textSearch_request = {
        "textQuery": "cafe",
        "searchAlongRouteParameters": {
            "polyline": {
                "encodedPolyline": ""
            }
        }
    };
    fetchResources(routes_service,routes_request).then(routes => {
        textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline;
        fetchResources(textSearch_service,textSearch_request).then(places => {
            console.log(places);
        });
    });
}
async function fetchResources(resource,reqBody){
    const response = await fetch(resource, {
        method: 'POST',
        body: JSON.stringify(reqBody),
        headers: {
            'Content-Type': 'application/json',
            'X-Goog-Api-Key': API_KEY,
            'X-Goog-FieldMask': '*'
        }
    });
    const responseJSON = await response.json();
    return responseJSON;
}
init();