Method: places.searchText

根據文字查詢搜尋地點。

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)
  },
  "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。舉例來說，如果評分為 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)

(選用步驟) 沿路線搜尋時使用的額外參數 proto。
includePureServiceAreaBusinesses

boolean

(選用步驟) 如果欄位設為 true，請納入純區域服務商家。純區域服務商家是指提供到府服務或直接送貨給顧客的商家，不在商家地址服務顧客。例如清潔或水電服務。這些商家在 Google 地圖上沒有實體地址或位置。對於這些商家，Places 不會傳回 location、plusCode 和其他地點相關欄位。
includeFutureOpeningBusinesses

boolean

(選用步驟) 如果設為 true，則包含尚未開幕但未來會開幕的商家。

回應主體

places.searchText 的回應 proto。

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

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

回覆中結果的排序方式。

列舉
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

如果地點提供內用服務。