השלמה אוטומטית (חדשה)

מבוא

השלמה אוטומטית (חדש) הוא שירות אינטרנט שמחזיר חיזויים של מקומות וחיזויים של שאילתות בתגובה לבקשת HTTP. בבקשה, מציינים מחרוזת של חיפוש טקסט וגבולות גיאוגרפיים ששולטים באזור החיפוש.

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

התשובה מההשלמה האוטומטית (חדש) יכולה להכיל שני סוגים של חיזויים:

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

לדוגמה, אתם קוראים ל-Autocomplete (New) באמצעות מחרוזת שמכילה קלט חלקי של משתמש, "Sicilian piz", ואזור החיפוש מוגבל ל-San Francisco, CA. התשובה מכילה רשימה של הצעות למקומות שתואמים למחרוזת החיפוש ולאזור החיפוש, כמו המסעדה "Sicilian Pizza Kitchen", ופרטים על המקום.

ההצעות למקומות שמוחזרות נועדו להצגה למשתמש כדי לעזור לו לבחור את המקום הרצוי. אתם יכולים לשלוח בקשה מסוג Place Details (New)‎ כדי לקבל מידע נוסף על כל אחד מהמקומות שמופיעים בתחזיות.

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

בעזרת APIs Explorer אתם יכולים לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת האפשרויות שלו:

בקשות להשלמה אוטומטית (חדשה)

בקשת השלמה אוטומטית (חדשה) היא בקשת POST HTTP לכתובת URL בפורמט הבא:

https://places.googleapis.com/v1/places:autocomplete

מעבירים את כל הפרמטרים בגוף הבקשה בפורמט JSON או בכותרות כחלק מבקשת ה-POST. לדוגמה:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

פרמטרים נתמכים

מידע על התשובה

השלמה אוטומטית (חדשה) מחזירה אובייקט JSON כתגובה. בתשובה:

• המערך suggestions מכיל את כל המקומות והשאילתות החזויים לפי הסדר, על סמך הרלוונטיות המשוערת שלהם. כל מקום מיוצג על ידי שדה placePrediction וכל שאילתה מיוצגת על ידי שדה queryPrediction.
• שדה placePrediction מכיל מידע מפורט על חיזוי של מקום אחד, כולל מזהה המקום והתיאור בטקסט.
  • כדי להתאים בצורה מדויקת יותר לקלט של המשתמש כפי שסופק בפרמטר input, תיאור הטקסט של חיזוי המקום עשוי לכלול שמות חלופיים של מקומות, רחובות ורכיבי כתובת אחרים. השמות החלופיים האלה עשויים להיות שונים מהשמות שמוחזרים בשדות displayName והכתובת של תוצאות פרטי המקום של אותו מזהה מקום.
  • בהקשר הזה, שמות חלופיים של מקומות מסוימים עשויים להיות בשפה שונה מהשפה שצפויה לפי הפרמטר languageCode, בהתאם לשמות שהכי דומים למה שהמשתמש הזין.
• השדה queryPrediction מכיל מידע מפורט על חיזוי שאילתה יחיד.

אובייקט ה-JSON המלא הוא בפורמט:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

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

קלט

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

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

FieldMask

כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים מסכת שדה תגובה. מעבירים את מסכת השדות של התגובה ל-method באמצעות כותרת ה-HTTP‏ X-Goog-FieldMask.

צריך לציין רשימה מופרדת בפסיקים של שדות ההצעות שרוצים להחזיר. לדוגמה, כדי לאחזר את suggestions.placePrediction.text.text ו-suggestions.queryPrediction.text.text של ההצעה.

  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

אפשר להשתמש ב-* כדי לאחזר את כל השדות.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

אם הערך הוא true, יוחזרו עסקים שצפויים להיפתח בעתיד. ברירת המחדל היא false.

includedPrimaryTypes

