درخواست و پاسخ Distance Matrix API

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

مقدمه

یک درخواست API مربوط به Distance Matrix به شکل زیر است:

https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

که در آن outputFormat می‌تواند یکی از مقادیر زیر باشد:

  • json (توصیه می‌شود) خروجی را در قالب نشانه‌گذاری شیء جاوا اسکریپت (JSON) نشان می‌دهد.
  • xml خروجی را به صورت XML نشان می‌دهد.

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

پارامترهای مورد نیاز

  • مقاصد

    یک یا چند مکان برای استفاده به عنوان نقطه پایان برای محاسبه مسافت و زمان سفر. گزینه‌های پارامتر destinations مشابه پارامتر origins هستند.

  • خاستگاه‌ها

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

    • شناسه مکان : اگر شناسه مکان ارائه می‌دهید، باید قبل از آن از place_id: استفاده کنید.
    • آدرس : اگر یک آدرس وارد کنید، سرویس رشته را ژئوکد می‌کند و آن را به مختصات عرض/طول جغرافیایی تبدیل می‌کند تا فاصله را محاسبه کند. این مختصات ممکن است با مختصات برگردانده شده توسط API ژئوکدینگ متفاوت باشد، به عنوان مثال ورودی ساختمان به جای مرکز آن.
      توجه: استفاده از شناسه‌های مکان نسبت به استفاده از آدرس‌ها یا مختصات طول و عرض جغرافیایی ارجحیت دارد. استفاده از مختصات همیشه منجر به این می‌شود که نقطه به نزدیکترین جاده به آن مختصات متصل شود - که ممکن است نقطه دسترسی به ملک یا حتی جاده‌ای که به سرعت یا با خیال راحت به مقصد منتهی شود، نباشد. استفاده از آدرس، فاصله تا مرکز ساختمان را ارائه می‌دهد، نه ورودی ساختمان.
    • مختصات : اگر مختصات عرض/طول جغرافیایی را وارد کنید، به نزدیکترین جاده متصل می‌شوند. وارد کردن شناسه مکان ترجیح داده می‌شود. اگر مختصات را وارد می‌کنید، مطمئن شوید که هیچ فاصله‌ای بین مقادیر عرض و طول جغرافیایی وجود ندارد.
    • کدهای پلاس باید به صورت یک کد سراسری یا یک کد مرکب قالب‌بندی شوند. کدهای پلاس را همانطور که در اینجا نشان داده شده است قالب‌بندی کنید (علامت‌های پلاس به صورت %2B و فاصله‌ها به صورت %20 با url-escaped نمایش داده می‌شوند):
      • کد جهانی یک کد منطقه‌ای ۴ کاراکتری و کد محلی ۶ کاراکتری یا بیشتر است ( 849VCWC8+R9 به صورت 849VCWC8%2BR9 کدگذاری می‌شود).
      • کد مرکب، یک کد محلی ۶ کاراکتری یا بیشتر با موقعیت مکانی مشخص است ( CWC8+R9 Mountain View, CA, USA به صورت CWC8%2BR9%20Mountain%20View%20CA%20USA کدگذاری می‌شود).
    • چندخطی کدگذاری‌شده (Encoded Polyline) به عنوان یک روش جایگزین، می‌توانید مجموعه‌ای کدگذاری‌شده از مختصات را با استفاده از الگوریتم چندخطی کدگذاری‌شده ارائه دهید. این روش به ویژه در صورتی مفید است که تعداد زیادی نقطه مبدا داشته باشید، زیرا URL هنگام استفاده از چندخطی کدگذاری‌شده به طور قابل توجهی کوتاه‌تر است.
      • خطوط چندخطی کدگذاری شده باید با enc: و به دنبال آن یک دونقطه : شروع شوند. برای مثال: origins=enc:gfo}EtohhU:
      • همچنین می‌توانید چندین پلی‌لاین کدگذاری شده را که با کاراکتر پایپ | از هم جدا شده‌اند، وارد کنید. برای مثال: 
        origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

