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

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

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

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

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

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

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

نوع بینش

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

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

نکته: اگر INSIGHT_PLACES را انتخاب کنید، API مربوط به Places Aggregate فقط در صورتی که count ۱۰۰ یا کمتر باشد، شناسه‌های مکان را برمی‌گرداند.

فیلترها

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

فیلتر مکان

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

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

مهم: مساحت هر فیلتر مکان باید بین ۱۵۵۶.۸۶ متر مربع (تقریباً به اندازه یک بلوک شهری کوچک) و ۲ تریلیون متر مربع (تقریباً به اندازه آلاسکا) باشد. درخواست‌هایی که مساحت آنها خارج از این محدوده باشد، خطای INVALID_ARGUMENT را برمی‌گردانند.

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

دایره

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

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

منطقه

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

مهم: هنگام استفاده از فیلتر region با نوع بینش INSIGHT_PLACES ، درخواست‌هایی که شامل مناطق مورد مناقشه هستند، به طور خودکار رد می‌شوند تا از صحت و بی‌طرفی سرویس‌های گوگل اطمینان حاصل شود. مناطق مورد مناقشه مناطقی با مرزهای متضاد یا ادعاهای ارضی توسط کشورها یا نهادهای مختلف هستند. مرزهای مورد مناقشه به صورت خط خاکستری نقطه‌چین در نقشه‌های گوگل نمایش داده می‌شوند.

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

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

• انواع مناطقی که آنقدر بزرگ هستند که منجر به تأخیر زیاد می‌شوند.
• انواع ناحیه‌ای که آنقدر کوچک هستند که رعایت حریم خصوصی را به خطر می‌اندازند.

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

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

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

توجه: حتی برخی از مکان‌هایی که در بالا ذکر نشده‌اند، در صورت نداشتن هندسه چندضلعی خوش‌تعریف، ممکن است رد شوند. این امر بیشتر در مورد انواعی مانند neighborhood ، locality ، sublocality و انواع شماره‌گذاری شده آن ( sublocality_level_1 ، sublocality_level_2 ، sublocality_level_3 ، sublocality_level_4 ) رایج است. در این حالت، کد خطای ۴۰۰ بازگردانده می‌شود.

منطقه سفارشی

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

مهم: مختصاتی که رئوس چندضلعی را تعریف می‌کنند باید به ترتیب خلاف جهت عقربه‌های ساعت فهرست شوند. این از قرارداد استاندارد صنعتی برای تعریف چندضلعی‌ها پیروی می‌کند، که در آن ترتیب خلاف جهت عقربه‌های ساعت نشان می‌دهد که داخل چندضلعی در سمت چپ لبه‌های مرزی قرار دارد.

مهم: نواحی سفارشی باید ۷۰۰۰ رأس یا کمتر داشته باشند.

می‌توانید بازدید کنید برای رسم یک چندضلعی سفارشی و وارد کردن مختصات آن در درخواست، به 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 در بخش Place Types for the 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 برگردانده می‌شود.