- HTTP 要求
- 要求主體
- 回應主體
- RankPreference
- LocationBias
- LocationRestriction
- EVOptions
- SearchAlongRouteParameters
- 折線
- ContextualContent
- 理由
- ReviewJustification
- HighlightedText
- HighlightedTextRange
- BusinessAvailabilityAttributesJustification
以文字查詢為基礎的地點搜尋。
HTTP 要求
POST https://places.googleapis.com/v1/places:searchText
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "textQuery": string, "languageCode": string, "regionCode": string, "rankPreference": enum ( |
欄位 | |
---|---|
text |
必要欄位。文字搜尋的文字查詢。 |
language |
系統會以偏好語言 (如有) 顯示地點詳細資料。如果未指定語言代碼或系統無法辨識,系統可能會傳回任何語言的詳細資料,並優先使用英文 (如果有此類詳細資料的話)。 目前支援的語言清單:https://developers.google.com/maps/faq#languagesupport。 |
region |
要求來源地點的 Unicode 國家/地區代碼 (CLDR)。這個參數可用來顯示地點詳細資料,例如特定區域的地點名稱 (如有)。這個參數可能會影響根據適用法律產生的結果。 詳情請參閱 https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html。 請注意,系統目前不支援 3 位數區域代碼。 |
rank |
回應中結果的排序方式。 |
included |
要求的地點類型。支援的類型完整清單:https://developers.google.com/maps/documentation/places/web-service/place-types。僅支援一種內含類型。 |
open |
用於將搜尋範圍限制在目前營業中的地點。預設值為 false。 |
min |
篩除平均使用者評分低於此限制的結果。有效值必須是介於 0 和 5 (含) 之間的浮點值,且步進為 0.5,也就是 [0, 0.5, 1.0, ... , 5.0] 之間的值 (含)。輸入的評分會進位至最接近的 0.5(上限)。舉例來說,評分為 0.6 的結果會排除所有評分低於 1.0 的結果。 |
maxResultCount |
已淘汰:請改用 每頁可傳回的結果數量上限。如果可用結果的數量大於 如果同時指定 |
page |
選用設定。每頁可傳回的結果數量上限。如果可用結果的數量大於 如果同時指定 |
page |
選用設定。來自先前 TextSearch 呼叫的網頁權杖。提供此項目即可擷取後續網頁。 進行分頁時,提供給 TextSearch 的所有參數 (除了 |
price |
用於將搜尋結果限制在標示為特定價格等級的地點。使用者可以選擇任何價格層級組合。預設會選取所有價格等級。 |
strict |
用於為 includedType 設定嚴格類型篩選。如果設為 true,系統只會傳回相同類型的結果。預設值為 false。 |
location |
要搜尋的區域。這個位置會做為偏差,也就是說,系統可能會傳回指定位置附近的結果。無法與 locationRestriction 一併設定。 |
location |
要搜尋的區域。這個位置是限制,代表系統不會傳回指定位置以外的結果。無法與 locationBias 一併設定。 |
ev |
選用設定。設定地點搜尋要求的可搜尋 EV 選項。 |
routing |
選用設定。用於將結果導向其他位置的其他參數。 |
search |
選用設定。沿路搜尋的額外參數原型檔。 |
include |
選用設定。如果這個欄位設為 true,就包含純區域服務商家。純區域服務商家是指直接為客戶提供送貨或到府服務,但未在商家地址為客戶提供服務的商家。例如清潔或水電服務。這些商家在 Google 地圖上沒有實體地址或地點。地點服務不會針對這些商家傳回欄位,包括 |
回應主體
places.searchText 的回應原型。
如果成功,回應主體會含有以下結構的資料:
JSON 表示法 |
---|
{ "places": [ { object ( |
欄位 | |
---|---|
places[] |
符合使用者文字搜尋條件的地點清單。 |
routing |
路徑摘要清單,其中每個項目都會連結至 |
contextual |
實驗功能:詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。 內容關聯清單,其中每個項目都會與地點欄位中相同索引的對應地點建立關聯。建議使用與要求中 |
next |
可做為 |
search |
使用者可以透過連結,以 Google 地圖上要求中指定的文字查詢進行搜尋。 |
RankPreference
回應中結果的排序方式。
列舉 | |
---|---|
RANK_PREFERENCE_UNSPECIFIED |
如果是類別查詢 (例如「紐約市的餐廳」),預設值為 RELEVANCE。對於非分類查詢 (例如「Mountain View, CA」),建議您不要設定 rankPreference。 |
DISTANCE |
依距離排序結果。 |
RELEVANCE |
依關聯性排序結果。排序順序由一般排名堆疊決定。 |
LocationBias
要搜尋的區域。這個位置會做為偏差,也就是說,系統可能會傳回指定位置附近的結果。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
rectangle |
由東北角和西南角定義的矩形框。 |
circle |
以圓心和半徑定義的圓形。 |
LocationRestriction
要搜尋的區域。這個位置是限制,代表系統不會傳回指定位置以外的結果。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
rectangle |
由東北角和西南角定義的矩形框。 |
EVOptions
可搜尋的 EV 選項,適用於地點搜尋要求。
JSON 表示法 |
---|
{
"minimumChargingRateKw": number,
"connectorTypes": [
enum ( |
欄位 | |
---|---|
minimum |
選用設定。所需的最低充電率 (以千瓦為單位)。系統會篩除收費率低於指定費率的地點。 |
connector |
選用設定。偏好的電動車連接器類型清單。系統會篩除不支援任何所列連接器類型的地方。 |
SearchAlongRouteParameters
指定 Routes API 中定義搜尋路徑的預先計算多邊形。沿著路線搜尋的功能類似於使用 locationBias
或 locationRestriction
要求選項,可偏向搜尋結果。不過,locationBias
和 locationRestriction
選項可讓您指定偏好區域,以便搜尋結果偏重該區域,而這個選項則可讓您偏重某個行程路線。
系統不會保證結果會沿著所提供的路線,而是會在多邊形定義的搜尋區域內,以及 (選用) locationBias
或 locationRestriction
中,根據從起點到目的地的最短繞路時間來排序。結果可能會沿著替代路線,尤其是當您提供的多邊形路線未定義從起點到目的地的最佳路線時。
JSON 表示法 |
---|
{
"polyline": {
object ( |
欄位 | |
---|---|
polyline |
必要欄位。路線折線。 |
折線
路線折線。僅支援已編碼的折線,可做為字串傳遞,並包含壓縮功能,以盡量減少資料損失。這是 Routes API 的預設輸出內容。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位 polyline_type 。封裝折線類型。Routes API 輸出內容預設為 encoded_polyline 。polyline_type 只能是下列其中一項: |
|
encoded |
已編碼的折線,這是 Routes API 預設傳回的內容。請參閱編碼器和解碼器工具。 |
ContextualContent
實驗功能:詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。
與地點查詢相關的內容。
JSON 表示法 |
---|
{ "reviews": [ { object ( |
欄位 | |
---|---|
reviews[] |
這個地點的評論清單,與地點查詢相關。 |
photos[] |
這個地點的相片資訊 (包括參考資料),與地點查詢相關。 |
justifications[] |
實驗功能:詳情請參閱 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 |
欄位 | |
---|---|
聯集欄位
|
|
review |
實驗功能:詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。 |
business |
實驗功能:詳情請參閱 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 ( |
欄位 | |
---|---|
highlighted |
|
review |
系統根據哪則評論產生標示文字。 |
HighlightedText
由對齊方式醒目顯示的文字。這是評論本身的子集。醒目顯示的確切字詞會標示為 HighlightedTextRange。文字中可能有幾個字詞會被標示。
JSON 表示法 |
---|
{
"text": string,
"highlightedTextRanges": [
{
object ( |
欄位 | |
---|---|
text |
|
highlighted |
醒目顯示文字的範圍清單。 |
HighlightedTextRange
醒目顯示文字的範圍。
JSON 表示法 |
---|
{ "startIndex": integer, "endIndex": integer } |
欄位 | |
---|---|
start |
|
end |
|
BusinessAvailabilityAttributesJustification
實驗功能:詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。BusinessAvailabilityAttributes 屬性理由。這會顯示商家擁有的某些屬性,這些屬性可能會引起使用者的興趣。
JSON 表示法 |
---|
{ "takeout": boolean, "delivery": boolean, "dineIn": boolean } |
欄位 | |
---|---|
takeout |
是否提供外帶服務。 |
delivery |
店家是否提供外送服務。 |
dine |
是否提供內用服務。 |