سرویس Distance Matrix با در نظر گرفتن ترافیک (برای خودرو و موتور سیکلت بصورت مجزا)
پلتفرم نقشه نشان با بهره‌گیری از داده و مشارکت جامعه کاربران ده میلیونی مسیریاب نشان، تنها ارائه‌دهنده ایرانی سرویس ماتریس فاصله بر اساس دیتای ترافیک آنلاین است.
با استفاده از وب‌سرویس ماتریس فاصله (Distance Matrix API) میتوانید فاصله و زمان حرکت میان ماتریسی از نقاط شروع و پایانی را به دست آورید. تمامی فواصل و زمان‌ها با در نظر گرفتن بهترین مسیر بر اساس وضعیت فعلی ترافیک محاسبه می‌شوند.
از جمله موارد کاربرد این سرویس برای کسب و کار ها:
برنامه ریزی سفر درون و برون شهری: شرکت ها می توانند با استفاده از این سرویس، فواصل و زمان سفر بین چندین نقطه را محاسبه و بر اساس آن سفرهای کاری را برنامه ریزی نمایند.
شرکت های تاکسی آنلاین و حمل و نقل مسافر: در این دسته از کسب و کارها، محاسبه دقیق زمان و هزینه سفر برای مسافران از اهمیت بسزایی برخوردار است. سرویس ماتریس فاصله به این شرکت ها امکان می دهد تا با دقت بالایی، فاصله و زمان تقریبی سفر بین نقطه شروع و مقصد را پیش بینی کنند.
محاسبه هزینه حمل و نقل: شرکت های لجستیک یا حتی فروشگاه های آنلاین می توانند با داشتن فاصله های دقیق، هزینه حمل و نقل را به درستی محاسبه کنند.
مدیریت ناوگان خودرو: شرکت های دارای ناوگان می توانند با این سرویس، فواصل بین وسایل نقلیه در نقاط مختلف را بدانند و منابع خود را بهتر مدیریت کنند.
سرویس های رزرو هتل و مسافرتی: این سرویس ها می توانند از ماتریس فاصله برای ارائه اطلاعات دقیق در مورد فاصله هتل ها یا اقامتگاه ها تا جاذبه های گردشگری و امکانات شهری استفاده کنند.
رستوران ها و سرویس تحویل غذا: رستوران ها می توانند از این سرویس برای تعیین محدوده تحویل بهینه، برآورد هزینه و زمان ارسال، و انتخاب مکان شعب جدید استفاده کنند.
برنامه ریزی شهری: در طراحی و برنامه ریزی شهری، دانستن فواصل بین امکانات شهری و مراکز مختلف اهمیت بسزایی دارد.
شیوه‌ی فراخوانی:
با محاسبه ترافیک لحظه ای:
GET:
https://api.neshan.org/v1/distance-matrix?type=car&origins=36.3177579,59.5323219|36.337115,59.530621&destinations=36.35067,59.5451965|36.337005,59.530021
Headers:
Api-Key: YOUR_API_KEYبدون ترافیک:
GET:
https://api.neshan.org/v1/distance-matrix/no-traffic?type=car&origins=36.3177579,59.5323219|36.337115,59.530621&destinations=36.35067,59.5451965|36.337005,59.530021
Headers:
Api-Key: YOUR_API_KEYپارامتر های وروردی:
- type: مشخص میکند که محاسبه مسافت و زمان، مخصوص به خودرو یا موتورسیکلت استفاده شود. مقدار آن میتواند
carبرای مسیریابی خودرو وmotorcycleبرای مسیریابی موتور باشد. (مقدار پیش فرض این پارامترcarاست) - origins: لیستی از مختصات نقاط شروعی. هر کدام از این مختصات باید به فرم
latitude,longitudeباشند که با کاما (,) از یکدیگر جدا شده‌اند. در صورتی که تعداد مختصات بیشتر از یک عدد باشد از علامت پایپ ( | ) برای جداسازی آنها استفاده می‌شود. - destinations: لیستی از مختصات نقاط پایانی که قالب آن مانند origins است
رمزگذاری آدرس اینترنتی :
بعضی از حروف و کاراکترها نمی‌توانند بصورت مستقیم در آدرس قرار بگیرند زیراکه این کاراکترها دارای معانی خاص خود هستند به عنوان مثال کاراکتر (=) برای جداسازی کلید و مقدار آن کلید مورد استفاده قرار می‌گیرد از این رو در نحو نوشتاری عمومی آدرس های اینترنتی رمزگذاری مطرح شد که این مشکل را به صورت عمومی حل کند .
بعضی از کاراکترهای خاص و معادل رمزگذاری شده آن ها :
معادل رمزگذاری | کاراکتر |
%20 | Space |
%22 | “ |
%23 | # |
%7C | | |
%25 | % |
مستندات و کتاب‌خانه ها :
- مستندات گوگل
- ساخت یک پارامتر موفق UrlEncode
- کتاب‌خانه ها و توابع برای زبان ها (جاوا ، جاوااسکریپت , Php)
فرمت پاسخ:
{
"status": "Ok",
"rows": [
{
"elements": [
{
"status": "Ok",
"duration": {
"value": 699,
"text": "۱۲ دقیقه"
},
"distance": {
"value": 8332,
"text": "۸ کیلومتر"
}
},
{
"status": "Ok",
"duration": {
"value": 605,
"text": "۱۰ دقیقه"
},
"distance": {
"value": 5373,
"text": "۵ کیلومتر"
}
}
]
},
{
"elements": [
{
"status": "Ok",
"duration": {
"value": 511,
"text": "۹ دقیقه"
},
"distance": {
"value": 5317,
"text": "۵ کیلومتر"
}
},
{
"status": "Ok",
"duration": {
"value": 69,
"text": "۱ دقیقه"
},
"distance": {
"value": 389,
"text": "۴۰۰ متر"
}
}
]
}
],
"origin_addresses": [
"36.317559,59.532226",
"36.337077,59.530843"
],
"destination_addresses": [
"36.350681,59.545227",
"36.337012,59.530023"
]
}اجزای این پاسخ بصورت زیر می‌باشند:
- status: وضعیت کلی درخواست را نشان می‌دهد.در صورتی که درخواست شما با موفقیت پردازش شده باشد مقدار آن “Ok” است.
- origin_addresses: آرایه‌ای از مختصات نقاط شروعی.هر کدام از مختصات به فرم
latitude,longitudeهستند. - destination_addresses: آرایه‌ای از مختصات نقاط پایانی. هر کدام از مختصات به فرم
latitude,longitudeهستند. - rows: پاسخ Distance Matrix در آرایه ای از سطرها (rows) ذخیره می‌شود که هر سطر شامل آرایه‌ای از المنت‌ها (elements) است.
ترتیب قرار گرفتن سطر ها بر اساس مقادیر قرار گرفته در origin_addresses است به طوری که سطر iام متناظر با مختصات iام در آرایه origin_addresses می باشد.- elements: آرایه‌ای از element هاست و ترتیب قرار گرفتن المنت‌ها (elements) در هر سطر براساس مقادیر قرار گرفته در destination_addresses است به طوری که المنت iام متناظر با مختصات iام در آرایه destination_addresses می‌باشد. هر element نشان دهنده زمان-مسافت بین یک زوج از نقاط شروعی و پایانی می‌باشد.
اجزای هر element به صورت زیر هستند:- status: سه حالت برای این مقدار وجود دارد:
- NoRoute: هیچ مسیری بین دو نقطه شروع و پایان وجود ندارد.
- UnknownError: نشان دهنده مشکل سمت سرور در هنگام پردازش این element است.ممکن است با تلاش دوباره این مشکل برطرف شود.
- Ok: پردازش element با موفقیت انجام شده است. فقط در این حالت دو متغیر distance و duration وجود دارند.
- distance: فاصله بین دو نقطه که به دو صورت عددی و قابل خواندن ارائه می‌شود. در فرمت عددی مقدار فاصله به متر است.
- duration: زمان سفر بین دو نقطه که به دو صورت عددی و قابل خواند ارائه می‌شود. در فرمت عددی مقدار زمان به ثانیه است.
- status: سه حالت برای این مقدار وجود دارد:
- elements: آرایه‌ای از element هاست و ترتیب قرار گرفتن المنت‌ها (elements) در هر سطر براساس مقادیر قرار گرفته در destination_addresses است به طوری که المنت iام متناظر با مختصات iام در آرایه destination_addresses می‌باشد. هر element نشان دهنده زمان-مسافت بین یک زوج از نقاط شروعی و پایانی می‌باشد.
مزایای این روش فراخوانی به شرح زیر است.
- دیگر نیازی به ارسال کلید دسترسی به صورت کلاینت ساید ندارید و کلید دسترسی شما در معرض سرقت قرار نمیگیرد.
- میتوانید برای کلید خود whitelist تعیین کنید.
- در صورت انتشار ورژن جدید سرویس ها در پلتفرم نشان براحتی امکان بروزرسانی api را خواهید داشت.
شیوه‌ی فراخوانی:
با فراخوانی این API در صورت وجود اشکال ممکن است، خطاهای زیر در خروجی برای شما ارسال گردند. شناسایی و مدیریت این خطاها میتواند به از بروز خطاهای احتمالی در اپلیکیشن شما جلوگیری کند. این خطاها عبارتند از:
470 : CoordinateParseError
چنانچه مختصات جغرافیایی ارسالی معتبر نباشد رخ خواهد داد.
480 : KeyNotFound
در صورتی که در فراخوانی وب‌سرویس از یک Api Key نامتعبر استفاده کنید یا Api Key خود را در header ارسال نکنید رخ خواهد داد.
481 : LimitExceeded
در صورتی که تعداد فراخوانی وب‌سرویس‌ها از میزان مجازی که برای شما تعیین شده‌است عبور کند رخ خواهد داد.
482 : RateExceeded
چنانچه تعداد درخواست وب‌سرویس در دقیقه از حد مجاز عبور کند رخ خواهد داد.
483 : ApiKeyTypeError
کلید دسترسی استفاده شده با سرویس فراخوانی شده همخوانی ندارد. بایستی از کلید دسترسی مرتبط با سرویس موردنظر استفاده کنید.
484 : ApiWhiteListError
با توجه به اسکوپ تعریف‌شده برای این کلید، شما مجاز به استفاده نیستید.
485 : ApiServiceListError
سرویس فراخوانی شده با سرویس‌های تعریف‌شده برای این کلید دسترسی همخوانی ندارد.
500 : GenericError
در صورت بروز خطایی غیر از خطاهای بالا این خطا گزارش می‌شود.
بازتاب: وب‌سرویس نگاشت نقطه بر نقشه – پلتفرم نقشه نشان