דף זה תורגם על ידי Cloud Translation API.

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

בחירת פלטפורמה: Android iOS JavaScript Web Service

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

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

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

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

לדוגמה, אפשר להפעיל את ה-API באמצעות מחרוזת שמכילה קלט חלקי של משתמש, "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

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

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

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

הערה: האפשרות 'השלמה אוטומטית (חדשה)' מחזירה חמישה חיזויים בסך הכול, בתור placePredictions, queryPredictions או שילוב של שניהם, בהתאם לבקשה. לדוגמה, אם הבקשה לא מגדירה את includeQueryPredictions, גוף התשובה יכלול עד חמישה placePredictions. אם הבקשה מגדירה את הערך includeQueryPredictions, גוף התגובה יכלול עד חמש תחזיות בשילוב של placePredictions ו-queryPredictions.

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

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

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

קלט

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

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

FieldMask

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

מציינים רשימה של שדות ההצעות להחזרה, מופרדים בפסיקים. לדוגמה, כדי לאחזר את הערכים suggestions.placePrediction.place ו-suggestions.placePrediction.text של ההצעה.
```
  X-Goog-FieldMask: places.displayName,places.formattedAddress
```
הערה: אסור להשתמש ברווחים בשום מקום ברשימה של השדות.

משתמשים ב-* כדי לאחזר את כל השדות.
```
  X-Goog-FieldMask: *
```
סמל הפלאי "*" בוחר את כל השדות.
includedPrimaryTypes

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

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

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

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

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

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

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

הכלל הזה מאפשר לכלול רק תוצאות מהרשימה של האזורים שצוינו, כפי שצוינו כמערך של עד 15 ערכים של ccTLD (דומיין ברמה עליונה) בתווים בודדים. אם השדה הזה לא יצוין, לא יחולו הגבלות על התגובה. לדוגמה, כדי להגביל את האזורים לגרמניה ולצרפת:
```
    "includedRegionCodes": ["de", "fr"]
```
אם מציינים גם את locationRestriction וגם את includedRegionCodes, התוצאות נמצאות באזור החיתוך של שתי ההגדרות.
inputOffset

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

הערה: בגרסת Private Preview הראשונית, המאפיין הזה נקרא predictionTermOffset.
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, ה-API משתמש בהטיה לפי כתובת IP כברירת מחדל. כשמשתמשים בהטיה לפי כתובת IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות.
- locationBias
  
  מציין אזור לחיפוש. המיקום הזה משמש כנטייה, כלומר יכול להיות שהמערכת תחזיר תוצאות בסביבת המיקום שצוין, כולל תוצאות מחוץ לאזור שצוין.
- locationRestriction
  
  מציין אזור לחיפוש. לא יוצגו תוצאות מחוץ לאזור שצוין.
מציינים את האזור locationBias או locationRestriction כתצוגת מסך מלבנית או כעיגול.
- מעגל מוגדר על ידי נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50000.0, כולל. ערך ברירת המחדל הוא 0.0. עבור locationRestriction, צריך להגדיר את הרדיוס לערך גדול מ-0.0. אחרת, הבקשה לא תחזיר תוצאות.
  
  לדוגמה:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- מלבן הוא חלון תצוגה לפי קו הרוחב והאורך, שמיוצג על ידי שתי נקודות low נמוכות ונקודות 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 ('דומיין ברמה עליונה') בן שני תווים. רוב הקודים של TLD ברמת המדינה זהים לקודי ISO 3166-1, מלבד כמה יוצאים מן הכלל. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא ‎uk (‎.co.uk), והקוד שלו לפי תקן ISO 3166-1 הוא ‎gb (טכנית, הישות היא 'הממלכה המאוחדת של בריטניה הגדולה וצפון אירלנד').

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

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

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

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

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

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

הערה: תחזיות לשאילתות לא מוחזרות כשמגדירים את הפרמטר includedRegionCodes.

שימוש במקור

בדוגמה הזו, צריך לכלול את 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 ובאפשרויות שלו.

נסה בעצמך!

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

בוחרים בסמל ה-API api בצד שמאל של הדף.
אפשר לערוך את פרמטרים הבקשה.
לוחצים על הלחצן Execute. בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.
בחלונית של APIs Explorer, בוחרים בסמל המסך המלא fullscreen כדי להרחיב את החלון של APIs Explorer.

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

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

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

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

קלט

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

FieldMask

includedPrimaryTypes

includePureServiceAreaBusinesses

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias או locationRestriction

locationBias

locationRestriction

מקור

regionCode

sessionToken

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

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

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

שימוש ב-includedPrimaryTypes

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

שימוש במקור

נסה בעצמך!

נסה בעצמך!