حصار جغرافیایی

سرویس حصار جغرافیایی (Geofencing) یک سرویس ویژه برای ایجاد ناحیه‌های جغرافیایی اختصاصی به‌صورت Polygon هست. با استفاده از این سرویس می‌توان وضعیت یک نقطه‌ی جغرافیایی نسبت به پلی‌گون‌های ایجاد شده رو مشخص کرد یعنی یک نقطه می‌تواند داخل یک یا چند پلی‌گون قرار گرفته باشد یا خارج از کلیه ناحیه‌های ایجاد شده باشد. دسترسی به این سرویس از طریق API حصار جغرافیایی مپ که بر اساس معماری Restful طراحی شده مقدور شده است.

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

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

این سرویس با بررسی وضعیت مختصات نقطه‌ی مشخص شده نسبت به محدوده‌ها یا پلی‌گون‌های بارگذاری شده، مشخص می‌کند که آیا این نقطه در یک یا چند پلی‌گون بارگذاری شده وجود دارد یا خارج از کلیه‌ی ناحیه‌های تعریف شده است. از آنجایی که استفاده از این سرویس دو مرحله دارد:

• مرحله‌ی اول: بارگذاری پلی‌گون‌های مربوط به نواحی اختصاصی شما
  • در این مرحله امکان افزودن چندین فایل جئومتری را دارید. با استفاده endpoint ایجاد نواحی می‌توانید ناحیه‌های خود را مدیریت کنید (مشاهده، افزودن و حذف).
• مرحله‌ی دوم: مشخص کردن وضعیت یک مختصات جغرافیایی نسبت به ناحیه‌های بارگذاری شده
  • در این مرحله با فرستادن مختصات نقطه‌ی مدنظر، درصورت شامل بودن در هر یک از جئومتری‌ها اطلاعات آن جئومتری برگشت داده خواهد شد. در نتیجه درصورتی‌که اطلاعات جئومتری‌ای برگشت داده نشود، به‌معنی عدم شامل بودن مختصات ورودی در آن است. همچنین اگر هیچ جئومتری شامل مختصات نباشد پاسخ برابر NotFound خواهد بود.

endpointها به‌صورت زیر هستش که در بخش پارامترهای ورودی شرح توضیحات آن آورده شده.  

ردیف	نوع سرویس	آدرس endpoint
۱	حصار جغرافیایی (Geofencing) / ایجاد نواحی	/geofence/stages/
۲	حصار جغرافیایی (Geofencing) / بررسی وضعیت نقطه نسبت به محدوده‌ها	/geofence/boundaries/

استفاده از این سرویس دو مرحله دارد، گام نخست بارگذاری پلی‌گون‌های مربوط به نواحی اختصاصی شما و گام دوم، مشخص کردن وضعیت یک مختصات جغرافیایی نسبت به ناحیه‌های بارگذاری شده است.

مرحله اول با توجه به این ساختار، ورود اطلاعات مربوط به نواحی به‌صورت زیر انجام می‌شود: 

ردیف	پارامترهای ورودی	نوع پارامتر	توضیحات	مقادیر قابل دریافت	جنس پارامتر	نحوه‌ی ارسال
۱	x-api-key *	اجباری	کلیدی اختصاصی دسترسی به سرویس‌های مپ (API Key)	API Key اختصاصی معتبر	string	Header
۲	polygons*	اجباری	فایل پلی گون‌های ناحیه‌بندی	فایل GeoJSON	file	formData

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

نکته 🚧
برای ساخت پلی‌گون تستی می‌تونید از سایت geojson.io استفاده کنید.

مرحله دوم بعد از بارگذاری محدوده‌ها، در این مرحله می‌تونید با مشخص کردن یک مختصات جغرافیایی وضعیت این نقطه را نسبت به محدوده‌های بارگذاری شده مشخص کنید.

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

خروجی گام نخست (بارگذاری ناحیه‌ها) شامل پیام موفق بودن عملیات یا مشکل داشتن فایل بارگذاری شده است. خروجی گام دوم API حصار جغرافیایی شامل موارد زیر است:

ردیف	پارامتر خروجی	توضیحات	جنس پارامتر
۱	odata.count	تعداد نتایج دریافتی که نشانگر این است که مختصات دریافتی در چه تعداد پلی‌گون بارگذاری شده قرار گرفته است	numeric
۲	id	Unique ID (شناسه)	numeric
۳	boundary	مشخصات پلی‌گون(ها)	geojson
۴	meta	سایر داده‌های مربوط به پلی‌گون(ها) که در GeoJSON ورودی وجود داشته است	object

فایل Postman این API را با کلیک روی گزینه‌ی زیر دریافت کنید.