Method: places.autocomplete

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

בקשת HTTP

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

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

גוף הבקשה

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

ייצוג 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
}
שדות
input

string

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

object (LocationBias)

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

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

object (LocationRestriction)

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

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

string

זה שינוי אופציונלי. סוג מקום ראשי (למשל, "מסעדה" או "gas_station") מטבלה א' או מטבלה ב' בסוגי מקומות (https://developers.google.com/maps/documentation/places/web-service/place-types), או רק (אזורים), או רק (ערים). מקום מוחזר רק אם הסוג הראשי שלו כלול ברשימה הזו. אפשר לציין עד 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

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

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

boolean

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

string

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

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

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

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

גוף התשובה

תגובה מסוג Proto עבור places.autocomplete.

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

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

object (Suggestion)

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

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 או להיפך.