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

نمای کلی

سرویس Distance Matrix گوگل مسافت سفر و مدت زمان سفر را بین مبدا و مقصدهای مختلف با استفاده از حالت معینی از سفر محاسبه می کند.

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

شروع کردن

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

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

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

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

قیمت گذاری

برای اطلاع از سیاست‌های قیمت‌گذاری و استفاده از سرویس ماتریس فاصله جاوا اسکریپت، به Usage and Billing for Distance Matrix API (Legacy) مراجعه کنید.

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

سیاست ها

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

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

دسترسی به سرویس Distance Matrix ناهمزمان است، زیرا Google Maps API نیاز به برقراری تماس با یک سرور خارجی دارد. به همین دلیل، برای پردازش نتایج باید پس از تکمیل درخواست، یک متد بازگشت به تماس را برای اجرا ارسال کنید.

شما از طریق شی سازنده google.maps.DistanceMatrixService به سرویس Distance Matrix در کد خود دسترسی پیدا می کنید. متد DistanceMatrixService.getDistanceMatrix() درخواستی را برای سرویس Distance Matrix آغاز می‌کند و یک شیء 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 از طریق مسیرهای حمل و نقل عمومی، مسیرها را درخواست می کند. این گزینه ممکن است تنها در صورتی مشخص شود که درخواست شامل یک کلید 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 تعیین نشده باشد، تا کنون (یعنی زمان فعلی) پیش‌فرض می‌شود.
• 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 بازگشتی_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 را برمی گرداند. اینها به تابع callback که در درخواست مشخص کرده اید ارسال می شوند.

شی 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 درخواست ماتریس فاصله ارسال می‌شوند. آدرس ها همانطور که توسط 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 - درخواست شما حاوی بیش از 25 مبدا یا بیش از 25 مقصد بود.
• 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];
      }
    }
  }
}