למקום יכול להיות רק סוג ראשי אחד מהסוגים שמפורטים בטבלה א' או בטבלה ב'. לדוגמה, הסוג הראשי יכול להיות "mexican_restaurant" או "steak_house".

כברירת מחדל, ה-API מחזיר את כל המקומות על סמך הפרמטר input, בלי קשר לערך הסוג הראשי שמשויך למקום. כדי להגביל את התוצאות לסוג ראשי מסוים או לסוגים ראשיים מסוימים, מעבירים את הפרמטר includedPrimaryTypes.

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

הפרמטר הזה יכול לכלול גם את (regions) או את (cities). אוסף הסוגים (regions) מסנן לפי אזורים או חלוקות, כמו שכונות ומיקודים. אוסף הסוגים (cities) מסנן מקומות ש-Google מזהה כעיר.

הבקשה תידחה ותוצג השגיאה INVALID_REQUEST אם:

• צוינו יותר מחמישה סוגים.
• צוין סוג כלשהו בנוסף ל-(cities) או ל-(regions).
• המערכת מציינת סוגים לא מזוהים.

includePureServiceAreaBusinesses

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

includeQueryPredictions

אם הערך הוא true, התגובה כוללת גם חיזויים של מקומות וגם חיזויים של שאילתות. ערך ברירת המחדל הוא false, כלומר התגובה כוללת רק חיזויים של מקומות.

includedRegionCodes

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

    "includedRegionCodes": ["de", "fr"]

אם מציינים גם את locationRestriction וגם את includedRegionCodes, התוצאות יהיו באזור החפיפה של שתי ההגדרות.

inputOffset

היסט תווי Unicode מבוסס-אפס שמציין את מיקום הסמן ב-input. מיקום הסמן יכול להשפיע על ההצעות שמוחזרות. אם הוא ריק, ברירת המחדל היא האורך של input.

languageCode

השפה המועדפת שבה התוצאות יוחזרו. התוצאות עשויות להיות בשפות שונות אם השפה שבה משתמשים ב-input שונה מהערך שצוין ב-languageCode, או אם למקום שמוחזר אין תרגום מהשפה המקומית ל-languageCode.

• כדי לציין את השפה המועדפת, צריך להשתמש בקודי שפה בתקן IETF BCP-47.
• אם לא מספקים את languageCode, ה-API משתמש בערך שצוין בכותרת Accept-Language. אם לא צוין אף אחד מהם, ברירת המחדל היא en. אם תציינו קוד שפה לא חוקי, ה-API יחזיר שגיאת INVALID_ARGUMENT.
• השפה המועדפת משפיעה קצת על קבוצת התוצאות שה-API בוחר להחזיר ועל הסדר שבו הן מוחזרות. זה משפיע גם על היכולת של ה-API לתקן שגיאות איות.
• הפורמט של חיזוי המקומות משתנה בהתאם לקלט של המשתמש בכל בקשה.
  • קודם נבחרים מונחים תואמים בפרמטר input, תוך שימוש בשמות שתואמים להעדפת השפה שצוינה בפרמטר languageCode, אם היא זמינה. אחרת, נעשה שימוש בשמות שהכי תואמים לקלט של המשתמש.
  • יכול להיות ששמות המקומות יופיעו בפורמט של שמות חלופיים כדי להתאים למונחים בפרמטר input, כולל שמות בשפות שונות מהשפה שצוינה בפרמטר languageCode.
  • כתובות הרחובות מוצגות בשפה המקומית, בכתב שניתן לקריאה על ידי המשתמש, אם הדבר אפשרי, רק לאחר שנבחרו מונחים תואמים שתואמים למונחים בפרמטר input.
  • כל הכתובות האחרות מוחזרות בשפה המועדפת, אחרי שנבחרו מונחים תואמים שתואמים למונחים בפרמטר input. אם השם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.

‫locationBias או locationRestriction

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

• locationBias

  מציין אזור לחיפוש. המיקום הזה משמש כהטיה, כלומר יכול להיות שיוחזרו תוצאות שמסביב למיקום שצוין, כולל תוצאות מחוץ לאזור שצוין.

