Distance Matrix Service (Legacy)

نمای کلی

سرویس «ماتریس فاصله» Google مسافت سفر و مدت سفر را بین چند مبدأ و مقصد بااستفاده از حالت سفر ارائه‌شده محاسبه می‌کند.

این سرویس اطلاعات دقیق مسیر را برنمی‌گرداند. اطلاعات مسیر، ازجمله چندخطی‌ها و مسیرهای متنی، را می‌توان با ارسال مبدأ و مقصد تکی موردنظر به سرویس مسیرها به‌دست آورد.

درحال شروع کردن

قبل‌از استفاده از سرویس Distance Matrix در Maps JavaScript API، ابتدا مطمئن شوید که Distance Matrix API (Legacy) در کنسول Google Cloud، در همان پروژه‌ای که برای Maps JavaScript API راه‌اندازی کرده‌اید، فعال باشد.

برای مشاهده فهرست میاناهای برنامه‌سازی کاربردی فعال‌شده:

1. به کنسول Google Cloud بروید.
2. روی دکمه انتخاب پروژه کلیک کنید، سپس همان پروژه‌ای را که برای Maps JavaScript API راه‌اندازی کرده‌اید انتخاب کنید و روی باز کردن کلیک کنید.
3. از فهرست میاناهای برنامه‌سازی کاربردی در داشبورد، Distance Matrix API (Legacy) را پیدا کنید.
4. اگر API را در فهرست می‌بینید، همه تنظیمات انجام شده است. اگر میانای برنامه‌سازی کاربردی در فهرست نیست، آن را در https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com فعال کنید

قیمت‌گذاری و خط‌مشی‌ها

قیمت‌گذاری

برای آشنایی با خط‌مشی‌های قیمت‌گذاری و استفاده برای سرویس Distance Matrix جاوا اسکریپت، به استفاده و صورت‌حساب برای Distance Matrix API (قدیمی) مراجعه کنید.

توجه: هر پُرسمانی که به سرویس «ماتریس فاصله» ارسال می‌شود، براساس تعداد عناصر مجاز محدود می‌شود، که تعداد مبدأها ضرب در تعداد مقصدها تعداد عناصر را تعریف می‌کند.

خط‌مشی‌ها

استفاده از سرویس Distance Matrix باید مطابق با خط‌مشی‌های شرح‌داده‌شده برای Distance Matrix API (قدیمی) باشد.

درخواست‌های Distance Matrix

دسترسی به سرویس «ماتریس فاصله» ناهمگام است، زیرا Google Maps API باید با سرور خارجی تماس برقرار کند. به همین دلیل، باید یک روش فراخوانی را برای اجرا پس‌از تکمیل درخواست ارسال کنید تا نتایج پردازش شود.

شما ازطریق شیء سازنده google.maps.DistanceMatrixService در کدتان به سرویس Distance Matrix دسترسی پیدا می‌کنید. روش DistanceMatrixService.getDistanceMatrix() درخواستی را به سرویس «ماتریس فاصله» آغاز می‌کند و یک راستین‌نماد شیء DistanceMatrixRequest حاوی مبدأها، مقصدها، و حالت سفر، و همچنین یک روش فراخوانی برای اجرا پس‌از دریافت پاسخ را به آن ارسال می‌کند.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

مشاهده نمونه

DistanceMatrixRequest شامل فیلدهای زیر است:

