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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

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

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

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

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

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

התשובה יכולה להכיל גם רשימה של חיזויים של שאילתות שתואמים למחרוזת החיפוש ולאזור החיפוש, למשל 'Sicilian Pizza & Stata'. כל חיזוי שאילתה בתגובה כולל את השדה text שמכיל מחרוזת מומלצת של חיפוש טקסט. אפשר להשתמש במחרוזת הזו כקלט ל-Text Search (New) כדי לבצע חיפוש מפורט יותר.

API Explorer מאפשר ליצור בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות ה-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
            }]
        },
        ...
    }
  ...]
}

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

  • קלט

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

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

  • includedPrimaryTypes

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

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

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

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

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

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

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

  • מקור

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

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

  • regionCode

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

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

  • sessionToken

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

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

שימוש בהגבלת מיקום וב-locationBias

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

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

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

ב-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"
        ]
      }
    },
    ...
  ]
}

שימוש ב-includePrimaryTypes

אפשר להשתמש בפרמטר 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 שמכיל מחרוזת מומלצת של חיפוש טקסט. אתם יכולים לשלוח בקשה ל-Text Search (New) (חיפוש טקסט (חדש)) לקבל מידע נוסף על כל אחת מהחיזויים של השאילתות שהוחזרו.

שימוש במקור

בדוגמה הזו, יש לכלול את origin בבקשה כקואורדינטות של קו אורך וקו רוחב. כשכוללים את origin, ה-API כולל בתשובה את השדה 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
      }
    }
  ]
}

רוצה לנסות?

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

  1. בצד שמאל של הדף, בוחרים בסמל ה-API מרחיבים את API Explorer..
  2. אפשר להרחיב את הקטע Show advanced parameters ולהגדיר את הפרמטר fields ל-field mask.
  3. אפשר לערוך את גוף הבקשה.
  4. לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש לשליחת הבקשה.

  5. בחלונית של API Explorer, לוחצים על סמל ההרחבה מרחיבים את API Explorer. כדי להרחיב את חלון ה-API Explorer.