• مدیر سایت
• شهریور ۰۹, ۱۳۹۸

متدهای API نقشه نشان (بخش دوم

در مقاله قبل در مورد معرفی وب سرویس نقشه نشان و توضیح متدهای آن (بخش اول) توضیح دادیم در این بخش در مورد متدهای وب سرویس نقشه نشان (بخش دوم) توضیح میدهیم.

سرویس مسریابی با در نظر گرفتن ترافیک

پلتفرم نقشه نشان با بهره‌گیری از داده و مشارکت جامعه کاربران دو میلیونی مسیریاب نشان، تنها ارائه‌دهنده ایرانی سرویس مسیریابی بر اساس دیتای ترافیک آنلاین است.

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

شیوه‌ی فراخوانی:

GET:
https://api.neshan.org/v2/direction?parameters
Headers:
Api-Key: YOUR_API_KEY

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

• origin: مختصات نقطه شروع مسیریابی، این مختصات باید به صورت latitude,longitude باشد که دو عدد با کاما از هم جدا شده‌اند.
• destination: مختصات نقطه پایان مسیریابی که قالب آن مانند نقطه شروع است.
• waypoints: این پارامتر اختیاری بوده و برای مشخص کردن نقاط میانی مسیر استفاده می‌شود. فرمت ارسال هر نقطه میانی به صورت
  latitude,longitude می‌باشد. در صورتی که بیش از یک نقطه میانی دارید با به صورت زیر آن‌ها را با علامت پایت (|) از هم جدا کنید:
  latitude,longitude|latitude,longitude
• avoidTrafficZone: این پارامتر اختیاری بوده و مقادیر آن true یا false می‌تواند باشد. در صورتی که این پارامتر true باشد مسیر از داخل طرح ترافیک عبور نخواهد کرد. همچین در صورتی که مقصد داخل طرح ترافیک باشد هیچ مسیری پیدا نمی‌شود.
• avoidOddEvenZone: این پارامتر اختیاری بوده و مقادیر آن true یا false می‌تواند باشد. در صورتی که این پارامتر true باشد مسیر از داخل طرح زوج و فرد عبور نخواهد کرد. همچین در صورتی که مقصد داخل طرح ترافیک باشد هیچ مسیری پیدا نمی‌شود.
• alternative: این پارامتر اختیاری بوده و مقادیر آن true یا false می‌تواند باشد. در صورتی که این پارامتر true باشد و مسیرهای جایگزین برای نقاط مشخص شده وجود داشته باشد این مسیرها در پاسخ ارائه خواهند شد. (مقدار پیش فرض این پارامتر false است)

با توجه به اینکه نام طرح ترافیک در شهرهای دیگر (غیر از تهران) عموماً یه جای طرح زوج و فرد نیز استفاده می‌شود، چنانچه در سایر شهرها هر یک از پارامترهای avoidTrafficZone و avoidOddEvenZone مقدار true داشته باشند و مقصد درون طرح زوج و فرد آن شهر باشد، سرویس مسیریابی خطای NoRouteFound در پاسخ برمی‌گرداند.

فرمت پاسخ:

“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 استفاده کنید.

توضیحات مرتبط با فیلد maneuver:

• right: گردش به راست
• slight-right: گردش به راست با زاویه کم
• sharp-right: گردش به راست با زاویه تند
• left: گردش به چپ
• slight-left: گردش به چپ با زاویه کم
• sharp-left: گردش به چپ با زاویه تند
• uturn: دور برگردان
• straight: مسیر مستقیم
• exit-rotary: خروجی میدان
• depart: شروع مسیر (مبدا)
• arrive: خاتمه مسیر (مقصد)

سرویس Distance Matrix با در نظر گرفتن ترافیک

پلتفرم نقشه نشان با بهره‌گیری از داده و مشارکت جامعه کاربران دو میلیونی مسیریاب نشان، تنها ارائه‌دهنده ایرانی سرویس ماتریس فاصله بر اساس دیتای ترافیک آنلاین است.

با استفاده از وب‌سرویس ماتریس فاصله (Distance Matrix API) میتوانید فاصله و زمان حرکت میان ماتریسی از نقاط شروع و پایانی را به دست آورید. تمامی فواصل و زمان‌ها با در نظر گرفتن بهترین مسیر بر اساس وضعیت فعلی ترافیک محاسبه می‌شوند.

شیوه‌ی فراخوانی:

GET:
https://api.neshan.org/v1/distance-matrix?origins=36.3177579,59.5323219|36.337115,59.530621&destinations=36.35067,59.5451965|36.337005,59.530021
Headers:
Api-Key: YOUR_API_KEY

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

• origins: لیستی از مختصات نقاط شروعی. هر کدام از این مختصات باید به فرم latitude,longitude باشند که با کاما (,) از یکدیگر جدا شده‌اند. در صورتی که تعداد مختصات بیشتر از یک عدد باشد از علامت پایپ ( | ) برای جداسازی آنها استفاده می‌شود.
• destinations: لیستی از مختصات نقاط پایانی که قالب آن مانند origins است.

فرمت پاسخ:

“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: زمان سفر بین دو نقطه که به دو صورت عددی و قابل خواند ارائه می‌شود. در فرمت عددی مقدار زمان به ثانیه است.

سرویس Map Matching

سرویس نگاشت نقطه بر نقشه (Map Matching API) تعدادی نقاط ورودی را به محتمل‌ترین مسیری که این نقاط نشان‌دهنده آن هستند، نگاشت میکند.

شیوه‌ی فراخوانی:

GET:
https://api.neshan.org/v1/map-matching?path=36.299394,59.606211|36.297950,59.604258|36.297206,59.603507
Headers:
Api-Key: YOUR_API_KEY

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

• path: نقاطی که باید به یک مسیر نگاشت شوند. هر کدام از این نقاط با علامت پایپ ( | ) از یکدیگر جدا شده‌اند.مختصات هر نقطه به فرم latitude,longitude حداقل تعداد نقاط ورودی برابر با 2 است در غیر این صورت خطای 470 برگردانده می‌شود.

فرمت پاسخ:

“snappedPoints”: [
{
“location”: {
“latitude”: 36.299336,
“longitude”: 59.606256
},
“originalIndex”: 0
},
{
“location”: {
“latitude”: 36.297886,
“longitude”: 59.604335
},
“originalIndex”: 1
},
{
“location”: {
“latitude”: 36.297218,
“longitude”: 59.603496
},
“originalIndex”: 2
}
]
}