• origins (الزامی) — آرایه‌ای حاوی یک یا چند رشته نشانی، شیء google.maps.LatLng، یا شیء مکان که فاصله و زمان از آن‌ها محاسبه می‌شود.
• destinations (الزامی) — آرایه‌ای حاوی یک یا چند رشته نشانی، اشیاء google.maps.LatLng، یا اشیاء مکان که فاصله و زمان تا آن‌ها محاسبه می‌شود.
• ‫travelMode (اختیاری) — حالت حمل‌ونقل برای استفاده هنگام محاسبه مسیرها. بخش مربوط به حالت‌های سفر را ببینید.
• transitOptions (اختیاری) — گزینه‌هایی که فقط برای درخواست‌هایی اعمال می‌شود که travelMode TRANSIT است. مقادیر معتبر در بخش مربوط به گزینه‌های حمل‌ونقل عمومی شرح داده شده است.
• drivingOptions (اختیاری) مقادیری را مشخص می‌کند که فقط برای درخواست‌هایی اعمال می‌شود که travelMode در آن‌ها DRIVING است. مقادیر معتبر در بخش گزینه‌های رانندگی شرح داده شده است.
• ‫unitSystem (اختیاری) — سیستم واحدی که باید هنگام نمایش فاصله استفاده شود. مقادیر پذیرفتنی عبارت‌اند از:
  • google.maps.UnitSystem.METRIC (پیش‌فرض)
  • google.maps.UnitSystem.IMPERIAL
• ‫avoidHighways (اختیاری) — اگر true، مسیرهای بین مبدأ و مقصد به‌گونه‌ای محاسبه خواهد شد که تا حد امکان از بزرگراه‌ها اجتناب شود.
• ‫avoidTolls (اختیاری) — اگر true، مسیرهای بین نقاط بااستفاده از مسیرهای بدون عوارض محاسبه خواهد شد، هرجا که ممکن باشد.

حالت‌های سفر

هنگام محاسبه زمان و مسافت، می‌توانید مشخص کنید از کدام وسیله حمل‌ونقل استفاده شود. درحال‌حاضر از حالت‌های سفر زیر پشتیبانی می‌شود:

• BICYCLING درخواست مسیرهای دوچرخه‌سواری ازطریق مسیرهای دوچرخه و خیابان‌های ترجیحی (درحال‌حاضر فقط در ایالات متحده و برخی شهرهای کانادا دردسترس است).
• DRIVING (پیش‌فرض) نشان‌دهنده مسیرهای رانندگی استاندارد بااستفاده از شبکه جاده‌ای است.
• TRANSIT درخواست مسیر ازطریق مسیرهای حمل‌ونقل عمومی می‌کند. این گزینه فقط درصورتی می‌تواند مشخص شود که درخواست حاوی کلید میانای برنامه‌سازی کاربردی باشد. برای گزینه‌های دردسترس در این نوع درخواست، بخش مربوط به گزینه‌های حمل‌ونقل عمومی را ببینید.
• WALKING مسیرهای پیاده‌روی را ازطریق مسیرهای عابر پیاده و پیاده‌روها (درصورت وجود) درخواست می‌کند.

گزینه‌های حمل‌ونقل عمومی

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

گزینه‌های دردسترس برای درخواست ماتریس فاصله در حالت‌های سفر مختلف متفاوت است. در درخواست‌های حمل‌ونقل عمومی، گزینه‌های avoidHighways و avoidTolls نادیده گرفته می‌شوند. می‌توانید گزینه‌های مسیریابی مختص حمل‌ونقل عمومی را ازطریق راستین‌نماد شیء TransitOptions مشخص کنید.

درخواست‌های حمل‌ونقل عمومی به زمان حساس هستند. محاسبات فقط برای زمان‌های آینده برگردانده خواهد شد.

راستین‌نماد شیء TransitOptions شامل فیلدهای زیر است:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

این فیلدها در زیر توضیح داده شده‌اند:

