Method: places.searchText

חיפוש מקומות שמבוסס על שאילתת טקסט.

בקשת HTTP

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

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

גוף הבקשה

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

ייצוג ב-JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "rankPreference": enum (RankPreference),
  "includedType": string,
  "openNow": boolean,
  "minRating": number,
  "maxResultCount": integer,
  "pageSize": integer,
  "pageToken": string,
  "priceLevels": [
    enum (PriceLevel)
  ],
  "strictTypeFiltering": boolean,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "evOptions": {
    object (EVOptions)
  },
  "routingParameters": {
    object (RoutingParameters)
  },
  "searchAlongRouteParameters": {
    object (SearchAlongRouteParameters)
  },
  "includePureServiceAreaBusinesses": boolean,
  "includeFutureOpeningBusinesses": boolean
}
שדות
textQuery

string

חובה. שאילתת הטקסט לחיפוש טקסטואלי.
languageCode

string

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

רשימת השפות הנתמכות הנוכחית: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

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

מידע נוסף זמין בכתובת https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.

שימו לב: אין כרגע תמיכה בקודים אזוריים בני 3 ספרות.
rankPreference

enum (RankPreference)

איך התוצאות ידורגו בתשובה.
includedType

string

סוג המקום המבוקש. רשימה מלאה של הסוגים הנתמכים: https://developers.google.com/maps/documentation/places/web-service/place-types. אפשר לכלול רק סוג אחד.
openNow

boolean

משמש להגבלת החיפוש למקומות שפתוחים כרגע. ברירת המחדל היא false.
minRating

number

סינון התוצאות כך שיוצגו רק תוצאות שבהן הדירוג הממוצע של המשתמשים גדול מהמגבלה הזו. הערך צריך להיות מספר עשרוני בין 0 ל-5 (כולל), במרווחים של 0.5, כלומר [0, 0.5, 1.0, ... , 5.0] כולל. דירוג הקלט יעוגל כלפי מעלה ל-0.5 הקרוב ביותר(ceiling). לדוגמה, דירוג של 0.6 יסיר את כל התוצאות עם דירוג נמוך מ-1.0.
maxResultCount
(deprecated)

integer

הוצא משימוש: במקומו, צריך להשתמש ב-pageSize.

המספר המקסימלי של תוצאות שיוחזרו בכל דף. אם מספר התוצאות הזמינות גדול מ-maxResultCount, מוחזר nextPageToken שאפשר להעביר ל-pageToken כדי לקבל את הדף הבא של התוצאות בבקשות הבאות. אם לא מציינים ערך או מציינים את הערך 0, המערכת משתמשת בערך ברירת המחדל 20. הערך המקסימלי הוא 20. ערכים גבוהים יותר יומרו ל-20. ערכים שליליים יחזירו שגיאת INVALID_ARGUMENT.

אם מציינים את שתי ההגדרות maxResultCount ו-pageSize, המערכת מתעלמת מההגדרה maxResultCount.
pageSize

integer

אופציונלי. המספר המקסימלי של תוצאות שיוחזרו בכל דף. אם מספר התוצאות הזמינות גדול מ-pageSize, מוחזר nextPageToken שאפשר להעביר ל-pageToken כדי לקבל את הדף הבא של התוצאות בבקשות הבאות. אם לא מציינים ערך או מציינים את הערך 0, המערכת משתמשת בערך ברירת המחדל 20. הערך המקסימלי הוא 20. ערכים מעל 20 יוגדרו כ-20. ערכים שליליים יחזירו שגיאת INVALID_ARGUMENT.

אם מציינים את שתי ההגדרות maxResultCount ו-pageSize, המערכת מתעלמת מההגדרה maxResultCount.
pageToken

string

אופציונלי. טוקן של דף שהתקבל מקריאה קודמת של TextSearch. צריך להזין את הטוקן כדי לאחזר את הדף הבא.

כשמבצעים חלוקה לעמודים, כל הפרמטרים שסופקו ל-TextSearch, מלבד pageToken,‏ pageSize ו-maxResultCount, חייבים להיות זהים לקריאה הראשונית שסיפקה את הטוקן של הדף. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
priceLevels[]

