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.id,places.name*
*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.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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」視窗。