درخواست پارامترها

این سند پارامترهای درخواست را برای Places Insights API توصیف می‌کند و شامل اطلاعات آماری و بهترین روش‌ها برای استفاده از این سرویس است.

Places Insights API به شما امکان می دهد چندین عملکرد کلیدی را انجام دهید:

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

پارامترهای مورد نیاز

این بخش پارامترهای مورد نیاز را هنگام صدور درخواست به Places Insights API پوشش می دهد. هر درخواست باید موارد زیر را ارائه کند:

• یک نوع بینش
• فیلتر مکان و نوع فیلتر.

نوع بینش

نوع بینش هایی را که می خواهید محاسبه کنید مشخص می کند. انواع بینش زیر پشتیبانی می شوند:

• INSIGHT_COUNT : تعداد مکان های مطابق با معیارهای فیلتر را برمی گرداند.

• INSIGHT_PLACES : شناسه‌های مکان مطابق با معیارهای فیلتر را برمی‌گرداند.

  توجه : اگر INSIGHT_PLACES را انتخاب کنید، API Places Insights فقط در صورتی شناسه مکان را برمی‌گرداند که count آن 100 یا کمتر باشد.

فیلترها

معیارهای فیلتر مکان ها را مشخص می کند. حداقل باید LocationFilter و TypeFilter را مشخص کنید.

فیلتر مکان

فیلتر مکان می تواند یکی از انواع زیر را داشته باشد:

• circle : ناحیه ای را به صورت دایره ای با مرکز و شعاع تعریف می کند.
• region : منطقه را به عنوان منطقه تعریف می کند.
• customArea : یک ناحیه را به عنوان چند ضلعی سفارشی تعریف می کند.

دایره

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

• center :
  • latLng : طول و عرض جغرافیایی مرکز دایره. عرض جغرافیایی باید عددی بین 90-، 90 باشد. طول جغرافیایی باید عددی بین -180 و 180 باشد.
  • place : شناسه مکان مرکز دایره. توجه داشته باشید که فقط مکان های نقطه ای پشتیبانی می شوند. این رشته باید با پیشوند places/ شروع شود.
• radius : شعاع دایره بر حسب متر. این عدد باید مثبت باشد.

منطقه

با ارسال شناسه مکان به پارامتر place ، منطقه خود را به عنوان یک منطقه تعریف کنید. شناسه مکان یک منطقه جغرافیایی را نشان می دهد (مانند ناحیه ای که با چند ضلعی قابل نمایش است). برای مثال، شناسه مکان تامپا، FL places/ChIJ4dG5s4K3wogRY7SWr4kTX6c است. توجه داشته باشید که همه شناسه‌های مکان هندسه کاملاً مشخصی ندارند و در این موارد Places Insights API یک کد خطای 400 را با پیامی که نشان می‌دهد منطقه پشتیبانی نمی‌شود، برمی‌گرداند.

برای تعیین اینکه آیا شناسه مکان نشان دهنده یک نوع مکان پشتیبانی نشده است، شناسه مکان را در یک درخواست API Geocoding ارسال کنید. پاسخ شامل آرایه type است که انواع مکان های مرتبط با شناسه مکان را فهرست می کند، مانند city ، neighborhood یا country .

انواع مکان پشتیبانی نشده عبارتند از:

• establishment : معمولاً مکانی را نشان می دهد که هنوز طبقه بندی نشده است.
• street_number : شماره خیابان دقیق را نشان می دهد.
• floor : نشان دهنده طبقه یک ساختمان است.
• post_box : نشان دهنده یک صندوق پستی خاص است.
• street_address : نشان دهنده آدرس دقیق خیابان است.
• room : نشان دهنده اتاق یک ساختمان است.
• intersection : نشان دهنده یک تقاطع بزرگ، معمولاً از دو جاده اصلی است.
• landmark : مکان نزدیکی را نشان می دهد که به عنوان مرجع برای کمک به ناوبری استفاده می شود.
• subpremise : یک موجودیت آدرس پذیر را در زیر سطح محل نشان می دهد، مانند یک آپارتمان، واحد یا سوئیت.
• sublocality_level_5 : خاص ترین سطح دانه بندی اجزای آدرس sublocality. معمولاً یک بخش فرعی محله ای بسیار کوچک یا منطقه بیش از حد محلی در یک شهر را نشان می دهد.

