آدرس‌یابی

تعریف سرویس#

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

مثال استفاده از این سرویس در SDK وب مپ را می‌توانید در اینجا مشاهده کنید.

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

ردیف	نام اصطلاح	شرح اصطلاح
۱	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