سرویس ماتریس فاصله

نمای کلی

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

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

شروع به کار

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

برای مشاهده لیست API های فعال خود:

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

قیمت‌گذاری و سیاست‌ها

قیمت‌گذاری

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

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

سیاست‌ها

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

درخواست‌های ماتریس فاصله

دسترسی به سرویس Distance Matrix به صورت غیرهمزمان است، زیرا API نقشه‌های گوگل نیاز به برقراری ارتباط با یک سرور خارجی دارد. به همین دلیل، شما باید یک متد callback ارسال کنید تا پس از تکمیل درخواست، اجرا شود و نتایج را پردازش کند.

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

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 یا اشیاء Place که از آنجا فاصله و زمان محاسبه می‌شود.
• destinations (الزامی) — آرایه‌ای شامل یک یا چند رشته آدرس، اشیاء google.maps.LatLng یا اشیاء Place که فاصله و زمان تا آنها محاسبه می‌شود.
• travelMode ( اختیاری ) — روش حمل و نقل مورد استفاده هنگام محاسبه مسیرها. به بخش روش‌های سفر مراجعه کنید.
• transitOptions ( اختیاری ) — گزینه‌هایی که فقط برای درخواست‌هایی اعمال می‌شوند که در آن‌ها travelMode TRANSIT است. مقادیر معتبر در بخش گزینه‌های ترانزیت توضیح داده شده‌اند.
• drivingOptions ( اختیاری ) مقادیری را مشخص می‌کند که فقط برای درخواست‌هایی اعمال می‌شوند که travelMode روی DRIVING است. مقادیر معتبر در بخش Driving Options توضیح داده شده‌اند.
• unitSystem ( اختیاری ) — سیستم واحد مورد استفاده هنگام نمایش فاصله. مقادیر قابل قبول عبارتند از:
  • google.maps.UnitSystem.METRIC (پیش‌فرض)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways ( اختیاری ) — اگر true ، مسیرهای بین مبدا و مقصد محاسبه می‌شوند تا در صورت امکان از بزرگراه‌ها اجتناب شود.
• avoidTolls ( اختیاری ) — اگر true ، مسیرهای بین نقاط، در صورت امکان، با استفاده از مسیرهای بدون عوارض محاسبه می‌شوند.

حالت‌های سفر

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

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

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

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

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

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

شیء TransitOptions به صورت تحت‌اللفظی شامل فیلدهای زیر است:

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

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

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

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

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

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

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

• departureTime ( برای اعتبار شیء drivingOptions به صورت تحت‌اللفظی لازم است ) زمان مطلوب عزیمت را به عنوان یک شیء Date مشخص می‌کند. مقدار باید روی زمان فعلی یا زمانی در آینده تنظیم شود. نمی‌تواند در گذشته باشد. (API تمام تاریخ‌ها را به UTC تبدیل می‌کند تا از مدیریت سازگار در مناطق زمانی اطمینان حاصل شود.) اگر زمان 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 یک شیء 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 از درخواست Distance Matrix است. آدرس‌ها به همان شکلی که توسط geocoder قالب‌بندی شده‌اند، بازگردانده می‌شوند.
• destinationAddresses آرایه‌ای است که شامل مکان‌های ارسالی در فیلد destinations ، در قالبی که توسط geocoder برگردانده می‌شود، می‌باشد.
• 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 : مبلغ کل کرایه، به ارزی که در بالا مشخص شده است.

کدهای وضعیت

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

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

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

• OK - درخواست معتبر است. این وضعیت حتی اگر هیچ مسیری بین هیچ یک از مبداها و مقصدها یافت نشود، قابل بازگشت است. برای اطلاعات وضعیت سطح عنصر، به کدهای وضعیت عنصر مراجعه کنید.
• INVALID_REQUEST — درخواست ارائه شده نامعتبر بود. این اغلب به دلیل عدم وجود فیلدهای الزامی است. لیست فیلدهای پشتیبانی شده در بالا را ببینید.
• MAX_ELEMENTS_EXCEEDED — حاصلضرب مبدا و مقصد از محدودیت هر پرس‌وجو فراتر می‌رود.
• MAX_DIMENSIONS_EXCEEDED — درخواست شما شامل بیش از ۲۵ مبدا یا بیش از ۲۵ مقصد بود.
• OVER_QUERY_LIMIT — درخواست شما در بازه زمانی مجاز، عناصر بسیار زیادی را درخواست کرده است. اگر پس از مدت زمان معقولی دوباره امتحان کنید، درخواست باید موفقیت‌آمیز باشد.
• REQUEST_DENIED — سرویس، استفاده از سرویس Distance Matrix توسط صفحه وب شما را رد کرد.
• 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];
      }
    }
  }
}