منطقه سفارشی

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

می توانید مراجعه کنید https://geojson.io/ برای رسم چند ضلعی سفارشی و وارد کردن آن مختصات در درخواست. یک چند ضلعی باید حداقل 4 مختصات داشته باشد که مختصات اول و آخر یکسان باشند. حداقل 3 مختصات ارائه شده باید منحصر به فرد باشد.

مختصات متوالی یکسان به عنوان یک مختصات واحد در نظر گرفته می شود. با این حال، مختصات تکراری غیر متوالی (به غیر از مختصات اول و آخر یکسان مورد نیاز) منجر به خطا می شود.

علاوه بر این، لبه‌های غیر مجاور اجازه تلاقی ندارند، و یال‌های با طول 180 درجه مجاز نیستند (یعنی رئوس مجاور نمی‌توانند پادپایه باشند).

به عنوان مثال:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

فیلتر را تایپ کنید

انواع مکان هایی را که باید شامل یا حذف شوند را مشخص می کند. برای فهرستی از انواع مکان‌های اولیه و ثانویه که Places Insights API پشتیبانی می‌کند، به جدول A در قسمت Place Types for Places API (جدید) مراجعه کنید. شما باید حداقل یک نوع includedTypes یا includedPrimaryTypes را مشخص کنید.

• includedTypes : فهرست انواع مکان های گنجانده شده.
• excludedTypes : فهرست انواع مکان های حذف شده.
• includedPrimaryTypes : فهرستی از انواع مکان های اولیه گنجانده شده.
• excludedPrimaryTypes : فهرستی از انواع مکان های اصلی حذف شده.

برای کسب اطلاعات بیشتر در مورد نحوه عملکرد فیلترهای نوع و انواع مکان، به فیلترهای نوع بیشتر مراجعه کنید.

پارامترهای اختیاری

این فیلترها اختیاری هستند:

• operatingStatus : وضعیت مکان هایی را که باید شامل یا حذف شوند را مشخص می کند. پیش‌فرض فیلتر کردن بر اساس operatingStatus: OPERATING_STATUS_OPERATIONAL (یک مقدار خاص).
• priceLevels : سطح قیمت مکان ها را مشخص می کند. پیش‌فرض بدون فیلتر (همه سطوح قیمت در نتایج گنجانده شده است).
• ratingFilter : محدوده رتبه بندی مکان ها را مشخص می کند. پیش‌فرض بدون فیلتر (همه رتبه‌بندی‌ها در نتایج گنجانده شده‌اند).

وضعیت عملیاتی

با فیلتر operatingStatus ، می توانید بر اساس وضعیت عملیاتی (مانند عملیاتی یا موقت بسته) فیلتر کنید. اگر فیلتر operatingStatus تنظیم نشده باشد، فقط مکان‌هایی با وضعیت عملیاتی OPERATING_STATUS_OPERATIONAL در نتایج گنجانده می‌شوند.

سطح قیمت

با فیلتر price_levels ، می توانید بر اساس سطح قیمت (مانند رایگان، متوسط ​​یا گران) فیلتر کنید. اگر فیلتر price_levels تنظیم نشده باشد، تمام سطوح قیمت در نتایج گنجانده شده است.

فیلتر رتبه بندی

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

• minRating : حداقل میانگین امتیاز کاربر (بین 1.0 و 5.0).
• maxRating : حداکثر میانگین امتیاز کاربر (بین 1.0 و 5.0).

علاوه بر این، مقدار minRating همیشه باید کمتر یا مساوی با مقدار maxRating باشد. اگر minRating بیشتر از maxRating مشخص شده باشد، یک خطای INVALID_ARGUMENT برگردانده می شود.