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

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

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

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

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

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

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

סוג התובנה

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

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

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

מסננים

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

מסנן מיקומים

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

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

חשוב: השטח של כל מסנן מיקום חייב להיות בין 1,556.86 מ"ר (בערך בגודל של בלוק קטן בעיר) לבין 2 טריליון מ"ר (בערך בגודל של אלסקה). בקשות עם אזורים מחוץ לטווח הזה יחזירו שגיאה מסוג INVALID_ARGUMENT.

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

מעגל

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

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

אזור

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

חשוב: כשמשתמשים במסנן region עם סוג התובנה INSIGHT_PLACES, בקשות שכוללות אזורים שנויים במחלוקת נדחות באופן אוטומטי כדי להבטיח את הדיוק והניטרליות של שירותי Google. אזורים שנויים במחלוקת הם אזורים עם גבולות או תביעות טריטוריאליות סותרות של מדינות או ישויות שונות. גבולות שנויים במחלוקת מוצגים במפות Google כקו אפור מקווקו.

מידע נוסף על האופן שבו מזוהים אזורים שנויים במחלוקת זמין במאמר הסבר על שמות וגבולות של ארצות.

חשוב: Google לא תומכת במזהי מקומות מסוימים ששייכים לסוגי האזורים הבאים:

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

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

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

• ‫establishment: בדרך כלל מציין מקום שעדיין לא סווג.
• ‫intersection: מציין צומת ראשי, בדרך כלל של שני כבישים ראשיים.
• ‫subpremise: מציין ישות שניתן להוסיף לה כתובת מתחת לרמת המבנה, כמו דירה, יחידה או סוויטה.

הערה: יכול להיות שגם מקומות שלא מופיעים ברשימה שלמעלה יידחו אם אין להם גיאומטריית פוליגון מוגדרת היטב. זה קורה יותר בסוגים כמו neighborhood,‏ locality,‏ sublocality והגרסאות הממוספרות שלהם (sublocality_level_1,‏ sublocality_level_2,‏ sublocality_level_3,‏ sublocality_level_4). במקרה כזה מוחזר קוד השגיאה 400.

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

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

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

חשוב: באזורים בהתאמה אישית יכולים להיות עד 7,000 קודקודים.

אפשר להיכנס לכתובת 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 API (החדש) מפורטים סוגי המקומות הראשיים והמשניים שנתמכים ב-Places Aggregate API. צריך לציין לפחות סוג אחד של includedTypes או includedPrimaryTypes.

• ‫includedTypes: רשימה של סוגי המקומות שנכללים.
• ‫excludedTypes: רשימה של סוגי מקומות שלא נכללים.
• ‫includedPrimaryTypes: רשימה של סוגי המקומות הראשיים שכלולים.
• ‫excludedPrimaryTypes: רשימה של סוגי מקומות ראשיים שלא נכללים.

מידע נוסף על מסנני סוגים

הערה: מסנני סוגים כוללים באופן אוטומטי סוגי משנה של הסוגים שצוינו. לדוגמה, אם מסננים לפי gym, התוצאות כוללות גם מקומות שמסווגים לפי סוגי המשנה שלו, כמו yoga_studio.

פרמטרים אופציונליים

המסננים האלה הם אופציונליים:

• ‫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.