آدرس‌یابی

تعریف سرویس#

سرویس آدرس‌یابی (Reverse Geocoding) یکی از پرکاربردترین سرویس‌های نقشه مپ هست. عملکرد این سرویس تبدیل مختصات جغرافیایی به آدرس متنی است تا بتوان به‌راحتی با انتخاب یک نقطه بر روی نقشه آدرسی قابل فهم و کاربردی از آن داشته باشیم. کاربردهای فراوانی برای این سرویس وجود دارد؛ مانند مشخص کردن محل مشتری، ارائه‌ی سرویس و… به نحوی که با انتخاب محل موردنظر آدرس قابل فهم توسط کاربر داشته باشیم. از آنجا که خروجی این سرویس به‌صورت یک JSON با جزییات فراوان هست، این امکان برای توسعه‌دهندگان فراهم است تا ساختار آدرس اختصاصی خود را ایجاد کرده یا از هر یک از خروجی‌ها به‌صورت مستقل یا ترکیبی به‌عنوان یک ضابطه‌ی مشخص استفاده کنند. به‌عنوان مثال اگر می‌خواهید از شهر کاربر داده‌های مشخصی برای وی نمایش داده شود، کافی است از طریق این سرویس و دریافت مختصات کاربر، خروجی شهر را به‌عنوان ورودی شاخص برای نمایش اطلاعات بعدی در نظر بگیرید. دسترسی به این سرویس از طریق API آدرس‌یابی مپ که با معماری Restful طراحی شده مقدور شده است. سرویس آدرس‌یابی امکانات متنوعی برای توسعه‌دهندگان فراهم می‌آورد تا بتوانند جزییات مختلفی را از مختصات ورودی دریافت کنند.

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

ردیف نام اصطلاح شرح اصطلاح
۱ JSON این عبارت مخفف JavaScript Object Notation بوده و استاندارد متن‌باز برای انتقال داده است به‌طوری که قابلیت خواندن توسط انسان را نیز داشته باشد
۲ GeoJSON یک استاندارد باز برای ارائه عوارض ساده‌ی جغرافیایی در کنار ویژگی‌های غیرجغرافیایی براساس ساختار JSON – اطلاعات بیشتر

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

همانطورکه قبلاً هم توضیح دادیم عملکرد سرویس آدرس‌یابی تبدیل مختصات جغرافیایی به آدرس متنی است. براین‌اساس با مشخص کردن مختصات ورودی امکان استفاده از دو حالت در آدرس‌یابی امکان‌پذیر خواهد بود: آدرس‌یابی کامل (Full Reverse Geocoding) و آدرس‌یابی سریع (Fast Reverse Geocoding). تفاوت این دو نوع مختلف آدرس‌یابی در جزییات و سرعت پاسخ می‌باشد. در حالت کامل در کنار جزییات آدرس اگر مختصات مربوط به مکان ثبت شده بروی نقشه باشد، نام محل ثبت شده نیز در پاسخ ارسال می‌گردد در حالی که در حالت سریع این ویژگی وجود ندارد. مزیت اصلی آدرس‌یابی سریع در سرعت بیشتر آن است به‌طوری‌که زمان پاسخ (Response Time) آن حدود ۲۰ms است در حالی که در حالت آدرس‌یابی کامل این زمان حدود ۷۰ms است.

ردیف نوع سرویس آدرس endpoint
۱ آدرس‌یابی کامل (Full Reverse Geocoding) /reverse/
۲ آدرس‌یابی سریع (Fast Reverse Geocoding) /fast-reverse/

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

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

ردیف پارامترهای ورودی نوع پارامتر توضیحات مقادیر قابل دریافت جنس پارامتر نحوه‌ی ارسال
۱ x-api-key * اجباری کلیدی اختصاصی دسترسی به سرویس‌های مپ (API Key) API Key اختصاصی معتبر string Header
۲ lat* اجباری عرض جغرافیایی عرض جغرافیایی number query
۳ lon* اجباری طول جغرافیایی طول جغرافیایی number query

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

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

خروجی 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 پلاک پلاک ثبتی numeric
۱۷ postal_code کدپستی –
۱۸ geom شامل مختصات جغرافیایی و type می‌باشد مختصات جغرافیایی, نوع موجودیت جغرافیایی geojson
۱۹ type نوع موجودیت جغرافیایی point (این مقدار ثابت است) string
۲۰ coordinates مختصات جغرافیایی طول و عرض جغرافیایی نقطه string

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

Swagger#

Postman#

فایل Postman دو حالت این API را از بخش زیر دریافت کنید.

Reverse


دانلود

Fast_Reverse


دانلود

محبوب‌ترین جست‌وجوها:مستندات, مثال‌ها, استایل‌های نقشهٔ مپ