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

رمزگذاری Polyline یک الگوریتم فشرده سازی با تلفات است که به شما امکان می دهد مجموعه ای از مختصات مانند یک مسیر را به عنوان یک رشته ذخیره کنید. فرآیند رمزگذاری یک مقدار باینری را با استفاده از طرح رمزگذاری base64 به یک سری کد کاراکتر برای کاراکترهای ASCII تبدیل می کند. برای توضیح کامل فرآیند رمزگذاری، قالب الگوریتم چند خط کدگذاری شده را ببینید.

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

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

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

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

  • پیکربندی کیفیت در مقابل تأخیر برای اطلاعات مربوط به پیکربندی کیفیت چند خط.
  • قالب الگوریتم چند خط رمزگذاری شده، الگوریتمی را برای رمزگذاری چند خط توصیف می کند.

  • 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"
      }
    }
  ]
}

نوع کدگذاری چند خطی را پیکربندی کنید

از گزینه درخواست 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 یکسان بود.

چند خطوط آگاه از ترافیک را با 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