enum (PriceLevel)

הפרמטר משמש להגבלת החיפוש למקומות שמסומנים ברמות מחיר מסוימות. המשתמשים יכולים לבחור כל שילוב של רמות מחיר. כברירת מחדל, כל רמות המחירים נבחרות.
strictTypeFiltering

boolean

המאפיין הזה משמש להגדרת סינון קפדני של סוגים עבור includedType. אם המדיניות מוגדרת כ-True, יוחזרו רק תוצאות מאותו סוג. ברירת המחדל היא False.
locationBias

object (LocationBias)

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

object (LocationRestriction)

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

object (EVOptions)

אופציונלי. הגדרת האפשרויות לחיפוש רכבים חשמליים בבקשה לחיפוש מקום.
routingParameters

object (RoutingParameters)

אופציונלי. פרמטרים נוספים לניתוב לתוצאות.
searchAlongRouteParameters

object (SearchAlongRouteParameters)

אופציונלי. פרוטוקול של פרמטרים נוספים לחיפוש לאורך מסלול.
includePureServiceAreaBusinesses

boolean

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

boolean

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

גוף התשובה

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

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

ייצוג ב-JSON 
{
  "places": [
    {
      object (Place)
    }
  ],
  "routingSummaries": [
    {
      object (RoutingSummary)
    }
  ],
  "contextualContents": [
    {
      object (ContextualContent)
    }
  ],
  "nextPageToken": string,
  "searchUri": string
}
שדות
places[]

object (Place)

רשימה של מקומות שעומדים בקריטריונים של חיפוש הטקסט שהמשתמש הזין.
routingSummaries[]

object (RoutingSummary)

רשימה של סיכומי ניתוב, שבה כל רשומה משויכת למקום המתאים באותו אינדקס בשדה places. אם סיכום הניתוב לא זמין לאחד מהמקומות, הוא יכיל רשומה ריקה. אם תבקשו, הרשימה הזו תכלול את כל המקומות שמופיעים ברשימה.
contextualContents[]

object (ContextualContent)

בשלב ניסיוני: פרטים נוספים זמינים בכתובת https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative.

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

string

טוקן שאפשר לשלוח כ-pageToken כדי לאחזר את הדף הבא. אם משמיטים את השדה הזה או משאירים אותו ריק, לא יופיעו דפים נוספים.
searchUri

string

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

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

RankPreference

איך התוצאות ידורגו בתשובה.

טיפוסים בני מנייה (enum)
RANK_PREFERENCE_UNSPECIFIED בשאילתות קטגוריות כמו 'מסעדות בניו יורק', הרלוונטיות היא ברירת המחדל. לשאילתות לא קטגוריות כמו 'מאונטיין ויו, קליפורניה', מומלץ להשאיר את ההגדרה rankPreference ללא ערך.
DISTANCE מדרג את התוצאות לפי מרחק.
RELEVANCE דירוג התוצאות לפי רלוונטיות. סדר המיון נקבע לפי ערימת הדירוג הרגילה.

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)

תיבת מלבן שמוגדרת לפי הפינה הצפון-מזרחית והפינה הדרום-מערבית. הערך rectangle.high() צריך להיות הנקודה הצפון-מזרחית של אזור התצוגה המלבני. הערך rectangle.low() צריך להיות הנקודה הדרום-מערבית של אזור התצוגה המלבני. הערך בשדה rectangle.low().latitude() לא יכול להיות גדול מ-rectangle.high().latitude(). התוצאה תהיה טווח ריק של קווי רוחב. הרוחב של אזור התצוגה המלבני לא יכול להיות גדול מ-180 מעלות.
circle

object (Circle)

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

LocationRestriction

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

