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.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_TRUE 的錯誤。

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

integer

選用設定。每頁可傳回的結果數量上限。如果可用結果的數量大於 pageSize，系統會傳回 nextPageToken，傳回 pageToken，以便在後續要求中取得下一頁的結果。如果提供 0 或未提供任何值，則會使用預設值 20。最大值為 20；值超過 20 時將會設為 20。負值會傳回 INVALID_TRUE 的錯誤。

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

string

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

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

enum (PriceLevel)

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

boolean

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

object (LocationBias)

要搜尋的區域。這個位置只是偏誤，因此系統可能會傳回指定地點附近的結果。無法同時設定 locationRestriction。
locationRestriction

object (LocationRestriction)

要搜尋的區域。這個地點屬於限制，因此不會傳回指定位置以外的結果。無法同時設定和 locationBia。
evOptions

object (EVOptions)

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

回應主體

places.searchText 的回應 proto。

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

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。

情境內容清單，其中每個項目都會與 Place 欄位中相同索引中的對應位置建立關聯。建議優先選擇與要求中 textQuery 相關的內容。如果其中一個地點沒有相關內容，則會傳回非關聯內容。只有在此地點沒有內容時，這個欄位才會留空。如有要求，此清單所包含的項目數量應與地點清單的數量一樣多。
nextPageToken

string

可做為 pageToken 傳送的權杖，用於擷取下一頁。如果省略了這個欄位留空或留空，系統就不會提供後續網頁。

RankPreference

結果在回應中的排名方式。

列舉
RANK_PREFERENCE_UNSPECIFIED 如果是「紐約市餐廳」這類類別查詢，預設值為 RELEVANCE。適用於非類別查詢，例如「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)

選用設定。偏好的電動車連接器類型清單。系統會篩除不支援任何下列連接器類型的地點。

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

地點是否提供內用。