تعریف سرویس#
سرویس حصار جغرافیایی (Geofencing) یک سرویس ویژه برای ایجاد ناحیه‌های جغرافیایی اختصاصی به‌صورت Polygon هست. با استفاده از این سرویس می‌توان وضعیت یک نقطه‌ی جغرافیایی نسبت به پلی‌گون‌های ایجاد شده رو مشخص کرد یعنی یک نقطه می‌تواند داخل یک یا چند پلی‌گون قرار گرفته باشد یا خارج از کلیه ناحیه‌های ایجاد شده باشد. دسترسی به این سرویس از طریق API حصار جغرافیایی مپ که بر اساس معماری Restful طراحی شده مقدور شده است.
اصطلاحات کاربردی#
| ردیف | نام اصطلاح | شرح اصطلاح |
|---|---|---|
| ۱ | JSON | این عبارت مخفف JavaScript Object Notation بوده و استاندارد متن‌باز برای انتقال داده است به‌طوری که قابلیت خواندن توسط انسان را نیز داشته باشد |
| ۲ | GeoJSON | یک استاندارد باز برای ارائه عوارض ساده‌ی جغرافیایی در کنار ویژگی‌های غیرجغرافیایی براساس ساختار JSON – اطلاعات بیشتر |
| ۳ | Geofence | منظور از خود geofence محدوده‌ای است که کاربر نیاز به تشخیص آن دارد تا محدودیت‌هایی بر روی آن اعمال کند (به‌عنوان‌مثال می‌خواهید ناوگان حمل‌ونقل از شهر تهران خارج نشود) |
زیربخش‌ها (Endpoints)#
این سرویس با بررسی وضعیت مختصات نقطه‌ی مشخص شده نسبت به محدوده‌ها یا پلی‌گون‌های بارگذاری شده، مشخص می‌کند که آیا این نقطه در یک یا چند پلی‌گون بارگذاری شده وجود دارد یا خارج از کلیه‌ی ناحیه‌های تعریف شده است. از آنجایی که استفاده از این سرویس دو مرحله دارد:
- مرحله‌ی اول: بارگذاری پلی‌گون‌های مربوط به نواحی اختصاصی شما
- مرحله‌ی دوم: مشخص کردن وضعیت یک مختصات جغرافیایی نسبت به ناحیه‌های بارگذاری شده
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 |
Swagger#
Postman#
فایل Postman این API را با کلیک روی گزینه‌ی زیر دریافت کنید.