• locationRestriction

  מציין אזור לחיפוש. לא יוחזרו תוצאות מחוץ לאזור שצוין.

מציינים את האזור של locationBias או locationRestriction בתור אזור תצוגה מלבני או בתור עיגול.

• מעגל מוגדר לפי נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50,000.0, כולל. ערך ברירת המחדל הוא 0.0. ב-locationRestriction, צריך להגדיר את הרדיוס לערך שגדול מ-0.0. אחרת, הבקשה לא מחזירה תוצאות.

  לדוגמה:

  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }

• מלבן הוא אזור תצוגה של קו רוחב וקו אורך, שמיוצג כשתי נקודות low ונקודות גבוהות, שנמצאות באלכסון זו מול זו. אזור תצוגה נחשב לאזור סגור, כלומר הוא כולל את הגבולות שלו. גבולות קו הרוחב חייבים להיות בין ‎-90 ל-90 מעלות, כולל, וגבולות קו האורך חייבים להיות בין ‎-180 ל-180 מעלות, כולל:

  • אם low = high, אזור התצוגה מורכב מהנקודה היחידה הזו.
  • אם low.longitude > high.longitude, טווח קווי האורך הפוך (אזור התצוגה חוצה את קו האורך של 180 מעלות).
  • אם low.longitude = ‎-180 מעלות ו-high.longitude = 180 מעלות, אזור הצפייה כולל את כל קווי האורך.
  • אם low.longitude = 180 מעלות ו-high.longitude = ‎-180 מעלות, טווח קווי האורך ריק.

  צריך לאכלס גם את low וגם את high, והתיבה שמיוצגת לא יכולה להיות ריקה. אם אזור התצוגה ריק, תופיע שגיאה.

  לדוגמה, אזור התצוגה הזה כולל את כל העיר ניו יורק:

  "locationBias": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }

origin

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

"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

regionCode

קוד האזור שמשמש לעיצוב התגובה, שמוגדר כערך ccTLD (דומיין ברמה העליונה) באורך שני תווים. רוב קודי ה-ccTLD זהים לקודי ISO 3166-1, למעט כמה חריגים בולטים. לדוגמה, סיומת ה-ccTLD של בריטניה היא uk‏ (‎.co.uk), אבל קוד ה-ISO 3166-1 שלה הוא gb (מבחינה טכנית, עבור הישות "הממלכה המאוחדת של בריטניה הגדולה וצפון אירלנד").

ההצעות מוטות גם על סמך קודי אזור. ‫Google ממליצה להגדיר את regionCode בהתאם להעדפות הפורמט והמידות של המשתמש.

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

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

sessionToken

טוקנים לסשנים הם מחרוזות שנוצרות על ידי המשתמשים, שמאפשרות לעקוב אחרי קריאות להשלמה אוטומטית (חדשה) בתור "סשנים". השלמה אוטומטית (חדשה) משתמשת בטוקנים לסשן כדי לקבץ את שלבי השאילתה והבחירה של חיפוש השלמה אוטומטית של משתמש לסשן נפרד לצורכי חיוב. מידע נוסף זמין במאמר טוקנים לסשנים.

בחירת פרמטרים להטיית התוצאות

דוגמאות להשלמה אוטומטית (חדשה)

הגבלת החיפוש לאזור מסוים באמצעות locationRestriction

‫locationRestriction מציין את האזור לחיפוש. לא יוחזרו תוצאות מחוץ לאזור שצוין. בדוגמה הבאה, משתמשים ב-locationRestriction כדי להגביל את הבקשה למעגל ברדיוס של 5,000 מטרים שמרכזו בתל אביב:

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

כל התוצאות מתוך האזורים שצוינו כלולות במערך suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

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

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

התוצאות כלולות במערך suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

הטיית החיפוש לאזור מסוים באמצעות locationBias

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

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

