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

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

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

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

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

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

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

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

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

ב-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

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

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

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

  • קלט

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

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

  • locationBias או locationRestriction

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

    • 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 ('דומיין ברמה עליונה') בן שני תווים. רוב קודי ה-ccTLD זהים לקודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, הדומיין ccTLD של בריטניה הוא 'uk' (.co.uk) ואילו קוד ISO 3166-1 הוא 'gb' (טכנית לישות 'בריטניה וצפון אירלנד').

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

  • sessionToken

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

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

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

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

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

כל התוצאות מהאזורים שצוינו נכללות במערך suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

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

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

התוצאות נכללות במערך suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

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

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

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

התוצאות מכילות עכשיו הרבה יותר פריטים, כולל תוצאות מחוץ לרדיוס של 5,000 מטר:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

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

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

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

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

שימוש ב-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 standard parameters ולהגדיר את הפרמטר fields למסכת השדה.
  3. אם רוצים, עורכים את גוף הבקשה.
  4. לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.

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