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

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

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

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

پارامترهای الزامی

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

• نوعی از اطلاعات آماری.
• فیلتر مکان و فیلتر نوع.

نوع بینش‌های تحلیلی

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

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

فیلترها

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

فیلتر مکان

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

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

دایره

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

• center:
  • ‫latLng: عرض و طول جغرافیایی مرکز دایره. عرض‌های جغرافیایی باید عددی بین ۹۰- و ۹۰ (شامل این دو عدد) باشد. طول جغرافیایی باید عددی بین ۱۸۰- و ۱۸۰ باشد.
  • ‫place: شناسه مکان مرکز دایره. توجه داشته باشید که فقط مکان‌های نقطه‌ای پشتیبانی می‌شود. این رشته باید با پیشوند places/ شروع شود.
• ‫radius: شعاع دایره به متر. این عدد باید مثبت باشد.

منطقه

منطقه‌تان را با ارسال شناسه مکان به پارامتر place به‌عنوان ناحیه تعریف کنید. شناسه مکان نشان‌دهنده یک منطقه جغرافیایی است (مانند منطقه‌ای که با چندضلعی قابل‌نمایش است). برای مثال، شناسه مکان تمپا، فلوریدا places/ChIJ4dG5s4K3wogRY7SWr4kTX6c است. توجه داشته باشید که همه شناسه‌های مکان هندسه مشخصی ندارند و در این موارد، Places Aggregate API کد خطای ۴۰۰ را با پیامی برمی‌گرداند که نشان می‌دهد منطقه پشتیبانی نمی‌شود. علاوه‌براین، برای مناطق جغرافیایی پیچیده، بهینه‌سازی‌های پردازش داخلی ممکن است منجر به تقریب کمی بیشتر از مساحت (تا ۲-۳٪) شود که منطقه را نشان می‌دهد.

برای تعیین اینکه آیا شناسه جا نشان‌دهنده نوع مکان پشتیبانی‌نشده است یا نه، شناسه جا را در درخواست Geocoding API ارسال کنید. پاسخ شامل آرایه type است که انواع مکان‌های مرتبط با شناسه مکان را فهرست می‌کند، مانند locality، neighborhood، یا country. اگر هرکدام از انواع مکان با این فهرست مطابقت داشته باشد، آن مکان برای فیلتر کردن منطقه رد خواهد شد.

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

• establishment: معمولاً نشان‌دهنده مکانی است که هنوز دسته‌بندی نشده است.
• intersection: نشان‌دهنده تقاطع اصلی است، معمولاً تقاطع دو جاده اصلی.
• ‫subpremise: نشان‌دهنده نهاد قابل‌آدرس‌دهی زیر سطح محل است، مانند آپارتمان، واحد، یا سوئیت.

منطقه سفارشی

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

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

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

علاوه‌براین، اضلاع غیرمجاور نباید تلاقی کنند و اضلاع با طول ۱۸۰ درجه مجاز نیستند (یعنی رئوس مجاور نمی‌توانند متقابل باشند).

برای مثال:

"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 Aggregate API پشتیبانی می‌کند، به جدول A در بخش انواع مکان برای Places API (جدید) مراجعه کنید. باید حداقل یک نوع includedTypes یا includedPrimaryTypes مشخص کنید.

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

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

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

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

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

وضعیت فعالیت

با فیلتر operatingStatus، می‌توانید براساس وضعیت فعالیت مثل OPERATIONAL یا TEMPORARILY_CLOSED فیلتر کنید. رفتار فیلتر operatingStatus به این صورت است:

• اگر فیلتری ارائه نشده باشد، فقط مکان‌هایی که وضعیت فعالیت آن‌ها OPERATING_STATUS_OPERATIONAL است در نتایج گنجانده می‌شوند.
• اگر یک یا چند فیلتر ارائه شده است، باید مقادیر معتبر وضعیت فعالیت را مشخص کنید (OPERATING_STATUS_OPERATIONAL، OPERATING_STATUS_PERMANENTLY_CLOSED، یا OPERATING_STATUS_TEMPORARILY_CLOSED).

سطح قیمت‌ها

با فیلتر priceLevels، می‌توانید مکان‌ها را براساس سطح قیمت آن‌ها فیلتر کنید. مقادیر معتبر سطح قیمت عبارتند از: PRICE_LEVEL_FREE، PRICE_LEVEL_INEXPENSIVE، PRICE_LEVEL_MODERATE، PRICE_LEVEL_EXPENSIVE، و PRICE_LEVEL_VERY_EXPENSIVE.

رفتار فیلتر priceLevels به‌صورت زیر است:

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

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

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

• ‫minRating: حداقل میانگین رده‌بندی کاربر (بین ۱٫۰ و ۵٫۰).
• ‫maxRating: حداکثر میانگین رده‌بندی کاربر (بین ۱٫۰ و ۵٫۰).

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