• arrivalTime (اختیاری) زمان ورود موردنظر را به‌عنوان شیء Date مشخص می‌کند. اگر زمان رسیدن مشخص شده باشد، زمان حرکت نادیده گرفته می‌شود.
• departureTime (اختیاری) زمان حرکت موردنظر را به‌عنوان شیء Date مشخص می‌کند. اگر arrivalTime مشخص شده باشد، departureTime نادیده گرفته خواهد شد. اگر مقداری برای departureTime یا arrivalTime مشخص نشده باشد، به‌طور پیش‌فرض روی «اکنون» (یعنی زمان فعلی) تنظیم می‌شود.
• ‫modes (اختیاری) آرایه‌ای است که حاوی یک یا چند راستین‌نماد شیء TransitMode است. این فیلد فقط درصورتی می‌تواند گنجانده شود که درخواست حاوی کلید میانای برنامه‌سازی کاربردی باشد. هر TransitMode حالت ترجیحی حمل‌ونقل عمومی را مشخص می‌کند. مقادیر زیر مجاز هستند:
  • BUS نشان می‌دهد که مسیر محاسبه‌شده باید سفر با اتوبوس را ترجیح دهد.
  • RAIL نشان می‌دهد که مسیر محاسبه‌شده باید سفر با قطار، تراموا، قطار شهری، و مترو را ترجیح دهد.
  • SUBWAY نشان می‌دهد که مسیر محاسبه‌شده باید سفر با مترو را ترجیح دهد.
  • TRAIN نشان می‌دهد که مسیر محاسبه‌شده باید سفر با قطار را ترجیح دهد.
  • TRAM نشان می‌دهد که مسیر محاسبه‌شده باید سفر با تراموا و قطار شهری را ترجیح دهد.
• ‫routingPreference (اختیاری) اولویت‌ها را برای مسیرهای حمل‌ونقل عمومی مشخص می‌کند. بااستفاده از این گزینه، می‌توانید گزینه‌های برگردانده‌شده را سوگیری کنید، به‌جای اینکه بهترین مسیر پیش‌فرض انتخاب‌شده توسط API را بپذیرید. این فیلد فقط درصورتی می‌تواند مشخص شود که درخواست حاوی کلید میانای برنامه‌سازی کاربردی باشد. مقادیر زیر مجاز هستند:
  • FEWER_TRANSFERS نشان می‌دهد که مسیر محاسبه‌شده باید تعداد محدودی تعویض وسیله داشته باشد.
  • LESS_WALKING نشان می‌دهد که مسیر محاسبه‌شده باید مقدار محدودی پیاده‌روی داشته باشد.

گزینه‌های رانندگی

از شیء drivingOptions برای مشخص کردن زمان حرکت استفاده کنید تا بهترین مسیر به مقصدتان با درنظر گرفتن شرایط ترافیک موردانتظار محاسبه شود. همچنین می‌توانید مشخص کنید که می‌خواهید زمان تخمینی در ترافیک بدبینانه، خوش‌بینانه، یا بهترین تخمین براساس شرایط ترافیک گذشته و ترافیک زنده باشد.

شیء drivingOptions حاوی فیلدهای زیر است:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

این فیلدها در زیر توضیح داده شده‌اند:

