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

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

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

• ספירת מקומות: קביעת מספר המקומות שתואמים לקריטריונים ספציפיים, כמו סוג המיקום, סטטוס הפעילות, רמת המחיר והדירוגים.
• ‫Retrieve place details (אחזור פרטים של מקום): מקבלים את השמות של מקומות שעומדים במסננים שצוינו, ואז מאחזרים מידע מפורט יותר באמצעות 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 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.