Text Search (新版) 可根據字串 (例如「台南魯肉飯」、「西門町附近的鞋店」或「中正路 123 號」),傳回一組地點的相關資訊。這項服務會傳回與文字字串和任何位置偏誤設定的地點清單。
此服務特別適合用於自動化系統中明確的地址查詢,而字串的非地址元件可能符合商家和地址。模稜兩可的地址查詢範例是格式不正確的地址,或包含非地址元件 (例如商家名稱) 的要求。按照下表前兩個範例的要求,除非已設定位置 (例如區域、位置限製或位置自訂調整),否則結果可能不會傳回任何結果。
「英國 10 號」或「美國中正路 123 號」 | 英國的多個「高街」;美國的多個「中正路」。 如未設定位置限制,查詢就不會傳回理想的結果。 |
「臺北市中餐廳」 | 紐約有多個「中菜餐廳」地點,沒有街道地址或街道名稱。 |
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 | 英國埃塞爾 (Escher) 的英國城市「高街」;在加州普萊桑頓市內只有一個「Main Street」(主街)。 |
「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 物件。在回覆中:
places
陣列包含所有相符地點。- 陣列中的每個地點都會以
Place
物件表示。Place
物件包含單一地點的詳細資訊。 - 透過要求傳遞的 FieldMask 會指定
Place
物件中傳回的欄位清單。
完整的 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
、places.photos
、places.plusCode
、places.primaryType
下列欄位會觸發 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 會使用最接近的項目。
- 偏好語言對 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
依地點提供的電動車充電連接器類型進行篩選。系統會篩除不支援任何連接器類型的地點。 支援的電動車充電接頭類型包括合併 (AC 和 DC) 充電器、Tesla 充電器、符合 GB/T 規定的充電器 (適用於中國的電動車快速充電),以及電源插座充電器。詳情請參閱參考說明文件。
minimumChargingRateKw
根據最低電動車充電速率篩選地點,單位為千瓦 (kW)。系統會篩除任何充電率低於最低充電率的地點。舉例來說,如要尋找充電率至少為 10 kW 的電動車充電器,請將這個參數設為「10」。
minRating
限制只傳回平均使用者評分大於或等於這個上限的結果。值必須介於 0.0 至 5.0 (含) 之間,以 0.5 為單位。例如:0、0.5、1.0、...、5.0 (含)。值會無條件進位至最接近的 0.5 倍數。舉例來說,如果值是 0.6,則會刪除評分低於 1.0 的所有結果。
openNow
如果設為
true
,則只傳回傳送查詢時營業中的地點。如為false
,則無論營業狀態為何,都傳回所有商家。 如果將這個參數設為false
,系統就會傳回未在 Google 地點介面集資料庫中指定營業時間的地點。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 範例
透過查詢字串尋找地點
以下範例顯示「Spicy Vegetarian Food in Sydney, Sydney」的 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
,即可在回應中加入餐廳類型和網址:
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
則能指定結果必須鄰近但可以超出該區域的區域。
以下範例顯示「Spicy Vegetarian Food」的 Text Search 要求,自訂位置偏誤在舊金山市中心某點 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 類型 1 電動車充電連接器的要求,在加州山景城最低充電速率為 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」視窗。