• departureTime (برای معتبر بودن راستین‌نماد شیء drivingOptions الزامی است) زمان حرکت موردنظر را به‌عنوان شیء Date مشخص می‌کند. مقدار باید روی زمان فعلی یا زمانی در آینده تنظیم شود. نمی‌تواند در گذشته باشد. (میانای برنامه‌سازی کاربردی همه تاریخ‌ها را به ساعت هماهنگ جهانی تبدیل می‌کند تا از مدیریت یکسان در مناطق زمانی مختلف مطمئن شود.) اگر departureTime را در درخواست بگنجانید، API بهترین مسیر را با توجه به شرایط ترافیکی موردانتظار در آن زمان برمی‌گرداند و زمان پیش‌بینی‌شده در ترافیک (duration_in_traffic) را در پاسخ لحاظ می‌کند. اگر زمان حرکت را مشخص نکنید (یعنی اگر درخواست شامل drivingOptions نباشد)، مسیر برگردانده‌شده معمولاً مسیر خوبی است که شرایط ترافیک در آن درنظر گرفته نشده است.
• ‫trafficModel (اختیاری) فرضیاتی را که باید هنگام محاسبه زمان در ترافیک استفاده شود مشخص می‌کند. این تنظیم بر مقدار برگردانده‌شده در فیلد duration_in_traffic در پاسخ تأثیر می‌گذارد، که حاوی زمان پیش‌بینی‌شده در ترافیک براساس میانگین‌های سابقه است. پیش‌فرض‌ها به best_guess. مقادیر زیر مجاز هستند:
  • bestguess (پیش‌فرض) نشان می‌دهد که duration_in_traffic برگردانده‌شده باید بهترین تخمین از مدت سفر بااستفاده از اطلاعات موجود درباره شرایط ترافیک گذشته و ترافیک زنده باشد. هرچه departureTime به زمان فعلی نزدیک‌تر باشد، ترافیک زنده اهمیت بیشتری پیدا می‌کند.
  • pessimistic نشان می‌دهد که duration_in_traffic برگردانده‌شده باید در اکثر روزها طولانی‌تر از مدت سفر واقعی باشد، اگرچه در برخی روزها با شرایط ترافیکی بسیار بد ممکن است از این مقدار فراتر رود.
  • optimistic نشان می‌دهد که duration_in_traffic برگردانده‌شده باید در اکثر روزها کوتاه‌تر از مدت سفر واقعی باشد، هرچند در روزهایی که شرایط ترافیک به‌طور خاص خوب است، ممکن است سریع‌تر از این مقدار باشد.

در زیر نمونه‌ای از DistanceMatrixRequest برای مسیرهای رانندگی، شامل زمان حرکت و مدل ترافیک آورده شده است:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

پاسخ‌های Distance Matrix

فراخوانی موفقیت‌آمیز به سرویس Distance Matrix یک شیء DistanceMatrixResponse و یک شیء DistanceMatrixStatus برمی‌گرداند. این موارد به تابع فراخوانی متقابل که در درخواست مشخص کرده‌اید منتقل می‌شوند.

شیء DistanceMatrixResponse حاوی اطلاعات مسافت و مدت‌زمان برای هر جفت مبدأ/مقصد است که می‌توان برای آن مسیر محاسبه کرد.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

نتایج ماتریس فاصله

فیلدهای پشتیبانی‌شده در پاسخ در زیر توضیح داده شده است.

• originAddresses آرایه‌ای است که مکان‌های ارسال‌شده در فیلد origins درخواست «ماتریس فاصله» را دربرمی‌گیرد. نشانی‌ها همان‌طور که توسط زمین‌کدیاب قالب‌بندی شده‌اند برگردانده می‌شوند.
• destinationAddresses آرایه‌ای است که حاوی مکان‌های ارسال‌شده در فیلد destinations است، در قالبی که توسط زمین‌کدیاب برگردانده شده است.
• rows آرایه‌ای از اشیای DistanceMatrixResponseRow است که هر ردیف آن با یک مبدأ مطابقت دارد.
• elements فرزندان rows هستند و با جفت شدن مبدأ ردیف با هر مقصد مطابقت دارند. این عناصر حاوی اطلاعات وضعیت، مدت، فاصله، و کرایه (درصورت وجود) برای هر جفت مبدأ/مقصد هستند.
• هر element شامل فیلدهای زیر است:
  • status: برای مشاهده فهرست کدهای وضعیت احتمالی، کدهای وضعیت را ببینید.
  • duration: مدت زمانی که طول می‌کشد تا این مسیر طی شود، به ثانیه (فیلد value) و به‌صورت text بیان می‌شود. مقدار متنی طبق unitSystem مشخص‌شده در درخواست قالب‌بندی می‌شود (یا در سنجه، اگر هیچ اولویت‌بندی‌ای ارائه نشده باشد).
  • duration_in_traffic: مدت زمانی که طول می‌کشد تا این مسیر را با درنظر گرفتن شرایط ترافیک فعلی طی کنید، به ثانیه (فیلد value) و به‌صورت text بیان می‌شود. مقدار متنی طبق unitSystem مشخص‌شده در درخواست قالب‌بندی می‌شود (یا در سنجه، اگر هیچ اولویت‌بندی‌ای ارائه نشده باشد). ‫ duration_in_traffic فقط زمانی برگردانده می‌شود که داده‌های ترافیک دردسترس باشد، mode روی driving تنظیم شده باشد، و departureTime به‌عنوان بخشی از فیلد distanceMatrixOptions در درخواست گنجانده شده باشد.
  • distance: مسافت کل این مسیر، بیان‌شده به متر (value) و به‌صورت text. مقدار متنی براساس unitSystem مشخص‌شده در درخواست قالب‌بندی می‌شود (یا در سنجه، اگر اولویتی ارائه نشده باشد).
  • fare: حاوی کل کرایه (یعنی کل هزینه بلیت) در این مسیر است. این ویژگی فقط برای درخواست‌های حمل‌ونقل عمومی و فقط برای ارائه‌دهندگان حمل‌ونقل عمومی که اطلاعات کرایه برای آن‌ها دردسترس است برگردانده می‌شود. این اطلاعات شامل موارد زیر است:
    • currency: کد ارز ISO 4217 که نشان‌دهنده ارزی است که مبلغ به آن بیان شده است.
    • value: مبلغ کل کرایه، به واحد پولی که در بالا مشخص شده است.