התוצאות מכילות עכשיו הרבה יותר פריטים, כולל תוצאות מחוץ לרדיוס של 5,000 מטר:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

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

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

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

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

שימוש ב-includedPrimaryTypes

משתמשים בפרמטר includedPrimaryTypes כדי לציין עד חמישה ערכי סוג מטבלה א', מטבלה ב', או רק (regions), או רק (cities). כדי שמקום ייכלל בתגובה, הוא חייב להתאים לאחד מערכי הסוג הראשי שצוינו.

בדוגמה הבאה, מציינים מחרוזת input של "Soccer" ומשתמשים בפרמטר includedPrimaryTypes כדי להגביל את התוצאות לבתי עסק מסוג "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

אם לא תציינו את הפרמטר includedPrimaryTypes, התוצאות יכולות לכלול מקומות מסוג שאתם לא רוצים, כמו "athletic_field".

בקשת חיזויים לשאילתות

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

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

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

שימוש במקור

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

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

התשובה כוללת עכשיו את distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

איך למצוא עסקים שייפתחו בעתיד

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

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

התגובה כוללת פרטים על המקום, אבל לא כוללת את תאריך הפתיחה.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

המרחק חסר בתגובה

במקרים מסוימים, השדה distanceMeters חסר בגוף התגובה, גם אם השדה origin נכלל בבקשה. זה יכול לקרות בתרחישים הבאים:

• ‫distanceMeters לא נכלל בתחזיות של route.
• השדה distanceMeters לא נכלל כשהערך שלו הוא 0, וזה קורה כשהתחזיות הן במרחק של פחות ממטר אחד מהמיקום שצוין ב-origin.

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

אופטימיזציה של השלמה אוטומטית (חדשה)

בקטע הזה מתוארות שיטות מומלצות שיעזרו לכם להפיק את המקסימום משירות ההשלמה האוטומטית (חדש).

הנה כמה הנחיות כלליות:

• הדרך המהירה ביותר לפתח ממשק משתמש פעיל היא להשתמש בווידג'ט ההשלמה האוטומטית (החדש) של Maps JavaScript API, בווידג'ט ההשלמה האוטומטית (החדש) של Places SDK ל-Android או בווידג'ט ההשלמה האוטומטית (החדש) של Places SDK ל-iOS.
• להבין את שדות הנתונים החיוניים של ההשלמה האוטומטית (חדש) כבר מההתחלה.
• השדות של הטיית מיקום והגבלת מיקום הם אופציונליים, אבל יכולה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
• כדאי להשתמש בטיפול בשגיאות כדי לוודא שהאפליקציה תפעל בצורה תקינה אם ה-API יחזיר שגיאה.
• חשוב לוודא שהאפליקציה מטפלת במקרים שבהם אין בחירה ומציעה למשתמשים דרך להמשיך.

שיטות מומלצות לאופטימיזציה של עלויות

אופטימיזציה בסיסית של עלויות

כדי להוזיל את עלות השימוש בשירות Autocomplete (חדש), אתם יכולים להשתמש במסכות שדות בווידג'טים של Place Details (חדש) ו-Autocomplete (חדש) כדי להחזיר רק את שדות הנתונים של Autocomplete (חדש) שאתם צריכים.

אופטימיזציה מתקדמת של עלויות

כדאי לשקול הטמעה פרוגרמטית של ההשלמה האוטומטית (חדש) כדי לגשת אל מק"ט: תמחור של בקשות להשלמה אוטומטית ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום Place Details (חדש). תמחור לכל בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לכל סשן (מבוסס-סשן) אם מתקיימים שני התנאים הבאים:

• אם אתם צריכים רק את קו הרוחב וקו האורך או את הכתובת של המקום שהמשתמש בחר, Geocoding API מספק את המידע הזה בעלות נמוכה יותר מאשר קריאה ל-Place Details (New).
• אם המשתמשים בוחרים הצעה להשלמת החיפוש מתוך ממוצע של ארבע בקשות להצעות של השלמה אוטומטית (חדשה) או פחות, תמחור לפי בקשה יכול להיות משתלם יותר מתמחור לפי סשן.

