Method: places.autocomplete

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

בקשת HTTP

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

כתובת ה-URL משתמשת בתחביר של Transcoding של 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,
  "includePureServiceAreaBusinesses": 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

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

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

boolean

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

string

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

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

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

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

boolean

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

גוף התשובה

פרוטוקול התגובה של 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)

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

מומלץ להשתמש ב-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 או להפך.