پارامترهای اختیاری

  • زمان_ورود

    زمان ترجیحی رسیدن برای مسیرهای حمل و نقل عمومی را بر حسب ثانیه از نیمه شب، ۱ ژانویه ۱۹۷۰ به وقت جهانی مشخص می‌کند. می‌توانید یا departure_time یا arrival_time مشخص کنید، اما نمی‌توانید هر دو را با هم داشته باشید. توجه داشته باشید که arrival_time باید به عنوان یک عدد صحیح مشخص شود.

  • اجتناب از

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

    • tolls نشان می‌دهد که مسیر محاسبه‌شده باید از جاده‌ها/پل‌های دارای عوارض اجتناب کند.
    • highways نشان می‌دهد که مسیر محاسبه‌شده باید از بزرگراه‌ها اجتناب کند.
    • ferries نشان می‌دهد که مسیر محاسبه‌شده باید از عبور کشتی‌ها اجتناب کند.
    • indoor نشان می‌دهد که مسیر محاسبه‌شده باید از پله‌های داخلی برای پیاده‌روی و مسیرهای حمل‌ونقل عمومی اجتناب کند.

    می‌توان با ارسال هر دو محدودیت به پارامتر avoid، مسیری را درخواست کرد که از هرگونه ترکیبی از عوارض، بزرگراه‌ها و کشتی‌ها اجتناب کند. برای مثال avoid=tolls|highways|ferries .

    نکته: اضافه کردن محدودیت‌ها، مسیرهایی را که شامل ویژگی محدود شده هستند، مسدود نمی‌کند؛ بلکه نتیجه را به سمت مسیرهای مطلوب‌تر متمایل می‌کند.

  • زمان_حرکت

    زمان ترجیحی حرکت را مشخص می‌کند. می‌توانید زمان را به صورت یک عدد صحیح بر حسب ثانیه از نیمه‌شب، ۱ ژانویه ۱۹۷۰ به وقت جهانی مشخص کنید. اگر زمان departure_time دیرتر از ۹۹۹۹-۱۲-۳۱T۲۳:۵۹:۵۹.۹۹۹۹۹۹۹۹Z مشخص شود، API departure_time به ۹۹۹۹-۱۲-۳۱T۲۳:۵۹:۵۹.۹۹۹۹۹۹۹۹Z برمی‌گرداند. به طور جایگزین، می‌توانید مقدار now را مشخص کنید که زمان حرکت را به زمان فعلی (دقیق تا نزدیکترین ثانیه) تنظیم می‌کند. زمان حرکت را می‌توان در دو حالت مشخص کرد:

    • برای درخواست‌هایی که حالت سفر آنها ترانزیت است: می‌توانید به صورت اختیاری یکی از departure_time یا arrival_time مشخص کنید. اگر هیچ‌کدام از این دو زمان مشخص نشده باشد، زمان departure_time به صورت پیش‌فرض روی «اکنون» تنظیم می‌شود (یعنی زمان حرکت به صورت پیش‌فرض روی زمان فعلی تنظیم می‌شود).
    • برای درخواست‌هایی که حالت سفر در آنها رانندگی است: می‌توانید زمان departure_time برای دریافت مسیر و مدت زمان سفر (فیلد پاسخ: duration_in_traffic) که شرایط ترافیک را در نظر می‌گیرد، مشخص کنید. زمان departure_time باید روی زمان فعلی یا زمانی در آینده تنظیم شود. نمی‌تواند در گذشته باشد.
    توجه: اگر زمان حرکت مشخص نشده باشد، انتخاب مسیر و مدت زمان بر اساس شبکه جاده‌ای و شرایط ترافیکی متوسط ​​مستقل از زمان انجام می‌شود. نتایج یک درخواست مشخص ممکن است به مرور زمان به دلیل تغییرات در شبکه جاده‌ای، شرایط ترافیکی متوسط ​​به‌روز شده و ماهیت توزیع‌شده سرویس، متفاوت باشد. نتایج همچنین ممکن است بین مسیرهای تقریباً معادل در هر زمان یا فرکانسی متفاوت باشد.
    نکته: درخواست‌های ماتریس فاصله که departure_time مشخص می‌کنند، زمانی که mode=driving ، حداکثر به ۱۰۰ عنصر در هر درخواست محدود می‌شوند. تعداد مبدا ضربدر تعداد مقصدها، تعداد عناصر را مشخص می‌کند.

  • زبان

    زبانی که نتایج با آن برگردانده می‌شوند.

    • فهرست زبان‌های پشتیبانی‌شده را ببینید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
    • اگر language ارائه نشود، API تلاش می‌کند از زبان ترجیحی مشخص شده در سربرگ Accept-Language استفاده کند.
    • این API تمام تلاش خود را می‌کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابانی را به زبان محلی برمی‌گرداند و در صورت لزوم با رعایت زبان ترجیحی، آنها را به اسکریپتی که توسط کاربر قابل خواندن باشد، تبدیل می‌کند. تمام آدرس‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای آدرس همگی به همان زبانی برگردانده می‌شوند که از اولین جزء انتخاب شده است.
    • اگر نامی در زبان مورد نظر موجود نباشد، API از نزدیکترین مورد منطبق استفاده می‌کند.
    • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن انتخاب می‌کند و ترتیب برگرداندن آنها دارد. کدگذار جغرافیایی بسته به زبان، اختصارات را به طور متفاوتی تفسیر می‌کند، مانند اختصارات مربوط به انواع خیابان، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند. به عنوان مثال، utca و tér مترادف خیابان در زبان مجارستانی هستند.

  • حالت

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

    • driving (پیش‌فرض) مسیرهای رانندگی استاندارد یا مسافت را با استفاده از شبکه جاده‌ای نشان می‌دهد.
    • درخواست‌های walking ، مسیر یا مسافت پیاده‌روی را با استفاده از مسیرهای عابر پیاده و پیاده‌روها (در صورت وجود) ارائه می‌دهد.
    • درخواست‌های bicycling مسیر یا مسافت دوچرخه‌سواری را با استفاده از مسیرهای دوچرخه‌سواری و خیابان‌های ترجیحی (در صورت وجود) ارائه می‌دهد.
    • درخواست‌های transit مسیر یا مسافت را با استفاده از مسیرهای حمل و نقل عمومی (در صورت وجود) درخواست می‌کنند. اگر حالت را روی حمل و نقل عمومی تنظیم کنید، می‌توانید به صورت اختیاری زمان departure_time یا arrival_time مشخص کنید. اگر هیچ کدام از این دو زمان مشخص نشده باشند، زمان departure_time به طور پیش‌فرض روی now تنظیم می‌شود (یعنی زمان حرکت به طور پیش‌فرض روی زمان فعلی تنظیم می‌شود). همچنین می‌توانید به صورت اختیاری transit_mode و/یا transit_routing_preference نیز وارد کنید.
    توجه: ممکن است گاهی اوقات مسیرهای پیاده‌روی و دوچرخه‌سواری مشخص نباشند، بنابراین این مسیرها در نتیجه‌ی برگردانده شده هشدارهایی را نشان می‌دهند که باید به کاربر نمایش دهید.
    توجه: سفرهای حمل و نقل عمومی تا ۷ روز گذشته یا تا ۱۰۰ روز آینده، بسته به در دسترس بودن اطلاعات حمل و نقل عمومی ارائه شده توسط ارائه دهندگان داده، در دسترس هستند. برنامه‌های حمل و نقل عمومی مرتباً تغییر می‌کنند، سفرهای حمل و نقل عمومی موجود ممکن است با گذشت زمان تغییر کنند و هیچ تضمینی برای ارائه نتایج ثابت برای پیش‌بینی‌های از قبل وجود ندارد.

  • منطقه

    کد منطقه، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با برخی استثنائات قابل توجه. به عنوان مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از نظر فنی برای موجودیت "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی").

  • مدل_ترافیک

    فرضیات مورد استفاده هنگام محاسبه زمان در ترافیک را مشخص می‌کند. این تنظیم بر مقدار برگردانده شده در فیلد duration_in_traffic در پاسخ تأثیر می‌گذارد، که شامل زمان پیش‌بینی شده در ترافیک بر اساس میانگین‌های تاریخی است. پارامتر traffic_model فقط می‌تواند برای مسیرهای رانندگی که درخواست شامل departure_time است، مشخص شود. مقادیر موجود برای این پارامتر عبارتند از:

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

    مقدار پیش‌فرض best_guess مفیدترین پیش‌بینی‌ها را برای اکثر موارد استفاده ارائه می‌دهد. این امکان وجود دارد که پیش‌بینی زمان سفر best_guess کوتاه‌تر از optimistic یا در عوض، طولانی‌تر از pessimistic باشد، به دلیل نحوه ادغام اطلاعات ترافیکی زنده توسط مدل پیش‌بینی best_guess .

  • حالت_ترانزیت

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

    • bus نشان می‌دهد که مسیر محاسبه‌شده باید سفر با اتوبوس را ترجیح دهد.
    • subway نشان می‌دهد که مسیر محاسبه‌شده باید سفر با مترو را ترجیح دهد.
    • train نشان می‌دهد که مسیر محاسبه‌شده باید سفر با قطار را ترجیح دهد.
    • tram نشان می‌دهد که مسیر محاسبه‌شده باید سفر با تراموا و قطار سبک شهری را ترجیح دهد.
    • rail نشان می‌دهد که مسیر محاسبه‌شده باید سفر با قطار، تراموا، قطار سبک شهری و مترو را ترجیح دهد. این معادل transit_mode=train|tram|subway است.

  • transit_routing_preference

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

    • less_walking نشان می‌دهد که مسیر محاسبه‌شده باید میزان محدودی پیاده‌روی را ترجیح دهد.
    • fewer_transfers نشان می‌دهد که مسیر محاسبه‌شده باید تعداد محدودی از انتقال‌ها را ترجیح دهد.

  • واحدها

    سیستم واحد مورد استفاده هنگام نمایش نتایج را مشخص می‌کند.

    توجه: این تنظیم سیستم واحد فقط روی متن نمایش داده شده در فیلدهای مسافت تأثیر می‌گذارد. فیلدهای مسافت همچنین حاوی مقادیری هستند که همیشه بر حسب متر بیان می‌شوند.