اجزای این پاسخ بصورت زیر می‌باشند:

• snappedPoints: لیستی از نقاطی است که نقاط ورودی به آنها نگاشت شده‌اند. تعداد این نقاط حداکثر برابر با تعداد نقاط ورودی است. از نقاط ورودی که قابل نگاشت شدن به هیچ مسیری نیستند صرف‌ نظر می‌شود. اجزای هر نقطه به صورت زیر است:هر element به صورت زیر است:
  • location: محل نقطه که با دو مقدار latitude و longitude مشخص می‌شود
  • originalIndex: اندیسی است که مشخص میکند این نقطه نگاشت کدام یک از نقاط ورودی است. شماره اندیس‌ها از 0 شروع میشود و برای n ورودی حداکثر n-1 است.

نکته: در صورتی که تعداد زیادی از نقاط قابلیت نگاشت شدن نداشته باشند خطای 404 برگردانده می‌شود.

در این مقاله در مورد متدهای وب سرویس نقشه نشان (بخش دوم) صحبت کردیم جهت مطالعه کامل مستندات از این لینک اقدام نمایید

• برچسب ها:
• api
• api مسیریاب
• Api نقشه
• api نقشه ایران
• وب سرویس
• وب سرویس مسیریاب
• وب سرویس نقشه
• وب سرویس نقشه ایران