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

این سند پارامترهای درخواست را برای 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 place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark subpremise
منطقه سفارشی

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

برای رسم چند ضلعی سفارشی و وارد کردن آن مختصات در درخواست می توانید به 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 : محدوده رتبه بندی مکان ها را مشخص می کند. پیش‌فرض بدون فیلتر (همه رتبه‌بندی‌ها در نتایج گنجانده شده‌اند).

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

فیلتر بر اساس وضعیت عملیاتی (مانند عملیاتی یا موقت بسته).

سطح قیمت

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

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

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

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