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

מבוא

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הטיה של מיקום

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

הגבלת מיקום

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

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

רוצה לנסות?

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

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

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

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

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