رمزهای وضعیت

پاسخ Distance Matrix شامل یک کد وضعیت برای پاسخ به‌صورت کلی و همچنین یک وضعیت برای هر عنصر است.

کدهای وضعیت پاسخ

کدهای وضعیتی که برای DistanceMatrixResponse اعمال می‌شوند در شیء DistanceMatrixStatus ارسال می‌شوند و شامل موارد زیر هستند:

• OK — درخواست معتبر است. این وضعیت می‌تواند برگردانده شود حتی اگر هیچ مسیری بین هیچ‌یک از مبدأها و مقصدها پیدا نشده باشد. برای اطلاعات وضعیت سطح عنصر، کدهای وضعیت عنصر را ببینید.
• INVALID_REQUEST — درخواست ارائه‌شده نامعتبر بود. این مشکل اغلب به‌دلیل تکمیل نشدن فیلدهای الزامی است. فهرست فیلدهای پشتیبانی‌شده را در بالا ببینید.
• MAX_ELEMENTS_EXCEEDED — حاصل‌ضرب مبدأها و مقصدها از حد مجاز هر پُرسمان فراتر می‌رود.
• MAX_DIMENSIONS_EXCEEDED — درخواست شما حاوی بیش‌از ۲۵ مبدأ یا بیش‌از ۲۵ مقصد بود.
• OVER_QUERY_LIMIT — برنامه شما در بازه زمانی مجاز، عناصر بسیار زیادی درخواست کرده است. اگر پس‌از مدت زمان معقولی دوباره امتحان کنید، درخواست باید موفقیت‌آمیز باشد.
• REQUEST_DENIED — این سرویس استفاده از سرویس «ماتریس فاصله» را توسط صفحه وب شما رد کرد.
• UNKNOWN_ERROR — درخواست «ماتریس فاصله» به‌دلیل خطای سرور پردازش نشد. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد.

کدهای وضعیت عنصر

کدهای وضعیت زیر برای اشیاء خاص DistanceMatrixElement اعمال می‌شود:

• NOT_FOUND — مبدأ و/یا مقصد این جفت‌سازی زمین‌کدیابی نشد.
• OK — پاسخ حاوی نتیجه معتبری است.
• ZERO_RESULTS — هیچ مسیری بین مبدأ و مقصد پیدا نشد.

درحال تجزیه کردن نتایج

شیء DistanceMatrixResponse حاوی یک row برای هر مبدأ است که در درخواست ارسال شده است. هر ردیف حاوی فیلد element برای هر جفت‌سازی آن مبدأ با مقصد(های) ارائه‌شده است.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}