مسیریابی

تعریف سرویس#

سرویس مسیریابی (Routing) مپ با دریافت مختصات مجموعه‌ای از نقاط به‌صورت دو یا چند نقطه یا به‌صورت یک polyline، تمامی داده‌های مربوط به بهینه‌ترین مسیر بین نقاط را به‌صورت خروجی JSON در اختیار شما قرار می‌ده. شما به‌وسیله API مسیریابی مپ می‌تونید با مشخص‌کردن دو یا چند نقطه، مسیر بهینه، مسیر جایگزین، فاصله بین نقاط، زمان رسیدن به مقصد، کلیه‌ی معابر طی مسیر به‌صورت گام‌های geohash و… رو دریافت کنید.

نکته 🚧
درحال‌حاضر مسیریابی در شهرهای تهران، مشهد، تبریز، کرج، اصفهان، شیراز، رشت و قم با درنظرگرفتن ترافیک و در سایر شهر‌ها بدون در نظر گرفتن ترافیک صورت می‌گیره. در نتیجه زمان رسیدن به مقصد (ETA) در تهران، مشهد، تبریز، کرج، اصفهان، شیراز، رشت و قم به‌صورت واقعی و برای سایر نقاط (شهرها) براساس حداکثر سرعت تردد در معابر محاسبه می‌شه.

دسترسی به این سرویس از طریق API مسیریابی مپ که با Convention Restful طراحی شده فراهم شده. سرویس مسیریابی امکانات متنوعی رو برای توسعه‌دهندگان فراهم می‌آورد تا بتوانند جزئیات مختلفی را در مسیریابی اعمال کنند. این ویژگی‌ها شامل موارد زیر می‌شود:

مسیریابی جهت تردد با خودرو
مسیریابی جهت تردد با دوچرخه
مسیریابی جهت تردد پیاده
درنظرگرفتن محدودیت‌های ترافیکی (طرح ترافیک یا زوج و فرد)
نمایش مسیر جایگزین
دریافت اطلاعات مسیر با جزئیات هر معبر عبوری
ساده‌سازی نمایش مسیر برای بزرگنمایی‌های پایین

تفاوت مسیریابی دوچرخه با مسیریابی استاندارد خودرو در سرعت اعلام شده در ETA و جلوگیری از حرکت در بزرگراه برای دوچرخه هستش. تفاوت مسیریابی پیاده با مسیریابی استاندارد در سرعت اعلامی برای ETA و همچنین دسترسی پیاده به خیابان‌های یکطرفه، پل‌های عابرپیاده، مسیرهای زیرگذر عابرپیاده و مسیرهای پیاده رو هست.

اصطلاحات کاربردی#

ردیف	نام اصطلاح	شرح اصطلاح
۱	Geohash	فرمتی جهت نگهداری داده‌های جغرافیایی به‌صورت فشرده
۲	Leaflet	یک کتابخانه‌ی متن‌باز JavaScript که به‌عنوان ابزاری رایج جهت ساخت و نمایش نقشه به‌صورت تحت وب استفاده می‌شود
۳	Front end	راهکاری برای نمایش اطلاعات از طریق یک رابط گرافیکی جهت مشاهده و تعامل کاربر از طریق HTML، CSS و یا JavaScript
۴	Zoom Level	اندازه‌ی بزرگنمایی نقشه
۵	Lat (Latitude)	عرض جغرافیایی
۶	Lon (Longitude)	طول جغرافیایی

زیربخش‌ها (Endpoints)#

سرویس مسیریابی با دریافت مقادیر ورودی، جزییات کاملی درباره‌ی مسیر بهینه بین مبدأ و مقصد و یا مجموعه‌ی نقاط مشخص شده رو ارائه می‌ده. این داده‌ها شامل مواردی همچون مسیر به همراه جزئیات معابر، زمان رسیدن به مقصد و طول مسیرهست. زمان رسیدن به مقصد در حال حاضر برای شهر تهران بر اساس داده‌های ترافیکی (ETA) و برای سایر نقاط با درنظرگرفتن حداکثر سرعت معابر محاسبه می‌شه. سرویس مسیریابی برای حالت‌های مختلف تردد و همچنین درنظرگرفتن محدودیت‌های ترافیکی از end-pointهای مختلفی استفاده می‌کنه. از این رو برای هر یک از روش‌های مسیریابی باید درخواست خود رو به یکی از این آدرس‌ها ارسال کنید.

