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

היקפי הרשאה

נדרש היקף הרשאות OAuth הבא:

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

RankPreference

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

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

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

boolean

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

boolean

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

boolean

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