سرویس مسیریابی با در نظر گرفتن ترافیک (خودرو و موتورسیکلت بصورت مجزا)
پلتفرم نقشه نشان با بهره‌گیری از داده و مشارکت جامعه کاربران مسیریاب نشان، تنها ارائه‌دهنده ایرانی سرویس مسیریابی بر اساس دیتای ترافیک آنلاین است.
با استفاده از وبسرویس مسیریابی (Routing / Direction API) شما میتوانید بهترین مسیر بین دو نقطه‌ی مشخص را به دست آورید. محاسبه مسیر با توجه به ترافیک معابر محاسبه میشود و هر پاسخ ممکن است شامل یک یا چند مسیر باشد. در هر مسیر زمان سفر و مسافت آن محاسبه می‌گردد. مرتب‌سازی مسیرها بر اساس بهترین مسیر از نظر زمان و مسافت خواهد بود.
از جمله کسب و کار هایی که می‌توانند در خدمات خود از این سرویس استفاده کنند:
سرویس‌های تاکسی‌رانی و حمل‌ونقل آنلاین: این سرویس‌ها نیازمند یافتن سریع‌ترین مسیر بین موقعیت راننده و مسافر هستند. سرویس مسیریابی با در نظر گرفتن شرایط ترافیک لحظه‌ای میتواند کوتاه‌ترین مسیر را محاسبه کند. این امر باعث کاهش زمان سفر، صرفه‌جویی در هزینه سوخت و افزایش رضایت مشتری میشود. همچنین با بهینه‌سازی مسیر، شرکت‌ها قادر خواهند بود از منابع انسانی خود به بهترین شکل استفاده کنند.
شرکت‌های پست و تحویل بسته: این شرکت‌ها باید بسته‌ها را سریع‌ترین زمان ممکن تحویل دهند. سرویس مسیریابی میتواند با در نظر گرفتن ترافیک، مناسب ترین مسیر بین دو و یا چندین نقطه تحویل را محاسبه کند که این باعث کاهش زمان تحویل، کاهش هزینه‌های سوخت و نیروی انسانی و در نهایت بهبود رضایتمندی مشتریان میشود.
مدیریت ناوگان حمل‌ونقل: شرکت‌های دارای ناوگان حمل‌ونقل بزرگ و شرکت های فعال در حوزه لجستیک مانند شرکت‌های پخش نیازمند برنامه‌ریزی دقیق برای جابجایی محموله‌ها و پرسنل هستند. سرویس مسیریابی به این شرکت‌ها کمک میکند تا با شناسایی مسیرهای بهینه با توجه به ترافیک، در هزینه‌های سوخت و زمان صرفه‌جویی کنند.
فروشگاه‌ها و سوپرمارکت‌های آنلاین: این فروشگاه‌ها می‌توانند با استفاده از سرویس مسیریابی، بهترین مسیر و زمان لازم برای تحویل سفارش‌های آنلاین را برآورد کنند. این امر به کاهش زمان تحویل، صرفه‌جویی در هزینه‌های حمل‌ونقل و بهبود رضایتمندی مشتری می‌انجامد.
سرویس ETA / تخمین زمان سفر
توجه داشته باشید که وبسرویس تخمین زمان سفر (ETA) با ترافیک زنده نیز به عنوان بخشی از سرویس مسیریابی است. لذا چنانچه قصد استفاده از ETA را دارید، کافیست ریکوئست خود را طبق مستندات همین صفحه ارسال کنید و زمان تخمین زده شده را در ریسپانس سرویس دریافت نمایید.
شیوه‌ی فراخوانی:
مسیریابی با ترافیک:
GET:
https://api.neshan.org/v4/direction?parameters
Headers:
Api-Key: YOUR_API_KEYمسیریابی بدون ترافیک: (فقط برای خودرو)
پارامتر های وروردی:
GET:
https://api.neshan.org/v4/direction/no-traffic?parameters
Headers:
Api-Key: YOUR_API_KEY- type: مشخص میکند که مسیریابی مخصوص به خودرو یا موتورسیکلت استفاده شود. مقدار آن میتواند car برای مسیریابی خودرو و motorcycle برای مسیریابی موتور باشد.
- origin: مختصات نقطه شروع مسیریابی، این مختصات باید به صورت latitude,longitude باشد که دو عدد با کاما از هم جدا شده‌اند.
- destination: مختصات نقطه پایان مسیریابی که قالب آن مانند نقطه شروع است.
- waypoints: این پارامتر اختیاری بوده و برای مشخص کردن نقاط میانی مسیر استفاده میشود. فرمت ارسال هر نقطه میانی به صورت
- latitude,longitude می‌باشد. در صورتی که بیش از یک نقطه میانی دارید با به صورت زیر آن‌ها را با علامت پایت (|) از هم جدا کنید: latitude,longitude|latitude,longitude
- avoidTrafficZone: این پارامتر اختیاری بوده و مقادیر آن true یا false میتواند باشد. در صورتی که این پارامتر true باشد مسیر از داخل طرح ترافیک عبور نخواهد کرد. همچین در صورتی که مقصد داخل طرح ترافیک باشد هیچ مسیری پیدا نمی‌شود.
- avoidOddEvenZone: این پارامتر اختیاری بوده و مقادیر آن true یا false میتواند باشد. در صورتی که این پارامتر true باشد مسیر از داخل طرح زوج و فرد عبور نخواهد کرد. همچین در صورتی که مقصد داخل طرح ترافیک باشد هیچ مسیری پیدا نمی‌شود.
- alternative: این پارامتر اختیاری بوده و مقادیر آن true یا false میتواند باشد. در صورتی که این پارامتر true باشد و مسیرهای جایگزین برای نقاط مشخص شده وجود داشته باشد این مسیرها در پاسخ ارائه خواهند شد. (مقدار پیش فرض این پارامتر false است)
- bearing: این فیلد که مقدار آن میتواند بین ۰ تا ۳۶۰ باشد(زاویه ساعت گرد نسبت به شمال)، جهت را هنگام شروع مسیر یابی مشخص می نماید. این مقدار منجر به مسیر یابی بهینه تر بر اساس جهت شروع مسیر یابی در خیابان میشود.
رمزگذاری آدرس اینترنتی :
بعضی از حروف و کاراکترها نمی‌توانند بصورت مستقیم در آدرس قرار بگیرند زیراکه این کاراکترها دارای معانی خاص خود هستند به عنوان مثال کاراکتر (=) برای جداسازی کلید و مقدار آن کلید مورد استفاده قرار می‌گیرد از این رو در نحو نوشتاری عمومی آدرس های اینترنتی رمزگذاری مطرح شد که این مشکل را به صورت عمومی حل کند .
بعضی از کاراکترهای خاص و معادل رمزگذاری شده آن ها :
معادل رمزگذاری | کاراکتر |
%20 | Space |
%22 | “ |
%23 | # |
%7C | | |
%25 | % |
مستندات و کتاب‌خانه ها :
- مستندات گوگل
- ساخت یک پارامتر موفق UrlEncode
- کتاب‌خانه ها و توابع برای زبان ها (جاوا ، جاوااسکریپت , Php)
فرمت پاسخ:
{
"routes": [
{
"overview_polyline": {
"points": "kz{xEggtxHn@E|@iAtMcAq@k`Ap@yO_OyA"
},
"legs": [
{
"summary": "روانمهر - ولیعصر",
"distance": {
"value": 1820.0,
"text": "۲ کیلومتر"
},
"duration": {
"value": 487.0,
"text": "۸ دقیقه"
},
"steps": [
{
"name": "میدان انقلاب اسلامی",
"instruction": "در جهت جنوب در میدان انقلاب اسلامی قرار بگیرید",
"bearing_after": 193,
"type": "depart",
"modifier": "left",
"distance": {
"value": 61.0,
"text": "۷۵ متر"
},
"duration": {
"value": 13.0,
"text": "کمتر از ۱ دقیقه"
},
"polyline": "kz{xEggtxHHBRAPGPMJSDS",
"start_location": [
51.390755,
35.701021
]
},
{
"name": "",
"instruction": "به مسیر خود ادامه دهید",
"bearing_after": 147,
"type": "exit rotary",
"modifier": "slight right",
"exit": 1,
"distance": {
"value": 279.0,
"text": "۳۰۰ متر"
},
"duration": {
"value": 72.0,
"text": "۱ دقیقه"
},
"polyline": "ww{xEcitxHXSf@Ih@EvCS~AMjCQ",
"start_location": [
51.391063,
35.700596
]
},
{
"name": "روانمهر",
"instruction": "به سمت روانمهر، به چپ بپیچید",
"bearing_after": 80,
"type": "turn",
"modifier": "left",
"distance": {
"value": 983.0,
"text": "۱۰۰۰ متر"
},
"duration": {
"value": 261.0,
"text": "۴ دقیقه"
},
"polyline": "gh{xE{ktxHASC]AkB?_@A}AGgJAy@?q@AQAiCEmFEoCAwCCmGAcBAcB?EAaBAkA?mA",
"start_location": [
51.391498,
35.698122
]
},
{
"name": "خسرو شکیبایی",
"instruction": "در خسرو شکیبایی به مسیر خود ادامه دهید",
"bearing_after": 95,
"type": "new name",
"modifier": "straight",
"distance": {
"value": 210.0,
"text": "۲۲۵ متر"
},
"duration": {
"value": 78.0,
"text": "۱ دقیقه"
},
"polyline": "yi{xEuovxHXuFVuE",
"start_location": [
51.402349,
35.698366
]
},
{
"name": "ولیعصر",
"instruction": "به چپ بپیچید و وارد ولیعصر شوید",
"bearing_after": 7,
"type": "end of road",
"modifier": "left",
"distance": {
"value": 288.0,
"text": "۳۰۰ متر"
},
"duration": {
"value": 130.0,
"text": "۲ دقیقه"
},
"polyline": "gh{xEa~vxHgAK{BUcCU_AKwBU",
"start_location": [
51.404651,
35.698117
]
},
{
"name": "ولیعصر",
"instruction": "در مقصد قرار دارید",
"bearing_after": 0,
"type": "arrive",
"distance": {
"value": 0.0,
"text": ""
},
"duration": {
"value": 0.0,
"text": ""
},
"polyline": "gx{xE{`wxH",
"start_location": [
51.405102,
35.700682
]
}
]
}
]
}
]
}
اجزای پاسخ:
- routes: هر پاسخ مسیر ممکن است از یک یا چند route تشکیل شده باشد. مسیرهای جایگزین یا alternative بسته به موقعیت ممکن است تغییر کنند. اجزای یک route به صورت زیر می‌باشند:
- overviewPolyline: یک نمونه simplified شده از کل مسیر که به صورت Encoded Polyline می‌باشد. دقت کنید این فیلد تنها برای نمایش یک نمای کلی از خط مسیر در سطح زوم‌های بالا می‌باشد و خطوط آن دقیق نمی‌باشند. برای رسم خطوط اصلی مسیر باید از فیلد polyline در هر step استفاده کنید.
- legs: در صورتی که مسیریابی فقط بین دو نقطه انجام شود route دارای یک leg خواهد بود. اگر پارامتر نقاط میانی برای مسیریابی ارسال شود بین هر دو نقطه میانی در route یک leg ایجاد میشود. هر leg از اجزای زیر تشکیل شده‌است:
- summery: خلاصه‌ای از مسیر که معمولا شامل نام دو خیابان اصلی ابتدا و انتهای آن leg است. با استفاده از خلاصه به صورت حدودی مسیر مشخص میشود.
- distance: فاصله بین دو نقطه که به دو صورت عددی و قابل خواندن ارائه میشود. در فرمت عددی مقدار فاصله به متر است.
- duration: زمان سفر بین دو نقطه که به دو صورت عددی و قابل خواند ارائه میشود. در فرمت عددی مقدار زمان به ثانیه است.
- steps: با توجه به شکل مسیر و پیچ خم‌های موجود یک leg میتواند شامل یک یا چند step باشد. اجزای یک step بصورت زیر می‌باشند:
- name: نام معبری که step در آن شروع میشود.
- instruction: یک دستور العمل که مشخص می‌کنند چطور باید وارد این step شد.
- bearnig_after: زاویه ساعت گرد نسبت به شمال، هنگام خروج از step.
- type: یک string که نشاندهنده نوع maneuver است.
- modifier: این پارامتر نوع و جهت تغییر مسیر در هر step را مشخص میکند. این مقدار این پارامتر یکی از موارد زیر است:
right,slight-right,sharp-right,left,slight-left,sharp-left,uturn,straight - exit: یک
integerنشاندهنده شماره خروجی که باید از آن رفت. - rotary_name: نام میدان. اگر step میدان باشد، و نام میدان نیز مشخص باشد، در ریسپانس برخواهد گشت.
- distance: طول step که به دو صورت عددی و قابل خواندن ارائه میشود. در فرمت عددی مقدار فاصله به متر است.
- duration: زمان سفر در این step که به دو صورت عددی و قابل خواند ارائه میشود. در فرمت عددی مقدار زمان به ثانیه است.
- polyline: ژئومتری هر step که به صورت Encoded polyline ارائه میشود.
- startLocation: نقطه شروع step، با توجه به اینکه یک مسیر به چند step تقسیم میشود نقطه شروع هر step در این قسمت به صورت یک آرایه که حاوی دو عدد longitude و latitude هست آورده خواهد شد.
1. پارامترهای name, exit, rotary_name ممکن است خالی برگردند:
-
دو پارامتر exit و rotary_name فقط زمانی پر هستند که step میدان یا خروجی باشد.
- پارامتر name زمانی خالی است که بعضی خیابان‌ها در شهرهای خیلی کوچک که اسم ندارند یا دیتایی برای آن معبر وجود ندارد، یا بعضی لینک‌ها که اسم خاصی ندارند و اسم‌گذاری بیشتر باعث اشتباه میشود.
2. زمانی که پارامتر type از نوع depart یا arrive باشد و مبدا و مقصد خیلی نزدیک هم باشند modifier نداریم.
3. انواع حالتهای پارامتر type در جدول زیر آمده است:
type |
توضیح |
|---|---|
turn |
یک گردش ساده در مسیر modifier |
new name |
امکان گردش نیست اما نام خیابان تغییر میکند. خیابان ممکن است بر اساس modifier گردش داشته باشد. |
depart |
نشاندهنده شروع حرکت است. |
arrive |
نشاندهنده رسیدن به مقصد است. |
merge |
پیوستن به یک خیابان (مانند ورود از یک رَمپ به یک بزرگراه، که در اینصورتmodifierجهت ورود یا پیوستن به خیابان جدید را مشخص میکند) |
continue |
در راستای modifierبه مسیر خود ادامه دهید |
on ramp |
استفاده از رمپ برای ورود به بزرگراه (جهت آن با modifier مشخص میشود) |
off ramp |
استفاده از رمپ برای خروج از بزرگراه (جهت آن با modifier مشخص میشود) |
fork |
رفتن به راست یا چپ در دوراهی، بر اساس modifier |
end of road |
خیابان در یک تقاطع T شکل تمام میشود و در مسیر modifierگردش میکند. |
roundabout |
عبور از میدان - اگر مسیر از میدان عبور کند و از آن بگذرد یک property اضافی بنام exit وجود خواهد داشت. در این حالت modifier جهت ورود به میدان را مشخص میکند. |
rotary |
عبور از میدان - اگر مسیر از میدان عبور کند و از آن بگذرد یک property اضافی بنام exit وجود خواهد داشت. در این حالت modifier جهت ورود به میدان را مشخص میکند. |
roundabout turn |
گردش در یک میدان کوچک، که باید با آن مانند یک گردش عادی برخورد کرد. modifier نشاندهنده جهت گردش است. |
notification |
نشاندهنده تغییر در شرایط رانندگی. چنانچه خیابان گردش داشته باشد modifier جهت آن را نشان میدهد. |
exit roundabout |
نشاندهنده ی maneuver در حال خروج از یک roundabout (معمولا قبل از roundabout می آید) |
exit rotary |
نشاندهنده ی maneuver در حال خروج از یک rotary (نسخه بزرگی از یک roundabout) |
- right: گردش به راست
- slight-right: گردش به راست با زاویه کم
- sharp-right: گردش به راست با زاویه تند
- left: گردش به چپ
- slight-left: گردش به چپ با زاویه کم
- sharp-left: گردش به چپ با زاویه تند
- uturn: دور برگردان
- straight: مسیر مستقیم
با فراخوانی این API در صورت وجود اشکال ممکن است، خطاهای زیر در خروجی برای شما ارسال گردند. شناسایی و مدیریت این خطاها میتواند به از بروز خطاهای احتمالی در اپلیکیشن شما جلوگیری کند. این خطاها عبارتند از:
470 : CoordinateParseError
چنانچه مختصات جغرافیایی ارسالی معتبر نباشد رخ خواهد داد.
480 : KeyNotFound
در صورتی که در فراخوانی وبسرویس از یک Api Key نامتعبر استفاده کنید یا Api Key خود را در header ارسال نکنید رخ خواهد داد.
481 : LimitExceeded
در صورتی که تعداد فراخوانی وب‌سرویس‌ها از میزان مجازی که برای شما تعیین شده‌است عبور کند رخ خواهد داد.
482 : RateExceeded
چنانچه تعداد درخواست وبسرویس در دقیقه از حد مجاز عبور کند رخ خواهد داد.
483 : ApiKeyTypeError
کلید دسترسی استفاده شده با سرویس فراخوانی شده همخوانی ندارد. بایستی از کلید دسترسی مرتبط با سرویس موردنظر استفاده کنید.
484 : ApiWhiteListError
با توجه به اسکوپ تعریف‌شده برای این کلید، شما مجاز به استفاده نیستید.
485 : ApiServiceListError
سرویس فراخوانی شده با سرویس‌های تعریف‌شده برای این کلید دسترسی همخوانی ندارد.
500 : GenericError
در صورت بروز خطایی غیر از خطاهای بالا این خطا گزارش میشود.