درخواست نمونه

این مثال از مختصات عرض/طول جغرافیایی برای مشخص کردن مختصات مقصد استفاده می‌کند:

آدرس اینترنتی 

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

حلقه زدن 

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

این مثال از کدهای بعلاوه برای مشخص کردن مختصات مقصد استفاده می‌کند:

آدرس اینترنتی 

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

حلقه زدن 

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

این مثال همان درخواست را با استفاده از یک چندخطی کدگذاری شده نشان می‌دهد:

آدرس اینترنتی 

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

حلقه زدن 

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

اطلاعات ترافیک

اطلاعات ترافیک زمانی استفاده می‌شود که همه موارد زیر اعمال شود (اینها شرایط لازم برای دریافت فیلد duration_in_traffic در پاسخ ماتریس فاصله هستند):

  • پارامتر mode سفر، driving است یا مشخص نشده است ( driving حالت سفر پیش‌فرض است).
  • این درخواست شامل یک پارامتر معتبر departure_time است. departure_time می‌تواند روی زمان فعلی یا زمانی در آینده تنظیم شود. نمی‌تواند در گذشته باشد.

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

آدرس اینترنتی زیر یک درخواست ماتریس مسافت برای مسافت رانندگی بین بوستون، ماساچوست یا چارلزتاون، ماساچوست، و لکسینگتون، ماساچوست و کنکورد، ماساچوست را آغاز می‌کند. این درخواست شامل زمان حرکت است که تمام الزامات مربوط به بازگرداندن فیلد duration_in_traffic در پاسخ ماتریس مسافت را برآورده می‌کند.