ردیف	نوع مسیر	آدرس endpoint
۱	مسیریابی با خودرو بدون درنظرگرفتن طرح ترافیک	`{route/v1/driving/{coordinates/`
۲	مسیریابی با خودرو با درنظرگرفتن طرح ترافیک	`{tarh/v1/driving/{coordinates/`
۳	مسیریابی با خودرو با درنظرگرفتن طرح زوج و فرد	`{zojofard/v1/driving/{coordinates/`
۴	مسیریابی با دوچرخه	`{bicycle/v1/driving/{coordinates/`
۵	مسیریابی پیاده	`{foot/v1/driving/{coordinates/`

نکته 🚧
مسیریابی با اعمال محدودیت طرح ترافیک برای شهرهای زیر در دسترس است:
• اصفهان
• تبریز
• تهران
• کرج
• مشهد

نکته 🚧
مسیریابی با اعمال محدودیت طرح زوج و فرد برای شهرهای زیر در دسترس است:
• تهران

پارامترهای ورودی#

API مسیریابی مپ به‌صورت Restful توسعه داده‌شده و از انعطاف‌پذیری بسیار بالایی برای انواع روش‌های پیاده‌سازی در محیط‌های مختلف برخوردار هستش. برای پیاده‌سازی این سرویس لازم است پارامترهای زیر به‌عنوان مقادیر ورودی در اختیار سرویس مسیریابی قرار گیرد:

ردیف	پارامترهای ورودی	نوع پارامتر	توضیحات	مقادیر قابل دریافت	جنس پارامتر	نحوه‌ی ارسال
۱	x-api-key *	اجباری	کلیدی اختصاصی دسترسی به سرویس‌های مپ (API Key)	API Key اختصاصی معتبر	string	Header
۲	coordinates*	اجباری	مختصات نقاط مبدا و مقصد به صورت یک یا چند نقطه به صورت ترتیبی و یا یک polyline	آرایه‌ای از مختصات به صورت lat, lon یا یک polyline	string	path
۳	alternatives	اختیاری	ارائه مسیر جایگزین	true/false	boolean	query
۴	steps	اختیاری	دریافت جزییات معابر مسیر به صورت geohash	true/false	boolean	query
۵	overview	اختیاری	ساده‌سازی جزییات نمایش مسیر در بزرگنمایی‌های پایین	full/simplified/false	string	query
۶	geometries	اختیاری	انتخاب فرمت خروجی مسیر	polyline (default), polyline6 , geojson	string	query

نکته 🚧
اگر API Key اختصاصی خودتون رو دریافت نکرده‌اید کافیه به صورت رایگان ثبت نام و با ساخت پروژه جدید API Key اختصاصی دریافت نمایید.

نکته 🚧
ساختار ورود مختصات دو نقطه در coordinates به صورت ترتیبی زیر است:
origin_longitude,origin_latitude; destination_longitude,destination_latitude

نکته 🚧
ساختار ورود مختصات x نقطه در coordinates به صورت ترتیبی زیر است:

origin_longitude,origin_latitude; destination1_longitude,destination1_latitude; destination2_longitude,destination2_latitude; . . . ; destinationx_longitude,destinationx_latitude;

نکته 🚧
ساختار ورود مختصات مجموعه‌ای از نقاط به صورت polyline به شکل رو‌به‌رو است:
Polyline: polyline(ofp_Ik_vpAilAyu@te@g`E)

پارامترهای خروجی#

ردیف	پارامتر خروجی	توضیحات	جنس پارامتر
۱	code	کد پاسخ که نشانگر ساختار اطلاعات ارسال شده یا پاسخ دریافتی است	string
۲	routes	جزئیات مسیر بهینه	object
۳	waypoints	نقاط ابتدایی و انتهایی مسیر	object
۴	routes.distance	مسافت کل	numeric
۵	routes.duration	زمان کل	numeric
۶	routes.legs.steps	گام‌های مسیر	object
۷	routes.legs.summary	خلاصه متن آدرس مسیر	text

Swagger#

Postman#

فایل Postman این API را با کلیک روی گزینه‌ی زیر دریافت کنید.

دانلود