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

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

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

برای اطلاعات بیشتر درباره چندخطی‌ها، به این مقاله مراجعه کنید:

  • اطلاعات مفهومی درباره چندخطی‌ها

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

درخواست چندخطی پایه برای مسیر، بخش، یا مرحله

چندخطی با شیء 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 ترافیک بین نقاط چندخطی ۲ و ۴ را نشان می‌دهد:

{
  "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، و دسته سرعت مربوطه توصیف می‌شود. توجه داشته باشید که عدم وجود نمایه شروع در بازه با نمایه ۰ مطابق با روال‌های proto3 مطابقت دارد.

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

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

در این مورد، وضعیت ترافیک از نمایه ۲ تا نمایه ۴ یکسان بود.

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

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

نمونه پرداز کردن چندخطی

کاربران «کیت توسعه نرم‌افزار Maps» این فرصت را دارند که منطق نگاشت سفارشی بین دسته‌های سرعت و طرحواره‌های پردازش چندخطی تعریف کنند. به‌عنوان مثال، ممکن است تصمیم گرفته شود که سرعت «عادی» به‌عنوان یک خط آبی ضخیم روی نقشه نمایش داده شود، درحالی‌که سرعت «آهسته» ممکن است به‌عنوان یک خط نارنجی ضخیم نمایش داده شود.

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

Android

جاوا

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

آبجکتیو-سی

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

استفاده از چندخطی‌های کدبندی‌شده با «جستجو در طول مسیر»

از «جستجوی نوشتاری» (جدید) در «میانای برنامه‌سازی کاربردی مکان‌ها» (جدید) برای جستجو درطول مسیر محاسبه‌شده استفاده کنید. چندخطی کدبندی‌شده مسیر ازپیش محاسبه‌شده را از Routes API Compute Routes به درخواست «جستجوی نوشتاری» (جدید) ارسال می‌کنید. پاسخ سپس شامل مکان‌هایی می‌شود که با معیارهای جستجو مطابقت دارند و همچنین در نزدیکی مسیر مشخص‌شده قرار دارند. برای جزئیات، به جستجو درطول مسیر مراجعه کنید.

برای مثال، برای برگرداندن کافه‌هایی درطول مسیر بین مبدأ و مقصد:

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();