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
}
欄位
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_ARGUMENT 錯誤。

如果同時指定 maxResultCountpageSize,系統會忽略 maxResultCount

pageSize

integer

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

如果同時指定 maxResultCountpageSize,系統會忽略 maxResultCount

pageToken

string

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

進行分頁時,提供給 TextSearch 的所有參數 (除了 pageTokenpageSizemaxResultCount) 都必須與提供網頁權杖的初始呼叫相符。否則會傳回 INVALID_ARGUMENT 錯誤。

priceLevels[]

enum (PriceLevel)

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

strictTypeFiltering

boolean

用於為 includedType 設定嚴格類型篩選。如果設為 true,系統只會傳回相同類型的結果。預設值為 false。

locationBias

object (LocationBias)

要搜尋的區域。這個位置會做為偏差,也就是說,系統可能會傳回指定位置附近的結果。無法與 locationRestriction 一併設定。

locationRestriction

object (LocationRestriction)

要搜尋的區域。這個位置是限制,代表系統不會傳回指定位置以外的結果。無法與 locationBias 一併設定。

evOptions

object (EVOptions)

選用設定。設定地點搜尋要求的可搜尋 EV 選項。

routingParameters

object (RoutingParameters)

選用設定。用於將結果導向其他位置的其他參數。

searchAlongRouteParameters

object (SearchAlongRouteParameters)

選用設定。沿路搜尋的額外參數原型檔。

includePureServiceAreaBusinesses

boolean

選用設定。如果這個欄位設為 true,就包含純區域服務商家。純區域服務商家是指直接為客戶提供送貨或到府服務,但未在商家地址為客戶提供服務的商家。例如清潔或水電服務。這些商家在 Google 地圖上沒有實體地址或地點。地點服務不會針對這些商家傳回欄位,包括 locationplusCode 和其他位置相關欄位。

回應主體

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

回應中結果的排序方式。

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

可搜尋的 EV 選項,適用於地點搜尋要求。

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

number

選用設定。所需的最低充電率 (以千瓦為單位)。系統會篩除收費率低於指定費率的地點。

connectorTypes[]

enum (EVConnectorType)

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

SearchAlongRouteParameters

指定 Routes API 中定義搜尋路徑的預先計算多邊形。沿著路線搜尋的功能類似於使用 locationBiaslocationRestriction 要求選項,可偏向搜尋結果。不過,locationBiaslocationRestriction 選項可讓您指定偏好區域,以便搜尋結果偏重該區域,而這個選項則可讓您偏重某個行程路線。

系統不會保證結果會沿著所提供的路線,而是會在多邊形定義的搜尋區域內,以及 (選用) locationBiaslocationRestriction 中,根據從起點到目的地的最短繞路時間來排序。結果可能會沿著替代路線,尤其是當您提供的多邊形路線未定義從起點到目的地的最佳路線時。

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_polylinepolyline_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

使用者評論的理由。這會標示使用者評論中可能引起使用者興趣的部分。舉例來說,如果搜尋查詢是「firewood pizza」,則審查理由會標示與搜尋查詢相關的文字。

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

是否提供內用服務。