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

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

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

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

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

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

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

סוג התובנה

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

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

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

  הערה: אם בוחרים באפשרות INSIGHT_PLACES, ה-Places Insights API מחזיר מזהי מקומות רק אם הערך של count הוא 100 או פחות.

מסננים

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

מסנן מיקומים

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

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

מעגל

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

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

אזור

כדי להגדיר את האזור כאזור, מעבירים מזהה מקום לפרמטר place. מזהה המקום מייצג אזור גיאוגרפי (למשל, אזור שאפשר לייצג באמצעות פוליגון). לדוגמה, מזהה המקום של טמפה, פלורידה הוא places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. חשוב לציין שלא לכל מזהי המקומות יש גיאומטריה מוגדרת היטב, ובמקרים כאלה Places Insights API מחזיר קוד שגיאה 400 עם הודעה שמציינת שהאזור לא נתמך.

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

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

• establishment: בדרך כלל מציין מקום שעדיין לא סווג.
• street_number: מציין את מספר הבית המדויק.
• floor: מציין את הקומה בכתובת של הבניין.
• post_box: מציין תיבת דואר ספציפית.
• street_address: מציין כתובת רחוב מדויקת.
• room: מציין את החדר בכתובת של הבניין.
• intersection: מציין צומת ראשי, בדרך כלל של שני כבישים ראשיים.
• landmark: מציין מקום סמוך שמשמש כנקודת עזר לניווט.
• subpremise: מציין ישות שניתן לשלוח אליה הודעות מתחת לרמת הנכס, כמו דירה, יחידה או סוויטה.
• sublocality_level_5: הרמה המפורטת ביותר של רכיבי הכתובת ברמת 'קטע יישוב'. בדרך כלל מייצגת חלוקה קטנה מאוד של שכונה או אזור היפר-מקומי בתוך עיר.

אזור מותאם אישית

הגדרת השטח של פוליגון בהתאמה אישית באמצעות קואורדינטות של קו אורך וקו רוחב.

אפשר להיכנס לכתובת 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 מופיעה בטבלה א בקטע סוגי מקומות ב-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.