Text Search (新版) 會根據字串,傳回一組地點的相關資訊。舉例來說, 「臺北披薩」或「渥太華附近的鞋店」或「中正路 123 號」。 服務會傳回與文字字串和任何位置相符的地點清單 預測出的偏誤
這項服務特別適合用來 模稜兩可的地址查詢 中的非地址元件可能會相符 以及地址模稜兩可的地址查詢示例如下: 地址格式有誤,或是包含非地址元件的要求,例如 。如下表前兩個範例類似的要求 除非指定地點 (例如區域、位置),否則可能會傳回零結果 限製或位置自訂調整,
「英國 10 號高街」或「美國中正路 123 號」 | 英國的多個「高街」;美國境內的多個「主街」。 除非有地點限制,否則查詢不會傳回理想的結果 設定。 |
「臺北市中餐廳」 | 多個「中國餐廳」臺北市無街道地址, 甚至是街道名稱 |
「10 High Street, Escher UK」或「美國臺北市中正區 123 號」 | 只有一個「高街」;只有一個「中正路」 美國境內 Pleasanton 的用戶。 |
「UniqueRestaurantName New York」 | 紐約地只有一間同名的建築物;無街道地址 以便區分。 |
「臺北市的披薩店」 | 這項查詢包含其位置限制和「披薩餐廳」為 定義明確的地點類型並傳回多項結果。 |
「+1 514-670-8700」 | 這項查詢包含電話號碼。它會傳回多個以下項目的結果: 與該組電話號碼相關聯的地點。 |
API Explorer 可讓您發出即時要求,以便熟悉 API 以及 API 選項:
Text Search 要求
Text Search 要求是一種 HTTP POST 要求,格式如下:
https://places.googleapis.com/v1/places:searchText
將 JSON 要求主體或標頭中的所有參數,做為 POST 要求。例如:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \ 'https://places.googleapis.com/v1/places:searchText'
Text Search (新版) 回應
Text Search (新版) 會傳回 做為回應的 JSON 物件。在回覆中:
完整的 JSON 物件的格式為:
{ "places": [ { object (Place) } ] }
必要參數
-
FieldMask
建立 回應欄位遮罩。 使用網址參數將回應欄位遮罩傳遞至方法
$fields
或fields
,或是使用 HTTP 標頭X-Goog-FieldMask
。回應中沒有傳回欄位的預設清單。 如果省略欄位遮罩,這個方法會傳回錯誤。欄位遮蓋是不錯的設計做法,可確保您不要要求。 不必要的資料,有助於避免不必要的處理時間,並 帳單費用。
指定要傳回的地點資料類型清單 (以半形逗號分隔)。例如: 來擷取地點的顯示名稱和地址。
X-Goog-FieldMask: places.displayName,places.formattedAddress
使用
*
擷取所有欄位。X-Goog-FieldMask: *
指定下列一或多個欄位:
下列欄位會觸發 Text Search (ID Only) SKU:
places.attributions
,places.id
,places.name
*、nextPageToken
*places.name
欄位含有地點「資源名稱」 格式:places/PLACE_ID
。使用「places.displayName
」 存取地點的文字名稱。下列欄位會觸發 Text Search (基本) SKU:
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.location
,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
。下列欄位會觸發 Text Search (進階) SKU:
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
下列欄位會觸發 Text Search (Preferred) SKU:
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.servesBeer
,places.servesBreakfast
,places.servesBrunch
,places.servesCocktails
,places.servesCoffee
,places.servesDessert
,places.servesDinner
,places.servesLunch
,places.servesVegetarianFood
,places.servesWine
,places.takeout
-
textQuery
要搜尋的文字字串,例如「餐廳」、 「中正路 123 號」或「舊金山最佳去處」。API 根據比對結果傳回可能相符的候選廣告 並依照觀察到的關聯性排序結果。
選用參數
includedType
限制在結果中只顯示符合 指定類型 的地點 表 A. 您只能指定一個類型。例如:
"includedType":"bar"
"includedType":"pharmacy"
languageCode
傳回結果時使用的語言。
- 詳情請參閱 支援的語言清單。 Google 經常更新支援的語言,因此這份清單可能不會列出 完整詳盡。
-
如未提供
languageCode
,API 會預設為en
。如果指定的語言代碼無效,API 會傳回INVALID_ARGUMENT
錯誤。 - API 會盡可能提供容易理解的街道地址 使用者和當地使用者為達成該目標,它回到了街道 將位址音譯為指令碼 使用者就會在必要時看到偏好的語言所有其他 系統會以偏好語言傳回地址。地址元件為 所有傳回的結果都是使用相同語言,也就是從第一個語言 元件。
- 如果未提供偏好語言的名稱,API 會使用 最接近的相符項目。
- 偏好的語言對於 Google 提供的 API 選擇傳回的 物件,以及傳回的順序。 地理編碼器會根據語言,以不同方式解讀縮寫 例如街道類型的縮寫 且在某種語言中有效,但是沒有另一種語言。
locationBias
指定要搜尋的區域。這個位置只是偏見 可以傳回指定位置附近的結果,包括 結果 指定區域外。
您可以指定
locationRestriction
或locationBias
但不能同時採用兩者您可以將locationRestriction
想成是指定 結果所在的區域,以及locationBias
為 用於指定結果必須鄰近的區域,但可以位於 這個區域請將區域指定為矩形可視區域或圓形。
圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑 必須介於 0.0 至 50000.0 (含) 之間。預設半徑為 0.0。 例如:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
矩形是經緯度可視區域,以兩個 沿著低點和高點對角線。低點標示西南方 矩形的角落,高點代表東北方
我們將可視區域視為 封閉區域,表示包含其邊界。緯度界限 必須介於 -90 到 90 度 (含經度邊界) 之間 必須介於 -180 到 180 度之間 (含首尾):
- 如果
low
=high
,表示可視區域由 單一點 - 如果
low.longitude
>high.longitude
, 經度範圍會反轉 (可視區域跨越 180 度 經度線)。 - 如果
low.longitude
= -180 度,且high.longitude
= 180 度,可視區域包含所有 經度 - 如果
low.longitude
= 180 度,且high.longitude
= -180 度,經度範圍是 並將空無一物。 - 如果
low.latitude
>high.latitude
, 緯度範圍空白。
請務必填入最低和高分,且表示方塊不得 並將空無一物。空白的可視區域會導致錯誤。
舉例來說,這個可視區域會完整涵蓋紐約市:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- 如果
locationRestriction
指定要搜尋的區域。不是指定區域以外的結果 。將區域指定為矩形可視區域。查看說明 /
locationBias
以瞭解定義檢視點的相關資訊。您可以指定
locationRestriction
或locationBias
但不能同時採用兩者您可以將locationRestriction
想成是指定 結果所在的區域,以及locationBias
為 用於指定結果必須鄰近的區域,但可以位於 這個區域-
maxResultCount (已淘汰)
指定每頁顯示的結果數量 (介於 1 到 20 之間)。 舉例來說,如果將
maxResultCount
值設為 5,最多會傳回 5 就能顯示搜尋結果如有其他結果可以傳回 回應中會包含您定義的nextPageToken
傳入後續要求,存取下一頁。 evOptions
指定用來識別可用電動車 (EV) 的參數 充電接頭和充電速率
connectorTypes
依地點提供的電動車充電連接器類型進行篩選。A 罩杯 系統會篩除不支援任何連接器類型的地點。 。 支援的電動車充電連接器類型包括混合 (AC 和 DC) 充電器、 Tesla 充電器、GB/T 相容充電器 (適用於電動車快速充電 中國和電源插座充電器詳情請參閱參考資料 說明文件
minimumChargingRateKw
根據最低電動車充電速率篩選地點,單位為千瓦 (kW)。不限 收費率低於最低充電率的商家是 過濾掉。舉例來說,如要尋找具備充電率的電動車充電器 至少 10 千瓦時,您可以將這個參數設為「10」。
minRating
限制只傳回使用者平均評分大於 的結果 或等於此上限這個值必須介於 0.0 和 5.0 (含) 之間 整數值。例如:0、0.5、1.0、...、5.0 (含)。值為 會四捨五入至最接近的 0.5。舉例來說,如果值是 0.6,就會排除所有 評分低於 1.0 的結果
openNow
如果
true
,請只傳回營業中的地點 寫入時。如果false
,請退回所有商家 不論是否開啟狀態 在 Google 地點介面集資料庫中,未指定營業時間的地點是指 如果您將這個參數設為false
,就會傳回 。pageSize
指定每頁顯示的結果數量 (介於 1 到 20 之間)。 舉例來說,如果將
pageSize
值設為 5,最多會傳回 5 就能顯示搜尋結果如有其他結果可以傳回 回應中會包含您定義的nextPageToken
傳入後續要求,存取下一頁。pageToken
從回應主體中指定
nextPageToken
上一頁。-
priceLevels
僅搜尋標有特定價位的地點。 預設設定是選取所有價位。
指定由一或多個值定義的陣列
PriceLevel
。例如:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
rankPreference
依據類型 查詢:
- 如果是「紐約市餐廳」這類類別查詢,
RELEVANCE
(依搜尋關聯性排名) 是預設值。 您可以將rankPreference
設為RELEVANCE
或DISTANCE
(依距離排名結果)。 - 如果是非類別查詢,例如「Mountain View, CA」
您未設定
rankPreference
。
- 如果是「紐約市餐廳」這類類別查詢,
regionCode
用於設定回應格式的區碼,以 也就是雙字元 CLDR 代碼值。這個參數可能會造成偏誤 相關的更多內容沒有預設值。
如果
formattedAddress
欄位的國家/地區名稱 回應符合regionCode
,系統會省略國家/地區代碼formattedAddress
起。這個參數不會對adrFormatAddress
,一律包含國家/地區 名稱可用,或是在shortFormattedAddress
上 (永不) 包括他人在內大部分 CLDR 代碼與 ISO 3166-1 代碼相同 有一些值得注意的例外情況舉例來說,英國的 ccTLD 是 「uk」(.co.uk),但 ISO 3166-1 代碼卻是「gb」(技術上來說 「大不列顛暨北愛爾蘭聯合王國」)。 這個參數會根據適用法律影響結果。
strictTypeFiltering
與
includedType
參數搭配使用。設為true
,只顯示符合指定類型的地點 會傳回includeType
。 如果為 false,則回應包含不相符的地點。 指定類型。
Text Search 範例
透過查詢字串尋找地點
以下範例顯示 Text Search 要求: 「位於澳洲雪梨的素食素食餐點」:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
請注意,X-Goog-FieldMask
標頭會指定
回應
包含下列資料欄位:places.displayName,places.formattedAddress
。
回應會採用以下形式:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, { "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Peace Harmony", "languageCode": "en" } }, ... ] }
在欄位遮罩中新增更多資料類型,即可傳回其他資訊。
舉例來說,新增 places.types,places.websiteUri
即可加入
餐廳類型和網址
response:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \ 'https://places.googleapis.com/v1/places:searchText'
回應會以下列形式呈現:
{ "places": [ { "types": [ "vegetarian_restaurant", "vegan_restaurant", "chinese_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "websiteUri": "http://www.motherchusvegetarian.com.au/", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "types": [ "vegan_restaurant", "thai_restaurant", "vegetarian_restaurant", "indian_restaurant", "italian_restaurant", "american_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "websiteUri": "http://www.veggosizzle.com.au/", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
依價格等級篩選地點
使用 priceLevel
選項即可篩選出餐廳搜尋結果
價格較低或中價位:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia", "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"] }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \ 'https://places.googleapis.com/v1/places:searchText'
此範例也使用 X-Goog-FieldMask
標頭,將
改為 places.priceLevel
資料欄位
回覆
它的格式為:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "115 King St, Newtown NSW 2042, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Green Mushroom", "languageCode": "en" } }, ... ] }
新增其他選項來縮小搜尋範圍,例如 includedType
、
minRating
、rankPreference
、openNow
、
以及先前介紹的
自選參數。
搜尋某地區內的地點
使用 locationRestriction
或 locationBias
。
則可將搜尋範圍限制在特定區域。試想 locationRestriction
指定結果所在的區域,locationBias
例如指定結果必須鄰近的區域,但不得位於
這個區域
以下範例顯示 Text Search 要求: 「Spicy Vegetarian Food」(香料素食)偏愛在某個點的 500 公尺內 臺北市大安區這項要求只會傳回前 10 個結果 營業中的商家。
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food", "openNow": true, "pageSize": 10, "locationBias": { "circle": { "center": {"latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } }, }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
搜尋具備最低充電率的電動車充電器
使用 minimumChargingRateKw
和 connectorTypes
:
搜尋哪些地點有與電動車相容的充電器。
以下範例顯示 Tesla 和 J1772 type 1 EV 充電的要求 最低充電功率為 10 kW,位於美國加州山景城。只有四個 系統會傳回結果
curl -X POST -d '{ "textQuery": "EV Charging Station Mountain View", "pageSize": 4, "evOptions": { "minimumChargingRateKw": 10, "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"] } }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \ 'https://places.googleapis.com/v1/places:searchText'
這個要求會傳回下列回應:
{ "places": [ { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 16, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 100, "count": 8, "availableCount": 5, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 2, "availableCount": 2, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 6, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 6, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 4, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 2, "availableCount": 0, "outOfServiceCount": 2, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 5, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_J1772", "maxChargeRateKw": 3.5999999046325684, "count": 1, "availableCount": 0, "outOfServiceCount": 1, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "Electric Vehicle Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 10, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_OTHER", "maxChargeRateKw": 210, "count": 10 } ] } } ] }
指定每頁要傳回的結果數
使用 pageSize
參數,指定要將多少結果傳送給
每頁報酬。回應主體中的 nextPageToken
參數
會提供憑證,可用於後續呼叫,存取
也就是預測結果
以下範例顯示「臺北披薩」的要求上限為 5 次 每頁結果數:
curl -X POST -d '{ "textQuery": "pizza in New York", "pageSize": 5 }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.id,nextPageToken" \ 'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJifIePKtZwokRVZ-UdRGkZzs" }, { "id": "ChIJPxPd_P1YwokRfzLhSiACEoU" }, { "id": "ChIJrXXKn5NZwokR78g0ipCnY60" }, { "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE" }, { "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw" } ], "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }
如要存取下一頁的結果,請使用 pageToken
傳入
要求主體中的 nextPageToken
:
curl -X POST -d '{ "textQuery": "pizza in New York", "pageSize": 5, "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.id,nextPageToken" \ 'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw" }, { "id": "ChIJjaD94kFZwokR-20CXqlpy_4" }, { "id": "ChIJ6ffdpJNZwokRmcafdROM5q0" }, { "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM" }, { "id": "ChIJ8164qwFZwokRhplkmhvq1uE" } ], "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c" }
試試看!
API Explorer 可讓您提出請求範例 熟悉 API 和 API 選項
選取 API 圖示
。 網頁右側。
視需要展開「Show Standard parameters」(顯示標準參數),然後設定
fields
參數設為欄位 遮罩。視需要編輯「要求主體」。
選取「執行」按鈕。在彈出式對話方塊中,選擇要執行哪個帳戶的帳戶 並指定要用於發出要求的選項
在 API Explorer 面板中,選取展開圖示
,展開「API Explorer」視窗。