آدرس اینترنتی 

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

حلقه زدن 

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

جی‌سون 

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML 


 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins

اصلاح‌کننده‌های مکان

شما می‌توانید از اصلاح‌کننده‌های مکان برای نشان دادن نحوه‌ی نزدیک شدن رانندگان به یک مکان خاص استفاده کنید، با استفاده از اصلاح‌کننده‌ی side_of_road برای مشخص کردن سمت جاده یا با تعیین یک عنوان برای نشان دادن جهت صحیح سفر.

مشخص کنید که مسیرهای محاسبه‌شده باید از یک طرف خاص جاده عبور کنند

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

آدرس اینترنتی 

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

حلقه زدن 

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

هنگام استفاده از side_of_road: با چندخطی‌های کدگذاری‌شده، اصلاح‌کننده به هر مکان در امتداد چندخطی اعمال می‌شود. برای مثال، دو مقصد در این درخواست هر دو از پارامتر زیر استفاده می‌کنند:

آدرس اینترنتی 

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

حلقه زدن 

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

اصلاحگر side_of_road: فقط با این محدودیت قابل استفاده است:

  • پارامتر mode سفر، driving است یا مشخص نشده است ( driving حالت سفر پیش‌فرض است).

مشخص کنید که مسیرهای محاسبه‌شده باید عنوان خاصی داشته باشند

