بررسی متد آدرس یابی وب سرویس نقشه map.ir
در مطالب قبل در مورد معرفی وب سرویس نقشه map.ir و همچنین معرفی متدهای آن صحبت کردیم در این مطلب در مورد بررسی متد آدرس یابی API نقشه توضیح میدهیم
آدرس‌یابی
سرویس آدرس‌یابی (Reverse Geocoding) یکی از پرکاربردترین سرویس‌های نقشه می‌باشد. عملکرد این سرویس تبدیل مختصات جغرافیایی به آدرس متنی است تا بتوان به‌راحتی با انتخاب یک نقطه به روی نقشه آدرسی قابل فهم و کاربردی داشته باشیم. کاربردهای فراوانی برای این سرویس وجود دارد مانند مشخص کردن محل مشتری، ارائه سرویس و… به نحوی که با انتخاب محل مورد نظر آدرس قابل فهم توسط کاربر داشته باشیم. از آنجا که خروجی این سرویس به صورت یک JSON با جزییات فراوان می‌باشد این امکان برای توسعه دهندگان فراهم است تا ساختار آدرس اختصاصی خود را ایجاد کرده یا از هر یک از خروجی‌ها به صورت مستقل یا ترکیبی به عنوان یک ضابطه مشخص استفاده کنند. به عنوان مثال اگر می‌خواهید از شهر کاربر داده‌های مشخصی برای وی نمایش داده شود کافی است از طریق این سرویس و دریافت مختصات کاربر، خروجی شهر را به عنوان ورودی شاخص برای نمایش اطلاعات بعدی در نظر بگیرید.
دسترسی به این سرویس از طریق API آدرس‌یابی مپ که با معماری Restful طراحی شده مقدور می‌باشد. سرویس آدرس‌یابی امکانات متنوعی برای توسعه دهندگان فراهم می‌آورد تا بتوانید جزییات مختلفی را از مختصات ورودی دریافت کنند.
اصطلاحات کاربردی
| JSON | این عبارت مخفف JavaScript Object Notation بوده و استاندارد متن باز برای انتقال داده است به طوری که قابلیت خواندن توسط انسان را نیز داشته باشد |
| GeoJSON | یک استاندارد باز برای ارائه عوارض ساده جغرافیایی در کنار ویژگی‌های غیرجغرافیایی بر اساس ساختار JSON است. |
ساختار استفاده
API آدرس‌یابی یا همان Reverse Geocoding مپ به صورت Restful توسعه داده‌شده است و از انعطاف پذیری بسیار بالایی برای انواع روش‌های پیاده سازی در محیط‌های مختلف برخوردارد است. برای پیاده‌سازی این سرویس لازم است پارامترهای زیر به عنوان مقادیر ورودی در اختیار سرویس آدرس‌یابی قرار گیرد:
| پارامترهای ورودی | نوع پارامتر | توضیحات | مقادیر قابل دریافت | جنس پارامتر | نحوه ارسال |
| x-api-key * | اجباری | کلیدی اختصاصی دسترسی به سرویس‌های مپ (API Key) | API Key اختصاصی معتبر | string | Header |
| lat * | اجباری | مختصات عرض جغرافیایی | مختصات با استاندارد | number | query |
| lon* | اجباری | مختصات طول جغرافیایی | مختصات با استاندارد | number | query |
نکته:
اگر API Key اختصاصی خودتون رو دریافت نکرده‌اید کافیه به صورت رایگان ثبت نام و با ساخت پروژه جدید API Key اختصاصی دریافت نمایید.
عملکرد سرویس
همانطور که قبلا هم توضیح دادیم عملکرد سرویس آدرس‌یابی تبدیل مختصات جغرافیایی به آدرس متنی است. بر این اساس با مشخص کردن مختصات ورودی امکان استفاده از دو حالت در آدرس‌یابی امکان‌پذیر خواهد بود: آدرس‌یابی کامل (Full Reverse Geocoding) و آدرس‌یابی سریع (Fast Reverse Geocoding). تفاوت این دو نوع مختلف آدرس‌یابی در جزییات و سرعت پاسخ می‌باشد. در حالت کامل در کنار جزییات آدرس اگر مختصات مربوط به مکان ثبت شده بروی نقشه باشد، نام محل ثبت شده نیز در پاسخ ارسال می‌گردد در حالی که در حالت سریع این ویژگی وجود ندارد.مزیت اصلی آدرس‌یابی سریع در سرعت بیشتر آن است به طوری که زمان پاسخ (Response Time) آن حدود 20ms است در حالی که در حالت آدرس‌یابی کامل این زمان حدود 70ms است.
| آدرس‌یابی کامل (Full Reverse Geocoding) | reverse/ |
| آدرس یابی سریع (Fast Reverse Geocoding) | fast-reverse/ |
پارامترهای خروجی
خروجی API آدرس‌یابی مپ به صورت یک JSON شامل موارد زیر می‌باشد.
| پارامترهای خروجی | توضیحات | مقادیر دریافتی | جنس پارامتر |
| address | آدرس کامل به صورت کشور/استان/شهر/منطقه/محله/خیابان اصلی/خیابان‌های واسط/معبر نهایی/نام مکان | آدرس متنی کامل | string |
| postal_address | آدرس پستی سه بخش به شکلشهر/خیابان اصلی/معبر نهایی | آدرس متنی | string |
| address_compact | آدرس متنی خلاصه به صورتشهر/محله/خیابان اصلی/معبر نهایی | آدرس متنی | string |
| last | نام مختصات | نام معبر نهایی/نام مکان | string |
| name | نام مختصات | نام معبر نهایی/نام مکان | string |
| poi | نام مکان ثبت شده روی نقشه | نام مکان | string |
| country | کشور | ایران | string |
| province | استان | نام استان | string |
| county | شهرستان | نام شهرستان | string |
| rural_district | دهستان | نام دهستان | string |
| city | شهر | نام شهر | string |
| village | روستا | نام روستا | string |
| region | منطقه | نام منطقه شهرداری | string |
| neighborhood | محله | نام محله شهرداری | string |
| primary | خیابان اصلی منتهی به مختصات | نام خیابان اصلی | string |
| plaque | پلاک | – | |
| postal_code | کدپستی | – | |
| geom | شامل مختصات جغرافیایی و type می‌باشد | مختصات جغرافیایی, نوع موجودیت جغرافیایی | geojson |
| type | نوع موجودیت جغرافیایی | point (این مقدار ثابت است) | string |
| coordinates | مختصات جغرافیایی | طول و عرض جغرافیایی نقطه | string |
از اونجایی که در خروجی سرویس آدرس‌یابی مشخص است آدرس‌های کامل، پستی و خلاصه به صورت پیش‌فرض در پاسخ وجود دارد اما اگر مایل باشید ساختار اختصاصی آدرس خود را بر اساس نیاز خودتان ایجاد کنید می‌توانید از جزییات مختلف ساختار جدید ایجاد کنید یا از هر یک از بخش‌های خروجی به صورت جداگانه استفاده نمایید.
برای دریافت راهنمای کامل این وب سرویس و متدهای آن از این لینک اقدام نمایید