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

מבוא

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

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

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

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

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

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

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

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

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

בקשה להשלמה אוטומטית (חדשה) היא בקשת HTTP POST לכתובת 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
            }]
        },
        ...
    }
  ...]
}

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

• קלט

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

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

• FieldMask

  כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים מסכת שדות של תגובה. מעבירים את מסכת שדות התגובה לשיטה באמצעות כותרת ה-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) type collection מיועד למקומות ש-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, או אם אין תרגום למקום שמוחזר מהשפה המקומית ל-input.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 כהגדרה של האזור שבו התוצאות צריכות להיות קרובות, אבל יכולות להיות מחוץ לאזור.

  Autocomplete (חדש) מוטות לפי כתובת ה-IP של המכשיר.

  • 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. הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

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

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

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

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

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

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

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

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

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

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

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

האם האפליקציה שלך דורשת מידע כלשהו מלבד הכתובת וקו הרוחב/קו האורך של התחזית שנבחרה?

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

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

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

הטיה של מיקום

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

הגבלת מיקום

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

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

רוצה לנסות?

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

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

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

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

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