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

מבוא

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

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

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

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

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

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

התשובה יכולה לכלול גם רשימה של תחזיות לשאילתות שתואמות למחרוזת החיפוש ולאזור החיפוש, כמו "Sicilian Pizza & Pasta". כל תחזית לשאילתה בתגובה כוללת את השדה 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 מכיל מידע מפורט על חיזוי של מקום יחיד, כולל מזהה המקום ותיאור טקסטואלי.
• שדה 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: *

• 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, או אם אין תרגום למקום שהוחזר מהשפה המקומית ל-languageCode.

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

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

  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
      }
    }
  ]
}

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

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

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

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

רוצה לנסות?

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

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

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

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

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