هشدار!
صفحه‌ای که در حال مشاهده آن هستید، حاوی مستندات نسخه قدیمی سرویس
مسیریابی
می‌باشد.
مستندات مرتبط با نسخه جدید این سرویس را در
این صفحه
میتوانید مشاهده کنید.
سرویس مسیریابی با در نظر گرفتن ترافیک (خودرو و موتورسیکلت بصورت مجزا)
پلتفرم نقشه نشان با بهره‌گیری از داده و مشارکت جامعه کاربران پنج میلیونی مسیریاب نشان، تنها ارائه‌دهنده ایرانی سرویس مسیریابی بر اساس دیتای ترافیک آنلاین است.
با استفاده از وب‌سرویس مسیریابی (Direction API) شما میتوانید بهترین مسیر بین دو نقطه‌ی مشخص را به دست آورید. محاسبه مسیر با توجه به ترافیک معابر محاسبه می‌شود و هر پاسخ ممکن است شامل یک یا چند مسیر باشد. در هر مسیر زمان سفر و مسافت آن محاسبه می‌گردد. مرتب‌سازی مسیرها بر اساس بهترین مسیر از نظر زمان و مسافت خواهد بود.
شیوه‌ی فراخوانی:
مسیریابی با ترافیک:
GET:
https://api.neshan.org/v3/direction?parameters
Headers:
Api-Key: YOUR_API_KEYمسیریابی بدون ترافیک: (فقط برای خودرو)
GET:
https://api.neshan.org/v2/direction/no-traffic?parameters
Headers:
Api-Key: YOUR_API_KEYپارامتر های وروردی:
- type: مشخص میکند که مسیریابی مخصوص به خودرو یا موتورسیکلت استفاده شود. مقدار آن میتواند
carبرای مسیریابی خودرو وmotorcycleبرای مسیریابی موتور باشد. - origin: مختصات نقطه شروع مسیریابی، این مختصات باید به صورت
latitude,longitudeباشد که دو عدد با کاما از هم جدا شده‌اند. - destination: مختصات نقطه پایان مسیریابی که قالب آن مانند نقطه شروع است.
- waypoint: این پارامتر اختیاری بوده و برای مشخص کردن نقاط میانی مسیر استفاده می‌شود. فرمت ارسال هر نقطه میانی به صورت
latitude,longitudeمی‌باشد. در صورتی که بیش از یک نقطه میانی دارید با به صورت زیر آن‌ها را با علامت پایت (|) از هم جدا کنید:latitude,longitude|latitude,longitude - avoidTrafficZone: این پارامتر اختیاری بوده و مقادیر آن
trueیاfalseمیتواند باشد. در صورتی که این پارامتر true باشد مسیر از داخل طرح ترافیک عبور نخواهد کرد. همچین در صورتی که مقصد داخل طرح ترافیک باشد هیچ مسیری پیدا نمی‌شود. - avoidOddEvenZone: این پارامتر اختیاری بوده و مقادیر آن
trueیاfalseمیتواند باشد. در صورتی که این پارامتر true باشد مسیر از داخل طرح زوج و فرد عبور نخواهد کرد. همچین در صورتی که مقصد داخل طرح ترافیک باشد هیچ مسیری پیدا نمی‌شود. - alternative: این پارامتر اختیاری بوده و مقادیر آن
trueیاfalseمیتواند باشد. در صورتی که این پارامتر true باشد و مسیرهای جایگزین برای نقاط مشخص شده وجود داشته باشد این مسیرها در پاسخ ارائه خواهند شد. (مقدار پیش فرض این پارامتر false است)
نکته!
با توجه به اینکه نام طرح ترافیک در شهرهای دیگر (غیر از تهران) عموماً یه جای طرح زوج و فرد نیز استفاده می‌شود، چنانچه در سایر شهرها هر یک از پارامترهای avoidTrafficZone و avoidOddEvenZone مقدار true داشته باشند و مقصد درون طرح زوج و فرد آن شهر باشد، سرویس مسیریابی خطای NoRouteFound در پاسخ برمی‌گرداند.
رمزگذاری آدرس اینترنتی :
بعضی از حروف و کاراکترها نمی‌توانند بصورت مستقیم در آدرس قرار بگیرند زیراکه این کاراکترها دارای معانی خاص خود هستند به عنوان مثال کاراکتر (=) برای جداسازی کلید و مقدار آن کلید مورد استفاده قرار می‌گیرد از این رو در نحو نوشتاری عمومی آدرس های اینترنتی رمزگذاری مطرح شد که این مشکل را به صورت عمومی حل کند .
بعضی از کاراکترهای خاص و معادل رمزگذاری شده آن ها :
معادل رمزگذاری | کاراکتر |
%20 | Space |
%22 | “ |
%23 | # |
%7C | | |
%25 | % |
مستندات و کتاب‌خانه ها :
- مستندات گوگل
- ساخت یک پارامتر موفق UrlEncode
- کتاب‌خانه ها و توابع برای زبان ها (جاوا ، جاوااسکریپت , Php)
فرمت پاسخ:
{
"routes": [
{
"legs": [
{
"summary": "آزادی - ولیعصر",
"distance": {
"value": 8998,
"text": "۹ کیلومتر"
},
"duration": {
"value": 2012,
"text": "۳۴ دقیقه"
},
"steps": [
{
"name": "عضدی جنوبی",
"instruction": "در جهت شرق در عضدی جنوبی قرار بگیرید",
"distance": {
"value": 46,
"text": "۴۶ متر"
},
"duration": {
"value": 11,
"text": "کمتر از ۱ دقیقه"
},
"polyline": "qxu|EkpcjJb@{@Tc@b...",
"maneuver": "depart",
"start_location": [
51.344035,
35.695452
]
}
]
}
],
"overview_polyline": {
"points": "qwzxEgckxHBeAWEDq ..."
}
}
]
}اجزای این پاسخ بصورت زیر می‌باشند:
- routes: هر پاسخ مسیر ممکن است از یک یا چند route تشکیل شده باشد. مسیرهای جایگزین یا alternative بسته به موقعیت ممکن است تغییر کنند. اجزای یک route بصورت زیر می‌باشند:
-
- legs: در صورتی که مسیریابی فقط بین دو نقطه انجام شود route دارای یک leg خواهد بود. اگر پارامتر نقاط میانی برای مسیریابی ارسال شود بین هر دو نقطه میانی در route یک leg ایجاد می‌شود. هر leg از اجزای زیر تشکیل شده‌است:
- summery: خلاصه‌ای از مسیر که معمولا شامل نام دو خیابان اصلی ابتدا و انتهای آن leg است. با استفاده از خلاصه به صورت حدودی مسیر مشخص می‌شود.
- distance: فاصله بین دو نقطه که به دو صورت عددی و قابل خواندن ارائه می‌شود. در فرمت عددی مقدار فاصله به متر است.
- duration: زمان سفر بین دو نقطه که به دو صورت عددی و قابل خواند ارائه می‌شود. در فرمت عددی مقدار زمان به ثانیه است.
- steps: با توجه به شکل مسیر و پیچ خم‌های موجود یک leg میتواند شامل یک یا چند step باشد. اجزای یک step بصورت زیر می‌باشند:
- name: نام معبری که step در آن شروع می‌شود.
- instruction: یک دستور العمل که مشخص می‌کنند چطور باید وارد این step شد.
- distance: طول step که به دو صورت عددی و قابل خواندن ارائه می‌شود. در فرمت عددی مقدار فاصله به متر است.
- duration: زمان سفر در این step که به دو صورت عددی و قابل خواند ارائه می‌شود. در فرمت عددی مقدار زمان به ثانیه است.
- polyline: ژئومتری هر step که به صورت Encoded polyline ارائه می‌شود.
- maneuver: این پارامتر نوع و جهت تغییر مسیر در هر step را مشخص میکند. این مقدار این پارامتر یکی از موارد زیر است:
right,slight-right,sharp-right,left,slight-left,sharp-left,uturn,straight,exit-rotary,depart,arrive - startLocation: نقطه شروع step . با توجه به اینکه یک مسیر به چند step تقسیم می‌شود نقطه شروع هر step در این قسمت به صورت یک آرایه که حاوی دو عدد longitude و latitude هست آورده خواهد شد.
- overviewPolyline: یک نمونه simplified شده از کل مسیر که به صورت Encoded Polyline می‌باشد. دقت کنید این فیلد تنها برای نمایش یک نمای کلی از خط مسیر در سطح زوم‌های بالا می‌باشد و خطوط آن دقیق نمی‌باشند. برای رسم خطوط اصلی مسیر باید از فیلد polyline در هر step استفاده کنید.
- legs: در صورتی که مسیریابی فقط بین دو نقطه انجام شود route دارای یک leg خواهد بود. اگر پارامتر نقاط میانی برای مسیریابی ارسال شود بین هر دو نقطه میانی در route یک leg ایجاد می‌شود. هر leg از اجزای زیر تشکیل شده‌است:
توضیحات مرتبط با فیلد maneuver:
- right: گردش به راست
- slight-right: گردش به راست با زاویه کم
- sharp-right: گردش به راست با زاویه تند
- left: گردش به چپ
- slight-left: گردش به چپ با زاویه کم
- sharp-left: گردش به چپ با زاویه تند
- uturn: دور برگردان
- straight: مسیر مستقیم
- exit-rotary: خروجی میدان
- depart: شروع مسیر (مبدا)
- arrive: خاتمه مسیر (مقصد)
توضیحات مرتبط با فیلد maneuver:
جهت کاهش حجم پاسخ در سرویس مسیریابی، خط پیش‌نمایش و خطوط مسیر به
Encoded Polyline
تبدیل شده‌اند.
برای آشنایی با این فرمت و چگونگی استفاده و
decode
کردن آن میتوانید به مطالب زیر مراجعه کنید:
کلید دسترسی سرویس (api-key)
برای ساخت کلید دسترسی (api-key) مناسب برای این سرویس شما باید در پنل ساخت کلید دسترسی گزینه سرویس ها و سپس مسیریابی را انتخاب کنید.
این را هم در نظر داشته باشید برای امنیت بیشتر کلید دسترسی خود و جلو گیری از سواستفاده شدن از آن IP سرور خود را نیز میتوانید در فیلد دامنه/Ip های مجاز وارد کنید.
