פרמטרים של בקשות

במסמך הזה מתוארים הפרמטרים של הבקשות ל-Places Aggregate API, ומוצגות תובנות ושיטות מומלצות לשימוש בשירות הזה.

ה-API של Places Aggregate מאפשר לכם לבצע כמה פונקציות מרכזיות:

• ספירת מקומות: קביעת מספר המקומות שתואמים לקריטריונים ספציפיים, כמו סוג המיקום, סטטוס הפעילות, רמת המחיר והדירוגים.
• אחזור פרטים של מקום: קבלת שמות של מקומות שעומדים במסננים שצוינו, ואז אחזור של מידע מפורט יותר באמצעות Places API.
• סינון גמיש: אפשר להחיל מסננים מקיפים כדי לקבל נתונים מצטברים מדויקים. המסננים הזמינים כוללים את האפשרויות הבאות:
  • אזור גיאוגרפי (עיגול, אזור או פוליגון בהתאמה אישית)
  • סוגי מקומות
  • סטטוס פעילות
  • רמות מחירים
  • טווחי דירוגים

פרמטרים נדרשים

בקטע הזה מוסבר על הפרמטרים הנדרשים כששולחים בקשה ל-Places Aggregate API. כל בקשה חייבת לכלול את הפרטים הבאים:

• סוג התובנה.
• מסנן מיקום ומסנן סוג.

סוג התובנה

מציינת את סוג התובנה שרוצים לחשב. אלה סוגי התובנות שנתמכים:

• ‫INSIGHT_COUNT: מחזירה את מספר המקומות שתואמים לקריטריוני הסינון.
• ‫INSIGHT_PLACES: מחזירה את מזהי המקומות שתואמים לקריטריונים של הסינון.

מסננים

מציינת את הקריטריונים לסינון מקומות. צריך לציין לפחות את LocationFilter ואת TypeFilter.

מסנן מיקומים

מסנן מיקום יכול להיות אחד מהסוגים הבאים:

• ‫circle: מגדיר אזור כמעגל עם מרכז ורדיוס.
• ‫region: מגדיר אזור כאזור.
• ‫customArea: הגדרת אזור כמצולע מותאם אישית.

מעגל

אם בוחרים אזור גיאוגרפי בצורת עיגול, צריך לציין center וradius. הערך של center יכול להיות קו רוחב וקו אורך, או מזהה המקום של מרכז העיגול. השיטה הזו מאפשרת סינון מדויק על סמך האזור המעגלי שהגדרתם.

• center:
  • ‫latLng: קו הרוחב וקו האורך של מרכז העיגול. קווי הרוחב חייבים להיות מספר בין ‎-90 ל-90, כולל. קו האורך חייב להיות מספר בין ‎-180 ל-180, כולל.
  • ‫place: מזהה המקום של מרכז המעגל. שימו לב שאפשר להשתמש רק בנקודות של מקומות. המחרוזת הזו חייבת להתחיל בקידומת places/.
• ‫radius: רדיוס העיגול במטרים. המספר הזה חייב להיות חיובי.

אזור

כדי להגדיר את האזור, מעבירים מזהה מקום לפרמטר place. מזהה המקום מייצג אזור גיאוגרפי (כמו אזור שאפשר לייצג באמצעות פוליגון). לדוגמה, מזהה המקום של טמפה, פלורידה הוא places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. שימו לב שלא לכל מזהי המקומות יש גיאומטריה מוגדרת היטב, ובמקרים כאלה Places Aggregate API מחזיר קוד שגיאה 400 עם הודעה שמציינת שהאזור לא אפשרי. בנוסף, באזורים גיאוגרפיים מורכבים, יכול להיות שאופטימיזציות פנימיות של העיבוד יובילו להערכת יתר קלה של האזור (עד 2-3%) שמייצג את האזור.

כדי לדעת אם מזהה מקום מייצג סוג מקום שלא נתמך, צריך להעביר את מזהה המקום בבקשה ל-Geocoding API. התשובה כוללת את מערך type שמפרט את סוגי המקומות שמשויכים למזהה המקום, כמו locality,‏ neighborhood או country. מקום יידחה במסגרת סינון לפי אזור אם אחד מסוגי המקומות שלו תואם לרשימה הזו.

סוגי מקומות שלא נתמכים:

• ‫establishment: בדרך כלל מציין מקום שעוד לא סווג.
• ‫intersection: מציין צומת גדול, בדרך כלל של שני כבישים ראשיים.
• ‫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 Aggregate API מופיעה בטבלה א' בקטע סוגי מקומות ב-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: הדירוג הממוצע המינימלי של המשתמשים (בין 1.0 ל-5.0).
• ‫maxRating: הדירוג הממוצע המקסימלי של המשתמש (בין 1.0 ל-5.0).

בנוסף, הערך של minRating תמיד צריך להיות קטן מהערך של maxRating או שווה לו. אם הערך של minRating גדול מהערך של maxRating, תוחזר שגיאת INVALID_ARGUMENT.