هنگام مشخص کردن یک مکان، می‌توانید درخواست کنید که مسیر محاسبه‌شده از محل در یک عنوان خاص عبور کند. این عنوان با پیشوند heading=X: مشخص می‌شود، که در آن X یک مقدار درجه صحیح بین 0 (شامل) و 360 (منحصراً) است. عنوان 0 نشان دهنده شمال، 90 نشان دهنده شرق است و در جهت عقربه‌های ساعت ادامه می‌یابد. به عنوان مثال، در این درخواست، مسیر محاسبه‌شده از مبدا به سمت شرق می‌رود، سپس یک دور کامل می‌زند:

آدرس اینترنتی 

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

حلقه زدن 

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

اصلاح‌کننده‌ی heading=X: فقط با این محدودیت‌ها قابل استفاده است:

  • پارامتر mode سفر، driving ، bicycling یا مشخص نشده است ( driving حالت سفر پیش‌فرض است).
  • اصلاح‌کننده‌ی side_of_road برای همان مکان مشخص نشده است.
  • مکان با مقدار طول/عرض جغرافیایی مشخص می‌شود. شما نمی‌توانید heading به همراه آدرس‌ها، شناسه‌های مکان یا چندخطی‌های کدگذاری‌شده استفاده کنید.

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

یک نمونه درخواست HTTP در زیر نشان داده شده است که مسافت و مدت زمان را از ونکوور، بریتیش کلمبیا، کانادا و از سیاتل، واشنگتن، ایالات متحده، تا سانفرانسیسکو، کالیفرنیا، ایالات متحده و تا ویکتوریا، بریتیش کلمبیا، کانادا درخواست می‌کند.

آدرس اینترنتی 

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

حلقه زدن 

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

این درخواست چهار عنصر را برمی‌گرداند - دو مبدا ضربدر دو مقصد:

ونکوور به سانفرانسیسکو ونکوور به ویکتوریا
سیاتل به سانفرانسیسکو سیاتل به ویکتوریا

نتایج به صورت ردیف‌هایی برگردانده می‌شوند که هر ردیف شامل یک مبدا و یک مقصد است.

جی‌سون 

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML 


 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km

پاسخ DistanceMatrix

میدان مورد نیاز نوع توضیحات
مورد نیاز آرایه

آرایه‌ای از آدرس‌ها که توسط API از درخواست اصلی شما بازگردانده می‌شود. همانند origin_addresses ، این آدرس‌ها در صورت لزوم بومی‌سازی می‌شوند. این محتوا برای خواندن به همان صورت که هست در نظر گرفته شده است. آدرس‌های قالب‌بندی شده را به صورت برنامه‌نویسی تجزیه نکنید.

مورد نیاز آرایه

آرایه‌ای از آدرس‌ها که توسط API از درخواست اصلی شما بازگردانده می‌شوند. این آدرس‌ها توسط geocoder قالب‌بندی شده و بر اساس پارامتر زبانی که با درخواست ارسال شده است، بومی‌سازی می‌شوند. این محتوا قرار است به همان صورت که هست خوانده شود. آدرس‌های قالب‌بندی شده را به صورت برنامه‌نویسی تجزیه نکنید.

مورد نیاز آرایه <DistanceMatrixRow>

آرایه‌ای از عناصر، که به نوبه خود هر کدام شامل یک عنصر status ، duration و distance هستند.

برای اطلاعات بیشتر به DistanceMatrixRow مراجعه کنید.

مورد نیاز وضعیت ماتریکس فاصله

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

برای اطلاعات بیشتر به DistanceMatrixStatus مراجعه کنید.

اختیاری رشته

رشته‌ای حاوی متن خوانا برای انسان از هرگونه خطایی که هنگام پردازش درخواست رخ داده است.

وضعیت ماتریکس فاصله

