Method: places.autocomplete

מחזירה תחזיות לקלט הנתון.

בקשת HTTP

POST https://places.googleapis.com/v1/places:autocomplete

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string,
  "includePureServiceAreaBusinesses": boolean,
  "includeFutureOpeningBusinesses": boolean
}
שדות
input

string

חובה. מחרוזת הטקסט שבה יתבצע החיפוש.
locationBias

object (LocationBias)

אופציונלי. הטיית התוצאות למיקום ספציפי.

צריך להגדיר לכל היותר אחד מהערכים locationBias או locationRestriction. אם אף אחת מההגדרות לא מוגדרת, התוצאות יהיו מוטות בגלל כתובת ה-IP, כלומר כתובת ה-IP תמופה למיקום לא מדויק ותשמש כאות הטיה.
locationRestriction

object (LocationRestriction)

אופציונלי. הגבלת התוצאות למיקום ספציפי.

צריך להגדיר לכל היותר אחד מהערכים locationBias או locationRestriction. אם אף אחת מההגדרות לא מוגדרת, התוצאות יהיו מוטות בגלל כתובת ה-IP, כלומר כתובת ה-IP תמופה למיקום לא מדויק ותשמש כאות הטיה.
includedPrimaryTypes[]

string

אופציונלי. סוג המקום הראשי שכלול (לדוגמה, 'מסעדה' או 'תחנת דלק') בסוגי המקומות (https://developers.google.com/maps/documentation/places/web-service/place-types), או רק (regions), או רק (cities). מקום יוחזר רק אם הסוג הראשי שלו כלול ברשימה הזו. אפשר לציין עד 5 ערכים. אם לא מציינים סוגים, כל סוגי המקומות מוחזרים.
includedRegionCodes[]

string

אופציונלי. כוללות רק תוצאות באזורים שצוינו, שמוגדרים כעד 15 קודי אזור בני שני תווים בפורמט CLDR. קבוצה ריקה לא תגביל את התוצאות. אם מגדירים את שתי ההגדרות locationRestriction ו-includedRegionCodes, התוצאות יופיעו באזור החיתוך.
languageCode

string

אופציונלי. השפה שבה יוחזרו התוצאות. ברירת המחדל היא en-US. יכול להיות שהתוצאות יהיו בשילוב של שפות אם השפה שבה נעשה שימוש ב-input שונה מ-languageCode, או אם אין תרגום של המקום שמוחזר מהשפה המקומית ל-languageCode.
regionCode

string

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

object (LatLng)

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

integer

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

אם השדה ריק, ברירת המחדל היא האורך של input.
includeQueryPredictions

boolean

אופציונלי. אם הערך הוא true, התשובה תכלול גם תחזיות של מקומות וגם תחזיות של שאילתות. אחרת, התשובה תכלול רק תחזיות לגבי מקומות.
sessionToken

string

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

הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהוא בוחר מקום ומתבצעת קריאה ל-Place Details או ל-Address Validation. בכל סשן יכולות להיות כמה שאילתות, ואחריהן בקשה אחת של Place Details או Address Validation. האישורים שמשמשים לכל בקשה בסשן חייבים להשתייך לאותו פרויקט במסוף Google Cloud. אחרי שהסשן מסתיים, הטוקן כבר לא תקף. האפליקציה צריכה ליצור טוקן חדש לכל סשן. אם לא מציינים את הפרמטר sessionToken או אם משתמשים מחדש בטוקן סשן, הסשן יחויב כאילו לא סופק טוקן סשן (כל בקשה תחויב בנפרד).

מומלץ לפעול לפי ההנחיות הבאות:

  • מומלץ להשתמש באסימוני סשן לכל הקריאות להשלמה אוטומטית למקומות.
  • צריך ליצור טוקן חדש לכל סשן. מומלץ להשתמש ב-UUID בגרסה 4.
  • חשוב לוודא שפרטי הכניסה שמשמשים לכל הבקשות של השלמה אוטומטית למקומות, Place Details ו-Address Validation בסשן מסוים שייכים לאותו פרויקט ב-מסוף Cloud.
  • חשוב להעביר טוקן לסשן ייחודי לכל סשן חדש. אם משתמשים באותו טוקן ליותר מסשן אחד, כל בקשה תחויב בנפרד.
includePureServiceAreaBusinesses

boolean

אופציונלי. אם השדה מוגדר כ-true, צריך לכלול עסקים שרק נותנים שירות באזור מוגדר. עסק שנותן שירות באזור מוגדר הוא עסק שמבקר או שולח מוצרים ללקוחות ישירות, אבל לא מספק שירותים בכתובת העסק. לדוגמה, עסקים שמספקים שירותי ניקיון או שרברבים. לעסקים האלה אין כתובת פיזית או מיקום במפות Google. השירות Places לא יחזיר שדות כולל location,‏ plusCode ושדות אחרים שקשורים למיקום של העסקים האלה.
includeFutureOpeningBusinesses

boolean

אופציונלי. אם הערך הוא true, כוללים עסקים שעדיין לא נפתחו אבל ייפתחו בעתיד.

גוף התשובה

פרוטוקול התגובה של places.autocomplete.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
שדות
suggestions[]

object (Suggestion)

מכיל רשימה של הצעות, מסודרות בסדר יורד לפי הרלוונטיות שלהן.

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/cloud-platform

LocationBias

האזור לחיפוש. יכול להיות שהתוצאות יהיו מוטות בהתאם לאזור שצוין.

ייצוג ב-JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
שדות

שדה איחוד type.

הערך type יכול להיות רק אחד מהבאים:
rectangle

object (Viewport)

אזור תצוגה שמוגדר על ידי פינה צפון-מזרחית ופינה דרום-מערבית.
circle

object (Circle)

מעגל שמוגדר על ידי נקודת מרכז ורדיוס.

LocationRestriction

האזור לחיפוש. התוצאות יוגבלו לאזור שצוין.

ייצוג ב-JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
שדות

שדה איחוד type.

הערך type יכול להיות רק אחד מהבאים:
rectangle

object (Viewport)

אזור תצוגה שמוגדר על ידי פינה צפון-מזרחית ופינה דרום-מערבית.
circle

object (Circle)

מעגל שמוגדר על ידי נקודת מרכז ורדיוס.

הצעה

תוצאה של הצעה של ההשלמה האוטומטית.

ייצוג ב-JSON 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
שדות

שדה איחוד kind.

הערך kind יכול להיות רק אחד מהבאים:
placePrediction

object (PlacePrediction)

תחזית לגבי מקום.
queryPrediction

object (QueryPrediction)

תחזית לשאילתה.

PlacePrediction

תוצאות של הצעות להשלמת החיפוש עבור השלמה אוטומטית למקומות.

ייצוג ב-JSON 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
שדות
place

string

שם המשאב של המקום המוצע. אפשר להשתמש בשם הזה בממשקי API אחרים שמקבלים שמות של מקומות.
placeId

string

המזהה הייחודי של המקום המוצע. אפשר להשתמש במזהה הזה בממשקי API אחרים שמקבלים מזהי מקומות.
text

object (FormattableText)

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

מומלץ להשתמש ב-text למפתחים שרוצים להציג רכיב בממשק המשתמש. מפתחים שרוצים להציג שני רכיבי ממשק משתמש נפרדים אבל קשורים, יכולים להשתמש במקום זאת ב-structuredFormat. אלה שתי דרכים שונות לייצוג של חיזוי מקום. אסור למשתמשים לנסות לנתח את structuredFormat ל-text או להיפך.

יכול להיות שהטקסט הזה שונה מdisplayName שמוחזר על ידי places.get.

יכול להיות שהשפה תהיה שילוב של כמה שפות אם הבקשה input ו-languageCode הן בשפות שונות, או אם אין תרגום של המקום מהשפה המקומית ל-languageCode.
structuredFormat

object (StructuredFormat)

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

מומלץ להשתמש ב-structuredFormat למפתחים שרוצים להציג שני רכיבי ממשק משתמש נפרדים אבל קשורים. מפתחים שרוצים להציג רכיב בממשק המשתמש יכולים להשתמש במקום זאת ב-text. אלה שתי דרכים שונות לייצוג של חיזוי מקום. אסור למשתמשים לנסות לנתח את structuredFormat ל-text או להיפך.
types[]

string

רשימה של סוגים שרלוונטיים למקום הזה מתוך טבלה א' או טבלה ב' בכתובת https://developers.google.com/maps/documentation/places/web-service/place-types.

סוג הוא סיווג של מקום. למקומות עם סוגים משותפים יהיו מאפיינים דומים.
distanceMeters

integer

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

FormattableText

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

ייצוג ב-JSON 
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
שדות
text

string

טקסט שאפשר להשתמש בו כמו שהוא או לעצב אותו באמצעות matches.
matches[]

object (StringRange)

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

הערכים האלה הם היסטים של תווי Unicode של text. הטווחים מובטחים להיות מסודרים בסדר עולה של ערכי ההיסט.

StringRange

מזהה מחרוזת משנה בטקסט נתון.

ייצוג ב-JSON 
{
  "startOffset": integer,
  "endOffset": integer
}
שדות
startOffset

integer

ההיסט מבוסס-אפס של תו ה-Unicode הראשון במחרוזת (כולל).
endOffset

integer

ההיסט מבוסס-אפס של תו ה-Unicode האחרון (לא כולל).

StructuredFormat

כולל פירוט של תחזית לגבי מקומות או שאילתה לטקסט ראשי ולטקסט משני.

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

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

ייצוג ב-JSON 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
שדות
mainText

object (FormattableText)

מייצג את השם של המקום או של השאילתה.
secondaryText

object (FormattableText)

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

QueryPrediction

תוצאות חיזוי להשלמה אוטומטית של שאילתה.

ייצוג ב-JSON 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
שדות
text

object (FormattableText)

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

מומלץ להשתמש ב-text למפתחים שרוצים להציג רכיב בממשק המשתמש. מפתחים שרוצים להציג שני רכיבי ממשק משתמש נפרדים אבל קשורים, יכולים להשתמש במקום זאת ב-structuredFormat. אלה שתי דרכים שונות לייצוג של חיזוי שאילתה. אסור למשתמשים לנסות לנתח את structuredFormat ל-text או להיפך.

יכול להיות שהתשובה תהיה בשילוב של שפות אם הבקשה input ו-languageCode הן בשפות שונות, או אם חלק מהשאילתה לא תורגם מהשפה המקומית ל-languageCode.
structuredFormat

object (StructuredFormat)

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

מומלץ להשתמש ב-structuredFormat למפתחים שרוצים להציג שני רכיבי ממשק משתמש נפרדים אבל קשורים. מפתחים שרוצים להציג רכיב בממשק המשתמש יכולים להשתמש במקום זאת ב-text. אלה שתי דרכים שונות לייצוג של חיזוי שאילתה. אסור למשתמשים לנסות לנתח את structuredFormat ל-text או להיפך.