متدهای API نقشه نشان (بخش اول)
در مطلب قبل له معرفی وب سرویس نقشه نشان پرداختیم در این مقاله در مورد متدهای وب سرویس نقشه نشان (بخش اول) توضیح خواهیم داد.
استفاده از Neshan Maps API
۱- اولین قدم ثبتنام و دریافت Api Key برای اپلیکیشنی است که قصد دارید در آن از Map Api نشان در استفاده کنید. کافیست از این لینک فرم مربوطه را تکمیل کنید تا بلافاصله Api Key به ایمیل شما ارسال گردد.
۲- Api Key دریافتی از پنل توسعهدهندگان نشان را به صورتی که در ادامه مشاهده میکنید از طریق کلید Api-Key در header درخواست سرویس بگنجانید.
۳- درخواست خود را با توجه به پارامترهایی که مربوط به سرویس موردنظرتان است با متد GET فراخوانی کنید.
۴- چنانچه درخواست شما با موفقیت پردازش و پاسخ داده شود، خروجی با فرمت JSON دریافت خواهید کرد و چنانچه به هر دلیل خطایی رخ دهد، کد خطا بصورت HTTP Status Code و نوع آن با فرمت JSON ارسال میگردد. کدهای خطای احتمالی نیز در در این صفحه به صورت کامل توضیح داده شدهاند.
سرویس جستجوی مکان محور
برای جستجوی نام خیابانها، نامهای قدیمی، اماکن و کسب و کارهای ثبتشده بر روی نقشه (Location Based Search API) میتوانید از وبسرویس جستجوی نشان استفاده کنید. این وبسرویس بهترین نتایج ممکن را با توجه به نقطهی مرجع (طول و عرض جغرافیایی مکانی که جستجو بایستی حول آن انجام شود) در اختیار شما قرار میدهد. در پاسخ به هر درخواست جستجو حداکثر ۳۰ نتیجهی مرتبط توسط وبسرویس برگردانده میشود
وب سرویس جستجوی مکان محور نقشه نشان یکی از کاملترین سرویسهای جستجو مبتنی بر موقعیت ایرانی میباشد. این سرویس با پشتیبانی کامل از زبان فارسی و نگارشهای مختلف از حروف فارسی، با توجه به موقعیت جغرافیایی مورد نظر شما (نقطه مرجع) بهترین نتایج را به صورت مرتبشده بر اساس فاصله تا آن نقطه مرجع در پاسخ باز میگرداند.
نقطه مرجع در این سرویس میتواند موقعیت جاری کاربر یا مرکز نقشهای که کاربر مشاهده میکند باشد. این نقطه باید بهصورت طول و عرض جغرافیایی (Latitude & Longitude) ارسال گردد.
پارامتر نقطهی مرجع به شما کمک میکند نتایج بهتری را در خروجی داشته باشید. با توجه به معماری سرویس جستجوی مکانمحور نشان، شما محدودیتی در دریافت نتایج بسیار دور از نقطهی مرجع (به عنوان مثال در شهری دیگر) را نیز نخواهید داشت. این نقطه میتواند مکان جغرافیایی کاربر نهایی شما یا مرکز نقشهای که مشاهده میکند باشد.
شیوهی فراخوانی:
GET:
https://api.neshan.org/v1/search?term=YOUR_SEARCH_TERM&lat=LATITUDE&lng=LONGITUDE
Headers:
Api-Key: YOUR_API_KEY
پارامترهای ورودی:
- term: عبارت جستجو
- lat: عرض جغرافیایی مرکز جستجو (latitude)
- lng: طول جغرافیایی مرکز جستجو (longitude)
فرمت پاسخ:
{
“count”: 1,
“items”: [
{
“title”: “حرم مطهر امام رضا (ع)”,
“address”: “مشهد، خراسان رضوی”,
“neighbourhood”: “حرم مطهر”,
“region”: “مشهد، خراسان رضوی”,
“type”: “religious”,
“category”: “place”,
“location”: {
“x”: 59.6157432,
“y”: 36.2880443
}
}
]
}
اجزای این پاسخ بصورت زیر میباشند:
- count: تعداد رکوردهای یافت شده
- items: آرایهای از رکوردهای یافت شده که اجزای آن بصورت زیر میباشند:
- title: عنوان نتیجه پیدا شده
- address: آدرس مکان یا معبر
- neighbourhood: نام محله (در صورت وجود)
- region: نام شهر و استان که با کاما به هم متصل شدهاند
- type: نوع رکورد یافتشده (به عنوان مثال مسجد، خیابان، بزگرراه، میدان و …)
- category: دستهبندی اصلی رکورد یافت شده که یکی از مقادیر زیر میتواند باشد:
- place: برای مکان
- municipal: برای خیابان
- region: برای شهر، روستا و استانها
- location: نقطهی جغرافیایی رکورد یافتشده که از دو بخش تشکیل شدهاست:
- x: طول جغرافیایی (longitude)
- y: عرض جغرافیایی (latitude)
سرویس Reverse Geocoding
از طریق وبسرویس تبدیلنقطهی جغرافیایی به آدرس (Reverse Geocoding API ) به سادگی میتوانید با ارسال طول و عرض جغرافیایی موردنظر، اطلاعاتی نظیر آدرس دقیق، نام محله، منطقهی شهرداری، در طرح ترافیک بودن (تهران) و در طرح زوج و فرد بودن (تهران، مشهد، اصفهان) آن نقطه را دریافت کنید.
شیوهی فراخوانی:
GET:
https://api.neshan.org/v2/reverse?lat=LATITUDE&lng=LONGITUDE
Headers:
Api-Key: YOUR_API_KEY
پارامترهای ورودی:
- lat: عرض جغرافیایی (latitude)
- lng: طول جغرافیایی (longitude)
فرمت پاسخ:
“status”: “OK”,
“formatted_address”: “تهران، تهران، فاطمی، حجاب، سازمان آب، نزدیک به عبدالله زاده”,
“route_name”: “سازمان آب”,
“route_type”: “secondary”,
“neighbourhood”: “فاطمی”,
“city”: “تهران”,
“state”: “تهران”,
“place”: null,
“municipality_zone”: “6”,
“in_traffic_zone”: true,
“in_odd_even_zone”: true,
“addresses”: [
{
“formatted”: “حجاب، سازمان آب، نزدیک به عبدالله زاده”,
“components”: [
{
“name”: “حجاب”,
“type”: “primary”
},
{
“name”: “سازمان آب”,
“type”: “secondary”
}
]
}
]
}
اجزای این پاسخ بصورت زیر میباشند:
- status: در صورت موفقیتآمیز بودن اجرای درخواست مقدار OK در آن قرار میگیرد.
- formatted_address: آدرس کامل موقعیت مورد نظر شامل استان، شهر، محله و خیابان
- route_name: نام خیابان انتهایی آدرس
- route_type: نوع خیابان انتهایی آدرس
- neighbourhood: نام محله (در صورت وجود)
- city: نام شهر
- state: نام استان
- place: نام مکان عمومی که موقعیت انتخابی در آن قرار گرفته است (در صورت وجود)
- municipality_zone: منطقه شهرداری (در صورت وجود)
- in_traffic_zone: آیا نقطهی موردنظر در طرح ترافیک قرار دارد؟
- in_odd_even_zone: ایا نقطهی موردنظر در طرح زوج و فرد قرار دارد؟
- addresses: آرایهای از آدرسهای تولیدشده برای موقعیت انتخابی
در این مقاله در مورد متدهای وب سرویس نقشه نشان (بخش اول) صحبت کردیم در مقاله بعد در مورد متدهای وب سرویس نقشه نشان (بخش دوم) صحبت خواهیم کرد.