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, כוללים עסקים שעדיין לא נפתחו אבל ייפתחו בעתיד.

גוף התשובה

‫Protocol Buffer של התגובה ל-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

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

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

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

object (Review)

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

object (Photo)

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

object (Justification)

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

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

הצדקה

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

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

ייצוג ב-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)

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

object (BusinessAvailabilityAttributesJustification)

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

ReviewJustification

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

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

ייצוג ב-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

בשלב ניסיוני: פרטים נוספים זמינים בכתובת https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative. הצדקות של מאפייני זמינות העסק. כאן מוצגים כמה מאפיינים של העסק שעשויים לעניין משתמש קצה.

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

boolean

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

boolean

אם במקום מסוים יש שירות משלוחים.
dineIn

boolean

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