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

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

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

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

  • چندخطی آگاه از ترافیک ، حاوی اطلاعاتی در مورد شرایط ترافیک در طول مسیر است. شرایط ترافیک بر اساس دسته‌های سرعت ( NORMAL ، SLOW ، TRAFFIC_JAM ) که در یک بازه مشخص از چندخطی قابل اجرا هستند، بیان می‌شوند. درخواست‌های مربوط به چندخطی‌های آگاه از ترافیک با نرخ ترجیحی مسیرها محاسبه می‌شوند. درباره محاسبه هزینه برای 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 را بین نقاط چندخطی ۲ و ۴ نشان می‌دهد:

{
  "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

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

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

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

قطعه کدهای زیر یک چندخطی آبی ضخیم با بخش‌های ژئودزیک از ملبورن تا پرت اضافه می‌کنند. برای اطلاعات بیشتر، به سفارشی‌سازی ظاهر (برای اندروید) و سفارشی‌سازی چندخطی (برای 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)
)

آی‌او‌اس

هدف-سی 

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

استفاده از پلی‌لاین‌های کدگذاری شده با قابلیت جستجو در امتداد مسیر

برای جستجو در امتداد یک مسیر محاسبه‌شده از Places API Text Search استفاده کنید. شما چندخطی کدگذاری‌شده‌ی یک مسیر از پیش محاسبه‌شده را از Routes API Compute Routes به درخواست Text Search ارسال می‌کنید. سپس پاسخ شامل مکان‌هایی است که با معیارهای جستجو مطابقت دارند و همچنین در نزدیکی مسیر مشخص‌شده قرار دارند. برای جزئیات بیشتر، به search along a route مراجعه کنید.

برای مثال، برای رفت و برگشت به کافه‌های بین مبدا و مقصد:

نود جی اس 

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