کدهای وضعیتی که توسط سرویس برگردانده می‌شوند.

  • OK نشان می‌دهد که پاسخ حاوی یک نتیجه معتبر است.
  • INVALID_REQUEST نشان می‌دهد که درخواست ارائه شده نامعتبر بوده است.
  • MAX_ELEMENTS_EXCEEDED نشان می‌دهد که حاصلضرب مبدا و مقصد از محدودیت هر پرس‌وجو فراتر رفته است.
  • MAX_DIMENSIONS_EXCEEDED نشان می‌دهد که تعداد مبداها یا مقصدها از حد مجاز برای هر پرس‌وجو بیشتر است.
  • OVER_DAILY_LIMIT به هر یک از موارد زیر اشاره دارد:
    • کلید API موجود نیست یا نامعتبر است.
    • پرداخت در حساب شما فعال نشده است.
    • از سقف مصرف تعیین‌شده توسط خود کاربر، عبور شده است.
    • روش پرداخت ارائه شده دیگر معتبر نیست (برای مثال، اعتبار کارت اعتباری منقضی شده است).
  • OVER_QUERY_LIMIT نشان می‌دهد که سرویس در بازه زمانی مجاز، درخواست‌های بسیار زیادی از برنامه شما دریافت کرده است.
  • REQUEST_DENIED نشان می‌دهد که سرویس، استفاده از سرویس Distance Matrix را توسط برنامه شما رد کرده است.
  • UNKNOWN_ERROR نشان می‌دهد که درخواست Distance Matrix به دلیل خطای سرور قابل پردازش نیست. اگر دوباره امتحان کنید، ممکن است درخواست با موفقیت انجام شود.

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

میدان مورد نیاز نوع توضیحات
مورد نیاز آرایه <DistanceMatrixElement>

وقتی API مربوط به Distance Matrix نتایج را برمی‌گرداند، آنها را در یک آرایه JSON rows قرار می‌دهد. حتی اگر هیچ نتیجه‌ای برگردانده نشود (مانند زمانی که مبداها و/یا مقصدها وجود نداشته باشند)، همچنان یک آرایه خالی برمی‌گرداند.

ردیف‌ها بر اساس مقادیر موجود در پارامتر مبدا درخواست مرتب می‌شوند. هر ردیف مربوط به یک مبدا است و هر عنصر درون آن ردیف مربوط به جفت شدن مبدا با مقدار مقصد است.

هر آرایه سطری شامل یک یا چند ورودی عنصر است که به نوبه خود حاوی اطلاعات مربوط به یک جفت مبدا-مقصد واحد است.

برای اطلاعات بیشتر به DistanceMatrixElement مراجعه کنید.

عنصر DistanceMatrix

میدان مورد نیاز نوع توضیحات
مورد نیاز DistanceMatrixElementوضعیت

وضعیتی برای عنصر.

برای اطلاعات بیشتر به DistanceMatrixElementStatus مراجعه کنید.

اختیاری شیء مقدار متن

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

برای اطلاعات بیشتر به TextValueObject مراجعه کنید.

اختیاری شیء مقدار متن

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

برای اطلاعات بیشتر به TextValueObject مراجعه کنید.

اختیاری شیء مقدار متن

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

  • این درخواست شامل پارامتر departure_time ) است.
  • شرایط ترافیکی برای مسیر مورد نظر فراهم است.
  • پارامتر حالت روی رانندگی تنظیم شده است.

برای اطلاعات بیشتر به TextValueObject مراجعه کنید.

اختیاری کرایه

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

برای اطلاعات بیشتر به Fare مراجعه کنید.

کرایه

کل کرایه برای مسیر. 

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
میدان مورد نیاز نوع توضیحات
مورد نیاز رشته

یک کد ارزی ISO 4217 که نشان دهنده ارزی است که مبلغ بر اساس آن بیان می‌شود.

text

 مورد نیاز رشته

مبلغ کل کرایه، به زبان درخواستی قالب‌بندی شده است.

مورد نیاز شماره

مبلغ کل کرایه، به ارز مشخص شده.

DistanceMatrixElementوضعیت

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

شیء مقدار متن

شیء حاوی یک مقدار عددی و نمایش متنی قالب‌بندی‌شده‌ی آن.

میدان مورد نیاز نوع توضیحات

text

 مورد نیاز رشته

مقدار رشته‌ای.

مورد نیاز شماره

مقدار عددی.