Method: places.searchText

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

בקשת HTTP

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

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

גוף הבקשה

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

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

string

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

string

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

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

string

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

מידע נוסף זמין בכתובת 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 הקרוב ביותר(התקרה). לדוגמה, דירוג של 0.6 יבטל את כל התוצאות שקיבלו דירוג נמוך מ-1.0.
maxResultCount
(deprecated)

integer

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

המספר המקסימלי של תוצאות שאפשר להחזיר בכל דף. אם מספר התוצאות הזמינות גדול מ-maxResultCount, מוחזר nextPageToken ואפשר להעביר אותו אל pageToken כדי לקבל את דף התוצאות הבא בבקשות הבאות. אם מציינים 0 או לא מציינים ערך, המערכת משתמשת בערך ברירת המחדל 20. הערך המקסימלי הוא 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, צריך לכלול עסקים שנותנים שירות באזור מוגדר בלבד. עסק שנותן שירות באזור מוגדר (SAB) הוא עסק שהעובדים שלו מגיעים אל הלקוחות או מציעים להם משלוחים באופן ישיר, אבל לא נותנים שירות ללקוחות בכתובת העסק. לדוגמה, עסקים כמו שירותי ניקיון או שרברבים. לעסקים האלה אין כתובת פיזית או מיקום במפות Google. המערכת של Places לא תחזיר שדות שכוללים את location, את plusCode ושדות אחרים שקשורים למיקום של העסקים האלה.

גוף התשובה

פרוטו לתגובה של 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 באמצעות אותה שאילתת טקסט שצוינה בבקשה.

RankPreference

איך התוצאות ירוכזו בתשובה.

טיפוסים בני מנייה (enum)
RANK_PREFERENCE_UNSPECIFIED לשאילתה שמסווגת לפי קטגוריות, כמו "מסעדות בתל אביב", ברירת המחדל היא RELEVANCE. עבור שאילתות שאינן מסווגות כקטגוריות, כגון 'Mountain View, CA', מומלץ להשאיר את הפרמטר levelPreference לא מוגדר.
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

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

ייצוג ב-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. נימוקים של BusinessAvailabilityAttributes. כאן מוצגים כמה מאפיינים של העסק שעשויים לעניין משתמש קצה.

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

boolean

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

boolean

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

boolean

אם יש במקום אכילה במקום.