ייצוג ב-JSON 
{

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

שדה איחוד type.

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

object (Viewport)

תיבת מלבן שמוגדרת לפי הפינה הצפון-מזרחית והפינה הדרום-מערבית. הערך rectangle.high() צריך להיות הנקודה הצפון-מזרחית של אזור התצוגה המלבני. הערך rectangle.low() צריך להיות הנקודה הדרום-מערבית של אזור התצוגה המלבני. הערך בשדה rectangle.low().latitude() לא יכול להיות גדול מ-rectangle.high().latitude(). התוצאה תהיה טווח ריק של קווי רוחב. הרוחב של אזור התצוגה המלבני לא יכול להיות גדול מ-180 מעלות.

EVOptions

אפשרויות חיפוש של רכבים חשמליים בבקשת חיפוש של מקום.

ייצוג ב-JSON 
{
  "minimumChargingRateKw": number,
  "connectorTypes": [
    enum (EVConnectorType)
  ]
}
שדות
minimumChargingRateKw

number

אופציונלי. קצב הטעינה המינימלי הנדרש בקילוואט. מקום עם מחיר טעינה נמוך מהמחיר שצוין מסונן החוצה.
connectorTypes[]

enum (EVConnectorType)

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

SearchAlongRouteParameters

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

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

ייצוג ב-JSON 
{
  "polyline": {
    object (Polyline)
  }
}
שדות
polyline

object (Polyline)

חובה. הקו הפוליגוני של המסלול.

מצולע פתוח

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

ייצוג ב-JSON 
{

  // Union field polyline_type can be only one of the following:
  "encodedPolyline": string
  // End of list of possible types for union field polyline_type.
}
שדות
שדה איחוד polyline_type. מגדיר את סוג הקו הפוליגוני. פלט ברירת המחדל של Routes API הוא encoded_polyline. הערך polyline_type יכול להיות רק אחד מהבאים:
encodedPolyline

string

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

ContextualContent

תוכן שרלוונטי להקשר של שאילתת המקום.

ייצוג ב-JSON 
{
  "reviews": [
    {
      object (Review)
    }
  ],
  "photos": [
    {
      object (Photo)
    }
  ],
  "justifications": [
    {
      object (Justification)
    }
  ]
}
שדות
reviews[]

object (Review)

רשימת ביקורות על המקום הזה, בהקשר של שאילתת המקום.
photos[]

object (Photo)

מידע (כולל הפניות) על תמונות של המקום הזה, בהקשר של שאילתת המקום.
justifications[]

object (Justification)

הצדקות לגבי המקום.

הצדקה

הצדקות לגבי המקום. ההצדקות עונות על השאלה למה מקום מסוים יכול לעניין משתמש קצה.

ייצוג ב-JSON 
{

  // Union field justification can be only one of the following:
  "reviewJustification": {
    object (ReviewJustification)
  },
  "businessAvailabilityAttributesJustification": {
    object (BusinessAvailabilityAttributesJustification)
  }
  // End of list of possible types for union field justification.
}
שדות

שדה איחוד justification.

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

object (ReviewJustification)
businessAvailabilityAttributesJustification

object (BusinessAvailabilityAttributesJustification)

ReviewJustification

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

ייצוג ב-JSON 
{
  "highlightedText": {
    object (HighlightedText)
  },
  "review": {
    object (Review)
  }
}
שדות
highlightedText

object (HighlightedText)
review

object (Review)

הביקורת שממנה נוצר הטקסט המודגש.

HighlightedText

הטקסט שמודגש על ידי ההצדקה. זהו חלק מהבדיקה עצמה. המילה המדויקת להדגשה מסומנת על ידי HighlightedTextRange. יכול להיות שיוצגו כמה מילים מודגשות בטקסט.

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

string
highlightedTextRanges[]

object (HighlightedTextRange)

רשימת הטווחים של הטקסט המודגש.

HighlightedTextRange

הטווח של הטקסט המודגש.

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

integer
endIndex

integer

BusinessAvailabilityAttributesJustification

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

ייצוג ב-JSON 
{
  "takeout": boolean,
  "delivery": boolean,
  "dineIn": boolean
}
שדות
takeout

boolean

אם במקום מסוים יש אפשרות לקנות אוכל ארוז.
delivery

boolean

אם מקום מסוים מספק משלוחים.
dineIn

boolean

אם במקום מסוים אפשר לאכול במקום.