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

במסמך הזה מתוארים פרמטרים של בקשות ל-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 מחזיר קוד שגיאה 404.

בטבלה הבאה מפורטים סוגי האזורים שלא נתמכים. כדי לקבוע אם מזהה מקום מייצג סוג אזור לא נתמך, מעבירים את מזהה המקום בבקשה ל-Geocoding API. התגובה כוללת את המערך 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 מופיעה בטבלה א בקטע סוגי מקומות ב-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).