יכול להיות ש-Geocoding API יהיה חסכוני יותר בשביל האפליקציה שלכם מאשר Place Details (חדש), בהתאם לביצועים של השימוש ב-Autocomplete (חדש). היעילות של ההשלמה האוטומטית (חדש) בכל אפליקציה משתנה בהתאם למה שהמשתמשים מזינים, למקום שבו משתמשים באפליקציה ולשאלה אם הוטמעו שיטות מומלצות לאופטימיזציה של הביצועים.

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

השלמה אוטומטית מבוססת-סשן (חדש) עם Place Details (חדש)

שימוש בהשלמה אוטומטית (חדשה) מבוססת-סשן עם פרטי מקום (חדשים).
מכיוון שהאפליקציה שלכם דורשת פרטי מקום (חדש), כמו שם המקום, סטטוס העסק או שעות הפעילות, ההטמעה של ההשלמה האוטומטית (חדש) צריכה להשתמש בטוקן לסשן (באופן פרוגרמטי או מובנה בווידג'טים של JavaScript, Android או iOS) לכל סשן, בנוסף למק"טים הרלוונטיים של Places, בהתאם לשדות של נתוני המקומות שאתם מבקשים.¹

הטמעת ווידג'ט
ניהול הסשנים מובנה באופן אוטומטי בווידג'טים של JavaScript, Android, או iOS . החיוב כולל גם את הבקשות של ההשלמה האוטומטית (חדש) וגם את הבקשה של Place Details (חדש) לגבי החיזוי שנבחר. חשוב לציין את הפרמטר fields כדי לוודא שאתם מבקשים רק את שדות הנתונים של ההשלמה האוטומטית (חדש) שאתם צריכים.

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

1. מזהה המקום מהתגובה של ההשלמה האוטומטית (חדש)
2. הטוקן לסשן שמשמש בבקשה להשלמה אוטומטית (חדשה)
3. הפרמטר fields שמציין את שדות הנתונים של ההשלמה האוטומטית (חדש) שאתם צריכים

השלמה אוטומטית (חדשה) לכל בקשה באמצעות Geocoding API

מטמיעים את Autocomplete (חדש) באופן פרוגרמטי בלי טוקנים לסשנים, וקוראים ל-Geocoding API בחיזוי המקום שנבחר.
‫Geocoding API מספק כתובות וקואורדינטות של קווי רוחב ואורך. שליחת ארבע בקשות של Autocomplete Requests וקריאה אחת ל-Geocoding API לגבי החיזוי של המקום שנבחר עולה פחות מהעלות של Autocomplete (חדש) לכל סשן.¹

כדאי להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את החיזוי שהם מחפשים עם עוד פחות תווים.

השלמה אוטומטית (חדשה) מבוססת-סשן לאפליקציות של כתובות בלבד

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

הטמעת ווידג'ט
ניהול הסשנים מובנה באופן אוטומטי בווידג'טים של JavaScript, Android, או iOS. החיוב כולל גם את הבקשות של ההשלמה האוטומטית (חדש) וגם את הבקשה של Place Details (חדש) לגבי החיזוי שנבחר. חשוב לציין את הפרמטר fields כדי לוודא שאתם מבקשים רק את השדות שאתם צריכים.

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

1. מזהה המקום מהתגובה של ההשלמה האוטומטית (חדש)
2. הטוקן לסשן שמשמש בבקשה להשלמה אוטומטית (חדשה)
3. הפרמטר fields שמציין שדות כמו כתובת וגיאומטריה

כדאי לשקול לעכב את הבקשות להשלמה אוטומטית (חדשה)
אפשר להשתמש באסטרטגיות כמו עיכוב של בקשה להשלמה אוטומטית (חדשה) עד שהמשתמש מקליד את שלושת או ארבעת התווים הראשונים, כדי שהאפליקציה תשלח פחות בקשות. לדוגמה, אם שולחים בקשות של Autocomplete (New)‎ לכל תו אחרי שהמשתמש מקליד את התו השלישי, והמשתמש מקליד שבעה תווים ואז בוחר הצעה שבעקבותיה נשלחת בקשה אחת של Geocoding API, העלות הכוללת תהיה על 4 בקשות של Autocomplete (New)‎ לפי בקשה + Geocoding.¹

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

כדאי להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את החיזוי שהם מחפשים בפחות תווים.

שיטות מומלצות לשיפור הביצועים

בהנחיות הבאות מוסבר איך לשפר את הביצועים של ההשלמה האוטומטית (חדש):

• מוסיפים להטמעה של ההשלמה האוטומטית (חדש) הגבלות לפי מדינה, הטיית מיקום והעדפת שפה (להטמעות פרוגרמטיות). אין צורך בהעדפת שפה בווידג'טים, כי הם בוחרים את העדפות השפה מהדפדפן או מהמכשיר הנייד של המשתמש.
• אם ההשלמה האוטומטית (חדש) מלווה במפה, אתם יכולים להטות את המיקום לפי אזור התצוגה של המפה.
• במקרים שבהם המשתמש לא בוחר באחת מההצעות של ההשלמה האוטומטית (חדש), בדרך כלל כי אף אחת מההצעות האלה היא לא הכתובת הרצויה, אתם יכולים להשתמש שוב בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
  • אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, השתמשו שוב בקלט המקורי של המשתמש בקריאה ל-Geocoding API.
  • אם אתם מצפים שהמשתמש יזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, השתמשו בבקשה לפרטי מקום (חדש). אם התוצאות צפויות רק באזור ספציפי, השתמשו בהטיית מיקום.
  תרחישים נוספים שבהם מומלץ להשתמש ב-Geocoding API:
  • משתמשים שמזינים כתובות של יחידות משנה, כמו כתובות של יחידות או דירות ספציפיות בתוך בניין. לדוגמה, הכתובת בצ'כיה "Stroupežnického 3191/17, Praha" מניבה חיזוי חלקי בהשלמה האוטומטית (חדש).
  • משתמשים שמזינים כתובות עם קידומות של קטעי כביש, כמו "‎23-30 29th St, Queens" בניו יורק או "‎47-380 Kamehameha Hwy, Kaneohe" באי קאואיי בהוואי.

הטיה לפי מיקום

כדי להטות את התוצאות לאזור מסוים, מעבירים את הפרמטרים location ו-radius. ההגדרה הזו מנחה את ההשלמה האוטומטית (חדש) להעדיף להציג תוצאות בתוך האזור שהוגדר. יכול להיות שעדיין יוצגו תוצאות מחוץ לאזור שהוגדר. אפשר להשתמש בפרמטר includedRegionCodes כדי לסנן את התוצאות כך שיוצגו רק המקומות במדינה מסוימת.

הגבלת מיקום

כדי להגביל את התוצאות לאזור מסוים, צריך להעביר פרמטר locationRestriction.

אפשר גם להגביל את התוצאות לאזור שמוגדר על ידי location ופרמטר radius, על ידי הוספת הפרמטר locationRestriction. ההגדרה הזו מנחה את ההשלמה האוטומטית (חדש) להחזיר רק תוצאות באזור הזה.

רוצה לנסות?

ב-APIs Explorer אתם יכולים לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות שהוא מציע.

1. לוחצים על סמל ה-API‏ api בצד שמאל של הדף.

2. אפשר לערוך את הפרמטרים של הבקשה.

3. לוחצים על הכפתור Execute. בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.

4. בחלונית APIs Explorer, לוחצים על סמל המסך המלא fullscreen כדי להרחיב את החלון של APIs Explorer.