درخواست چند خط مسیر

روش computeRoutes (REST) ​​و روش ComputeRoutes (gRPC) هر دو مسیری را که توسط یک چند خط نشان داده شده است به عنوان بخشی از پاسخ برمی‌گردانند. این API ها دو نوع پلی لاین را برمی گرداند:

  • چند خط اصلی (پیش‌فرض) ، یک مسیر را نشان می‌دهد اما بدون اطلاعات ترافیکی که در چند خط تعبیه شده است. درخواست‌هایی که یک پلی لاین پایه را برمی‌گردانند با نرخ Routes Basic صورت‌حساب می‌شوند. درباره صورتحساب برای Routes API بیشتر بیاموزید .

  • چند خط آگاه از ترافیک ، حاوی اطلاعاتی در مورد شرایط ترافیکی در طول مسیر است. شرایط ترافیک بر حسب دسته‌های سرعت ( NORMAL ، SLOW ، TRAFFIC_JAM ) قابل اعمال در یک بازه معین از چند خط بیان می‌شود. درخواست‌های پلی‌لاین‌های آگاه از ترافیک با نرخ ترجیحی مسیرها صورت‌حساب می‌شوند. درباره صورتحساب برای Routes API بیشتر بیاموزید . برای جزئیات، به پیکربندی کیفیت چند خط مراجعه کنید

برای اطلاعات بیشتر در مورد چند خط، نگاه کنید به:

  • اطلاعات مفهومی در Polylines

  • Interactive Polyline Encoder Utility به شما امکان می دهد چند خطوط کدگذاری شده را در یک رابط کاربری ایجاد کنید یا چند خطوط را برای نمایش روی نقشه رمزگشایی کنید. به عنوان مثال، از این ابزار برای رمزگشایی چند خط ایجاد شده توسط کد زیر استفاده کنید.

برای یک مسیر، پا یا پله، یک پلی لاین اساسی درخواست کنید

یک چند خط با یک شی Polyline (REST) ​​یا Polyline (gRPC) نشان داده می شود. شما می توانید یک چند خط در پاسخ در سطح مسیر، پا و پله برگردانید.

با استفاده از ماسک فیلد پاسخ، مشخص کنید که کدام چند خط برگردانده شود:

  • در سطح مسیر ، با قرار دادن routes.polyline در ماسک فیلد پاسخ، یک polyline را در پاسخ برگردانید.

  • در سطح پا ، با درج routes.legs.polyline ، یک 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'

کیفیت 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 مطابق با روش های proto3 مطابقت دارد.

مقادیر startPolylinePointIndex و endPolylinePointIndex همیشه پشت سر هم نیستند. به عنوان مثال:

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

در این مورد شرایط ترافیکی از شاخص 2 تا شاخص 4 یکسان بود.

چند خطوط آگاه از ترافیک را با Maps SDK ارائه دهید

توصیه می‌کنیم چند خطوط آگاه از ترافیک را با استفاده از ویژگی‌های مختلف ارائه شده توسط Google Maps SDK از جمله رنگ‌آمیزی سفارشی، سکته‌ها و الگوها در امتداد خطوط چند خطی نمایش دهید. برای جزئیات بیشتر در مورد استفاده از پلی لاین، به ویژگی‌های Polyline برای Android و ویژگی‌های Polyline برای iOS مراجعه کنید.

رندر چند خطی مثال

کاربران Maps SDK این فرصت را دارند که یک منطق نگاشت سفارشی شده را بین دسته های سرعت و طرحواره های رندر چند خطی تعریف کنند. به عنوان مثال، ممکن است تصمیم بگیرید که سرعت "NORMAL" را به صورت یک خط آبی ضخیم روی نقشه نمایش دهید در حالی که سرعت "Slow" ممکن است به عنوان یک خط نارنجی ضخیم نمایش داده شود.

تکه‌های زیر یک چند خط آبی ضخیم با بخش‌های ژئودزیکی از ملبورن تا پرث اضافه می‌کنند. برای اطلاعات بیشتر، به سفارشی کردن ظاهر (برای اندروید) و سفارشی کردن Polyline (برای iOS) مراجعه کنید.

اندروید

جاوا 

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

هدف-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;

سویفت

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