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

זה שינוי אופציונלי. סוג המקום הראשי הכלול (לדוגמה, 'restaurant' או '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

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

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

boolean

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

string

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

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

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

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

גוף התשובה

אב של תגובה עבור 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, או להיפך.