سرویس جستجوی مکان محور
برای جستجوی نام خیابان‌ها، نام‌های قدیمی، اماکن و کسب و کارهای ثبت‌شده بر روی نقشه (Location Based Search API) میتوانید از وب‌سرویس جستجوی نشان استفاده کنید. این وب‌سرویس بهترین نتایج ممکن را با توجه به نقطه‌ی مرجع (طول و عرض جغرافیایی مکانی که جستجو بایستی حول آن انجام شود) در اختیار شما قرار می‌دهد. در پاسخ به هر درخواست جستجو حداکثر ۳۰ نتیجه‌ی مرتبط توسط وب‌سرویس برگردانده می‌شود. وب سرویس جستجوی مکان محور نقشه نشان یکی از کامل‌ترین سرویس‌های جستجو مبتنی بر موقعیت ایرانی می‌باشد. این سرویس با پشتیبانی کامل از زبان فارسی و نگارش‌های مختلف از حروف فارسی، با توجه به موقعیت جغرافیایی مورد نظر شما (نقطه مرجع) بهترین نتایج را به صورت مرتب‌شده بر اساس فاصله تا آن نقطه مرجع در پاسخ باز می‌گرداند.
نقطه مرجع در این سرویس می‌تواند موقعیت جاری کاربر یا مرکز نقشه‌ای که کاربر مشاهده می‌کند باشد. این نقطه باید به‌صورت طول و عرض جغرافیایی (Latitude & Longitude) ارسال گردد.
فهرست مطالب این صفحه
پارامتر نقطه‌ی مرجع به شما کمک می‌کند نتایج بهتری را در خروجی داشته باشید. با توجه به معماری سرویس جستجوی مکان‌محور نشان، شما محدودیتی در دریافت نتایج بسیار دور از نقطه‌ی مرجع (به عنوان مثال در شهری دیگر) را نیز نخواهید داشت. این نقطه می‌تواند مکان جغرافیایی کاربر نهایی شما یا مرکز نقشه‌ای که مشاهده می‌کند باشد.
شیوه‌ی فراخوانی:
GET:
https://api.neshan.org/v1/search?term=YOUR_SEARCH_TERM&lat=LATITUDE&lng=LONGITUDE
Headers:
Api-Key: YOUR_API_KEYپارامتر های وروردی:
- term: عبارت جستجو
- lat: عرض جغرافیایی مرکز جستجو (latitude)
- lng: طول جغرافیایی مرکز جستجو (longitude)
فرمت پاسخ:
{
"count": 1,
"items": [
{
"title": "حرم مطهر امام رضا (ع)",
"address": "مشهد، خراسان رضوی",
"neighbourhood": "حرم مطهر",
"region": "مشهد، خراسان رضوی",
"type": "religious",
"category": "place",
"location": {
"x": 59.6157432,
"y": 36.2880443
}
}
]
}اجزای این پاسخ بصورت زیر می‌باشند:
- count: تعداد رکوردهای یافت شده
- items: آرایه‌ای از رکوردهای یافت شده که اجزای آن بصورت زیر می‌باشند:
- title: عنوان نتیجه پیدا شده
- address: آدرس مکان یا معبر
- neighbourhood: نام محله (در صورت وجود)
- region: نام شهر و استان که با کاما به هم متصل شده‌اند
- type: نوع رکورد یافت‌شده (به عنوان مثال مسجد، خیابان، بزگرراه، میدان و …)
- category: دسته‌بندی اصلی رکورد یافت شده که یکی از مقادیر زیر می‌تواند باشد:
- place: برای مکان
- municipal: برای خیابان
- region: برای شهر، روستا و استان‌ها
- location: نقطه‌ی جغرافیایی رکورد یافت‌شده که از دو بخش تشکیل شده‌است:
- x: طول جغرافیایی (longitude)
- y: عرض جغرافیایی (latitude)
با فراخوانی این API در صورت وجود اشکال ممکن است، خطاهای زیر در خروجی برای شما ارسال گردند. شناسایی و مدیریت این خطاها می‌تواند به از بروز خطاهای احتمالی در اپلیکیشن شما جلوگیری کند. این خطاها عبارتند از:
470 : CoordinateParseError
چنانچه مختصات جغرافیایی ارسالی معتبر نباشد رخ خواهد داد.
480 : KeyNotFound
در صورتی که در فراخوانی وب‌سرویس از یک Api Key نامتعبر استفاده کنید یا Api Key خود را در header ارسال نکنید رخ خواهد داد.
481 : LimitExceeded
در صورتی که تعداد فراخوانی وب‌سرویس‌ها از میزان مجازی که برای شما تعیین شده‌است عبور کند رخ خواهد داد.
482 : RateExceeded
چنانچه تعداد درخواست وب‌سرویس در دقیقه از حد مجاز عبور کند رخ خواهد داد.
483 : ApiKeyTypeError
کلید دسترسی استفاده شده با سرویس فراخوانی شده همخوانی ندارد. بایستی از کلید دسترسی مرتبط با سرویس موردنظر استفاده کنید.
484 : ApiWhiteListError
با توجه به اسکوپ تعریف‌شده برای این کلید، شما مجاز به استفاده نیستید.
485 : ApiServiceListError
سرویس فراخوانی شده با سرویس‌های تعریف‌شده برای این کلید دسترسی همخوانی ندارد.
500 : GenericError
در صورت بروز خطایی غیر از خطاهای بالا این خطا گزارش می‌شود.
