Method: places.searchText

文字查詢 Place Search。

HTTP 要求

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

這個網址使用 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)
  }
}
欄位
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(天花板)。舉例來說，如果評分為 0.6，就會排除評分低於 1.0 的所有結果。
maxResultCount
(deprecated)

integer

已淘汰：請改用 pageSize。

每頁可傳回的結果數量上限。如果可用結果的數量大於 maxResultCount，系統會傳回 nextPageToken 並傳遞至 pageToken，在後續要求中取得下一頁的結果。如果提供 0 或未提供值，系統會使用預設值 20。許可的最大值為 20；超出的數值將一律指定為 20。負值會傳回 INVALID_Gradle 錯誤。

如果同時指定 maxResultCount 和 pageSize，系統會忽略 maxResultCount。
pageSize

integer

選用設定。每頁可傳回的結果數量上限。如果可用結果的數量大於 pageSize，系統會傳回 nextPageToken 並傳遞至 pageToken，在後續要求中取得下一頁的結果。如果提供 0 或未提供值，系統會使用預設值 20。最大值是 20；高於 20 的值會設為 20。負值會傳回 INVALID_Gradle 錯誤。

如果同時指定 maxResultCount 和 pageSize，系統會忽略 maxResultCount。
pageToken

string

選用設定。接收自先前的 TextSearch 呼叫的網頁權杖。提供此項目即可擷取後續網頁。

進行分頁時，提供給 TextSearch 的 pageToken、pageSize 和 maxResultCount 以外的所有參數，都必須與提供網頁權杖的初始呼叫相符。否則系統會傳回 INVALID_UNIT 錯誤。
priceLevels[]

enum (PriceLevel)

用於將搜尋範圍限制在標示為特定價位的地點。使用者可以選擇任何價位的組合。預設為選取所有價位。
strictTypeFiltering

boolean

用於為 includeType 設定嚴格類型篩選。如果設為 True，系統只會傳回相同類型的結果。預設為 false。
locationBias

object (LocationBias)

要搜尋的區域。這個位置會做為自訂區域，這表示系統可能會傳回指定位置周圍的結果。無法同時設定 locationRestriction。
locationRestriction

object (LocationRestriction)

要搜尋的區域。這個位置會受到限制，表示不會傳回指定地區以外的結果。無法同時設定 locationBias。
evOptions

object (EVOptions)

選用設定。針對地點搜尋要求設定可搜尋的電動車選項。

回應主體

Places.searchText 的回應通訊協定。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "places": [
    {
      object (Place)
    }
  ],
  "contextualContents": [
    {
      object (ContextualContent)
    }
  ],
  "nextPageToken": string
}
欄位
places[]

object (Place)

符合使用者文字搜尋條件的地點清單。
contextualContents[]

object (ContextualContent)

實驗功能：詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。

內容相關內容清單，每個項目都會與地點欄位中相同索引的對應位置建立關聯。最好提供與要求中 textQuery 相關的內容。如果其中一個地點無法取得相關內容，就會傳回非相關內容。除非該內容不適用於這個地點，否則這裡不會顯示任何內容。如果系統提出要求，這份清單應包含地點清單的項目數量。
nextPageToken

string

可做為 pageToken 傳送的權杖，用於擷取後續網頁。如果省略這個欄位或留空，表示沒有後續網頁。

RankPreference

回應中的結果排名方式。

列舉
RANK_PREFERENCE_UNSPECIFIED 如果是如「紐約市餐廳」這類類別查詢，預設值為 RELEVANCE。如果是「加州山景城」這類非類別的查詢，則建議您不要設定 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() 必須是矩形可視區域的 northeast 點。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() 必須是矩形可視區域的 northeast 點。rectangle.low() 必須是矩形可視區域的西南點。rectangle.low().latitude()不得大於 rectangle.high().latitude()。如此一來，緯度範圍就會是空的。矩形可視區域的寬度不得超過 180 度。

EVOptions

Place Search 要求中可供搜尋的電動車選項。

JSON 表示法 
{
  "minimumChargingRateKw": number,
  "connectorTypes": [
    enum (EVConnectorType)
  ]
}
欄位
minimumChargingRateKw

number

選用設定。最低所需充電速率，以千瓦為單位。系統會篩除充電率低於指定費率的地點。
connectorTypes[]

enum (EVConnectorType)

選用設定。偏好的電動車連接器類型清單。不支援指定連接器類型的位置會遭到篩除。

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

是否提供內用資訊。