文字搜尋 (新推出) 會根據字串 (例如「臺北披薩」或「臺北披薩店」或「中正路 123 號」) 傳回一組地點的相關資訊。這項服務會傳回與文字字串和任何位置偏誤設定相符的地點清單。
此服務特別適合用於自動化系統中模糊的地址查詢,且字串的非地址元件可能與商家和地址相符。模稜兩可的地址查詢範例包括格式不正確的地址,或是包含非地址元件 (例如商家名稱) 的要求。下表中前兩個範例的要求可能不會傳回任何結果,除非已設定位置 (例如地區、位置限製或位置自訂調整)。
「10 High Street, UK」或「123 Main Street, US」 | 英國有多個「高街」,美國境內還有多條「主要街道」。 除非已設定位置限制,否則查詢不會傳回符合需求的結果。 |
「臺北中國菜」 | 在紐約有多個「連鎖餐廳」地點;沒有街道地址或甚至街道名稱。 |
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 | 英國 Escher 城市中只有一號「高街」,在美國普萊森頓市只有一道「主要街道」。 |
「Unique 餐廳 Name 紐約」 | 在紐約只使用一間名稱的建築物,不需要區分街道地址。 |
「臺北披薩餐廳」 | 這項查詢包含地點限制,而「披薩餐廳」是定義明確的地點類型。這個方法會傳回多個結果。 |
「+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 (New) 會傳回 以 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: *
請指定下列一或多個欄位:
下列欄位會觸發文字搜尋 (僅限 ID) SKU:
places.id
、places.name
*
*places.name
欄位包含地點資源名稱,格式為:places/PLACE_ID
。使用places.displayName
存取地點的文字名稱。下列欄位會觸發 Text Search (Basic) 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 (Advanced) 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.servesDesserts
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
依最低電動車充電率 (單位為千瓦) 篩選地點。任何充電速率低於最低充電率的地點都會遭到篩除。舉例來說,如要尋找充電速率至少為 10 千瓦的電動車充電器,可以將這項參數設為「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
(依距離排名結果)。 - 如果是非類別查詢 (例如「加州山景城」),建議您不要設定
rankPreference
。
- 如果是如「紐約市餐廳」等類別查詢,系統會預設
regionCode
用於設定回應格式的區碼,指定為 雙字元 CLDR 代碼值。此外,這項參數也會對搜尋結果產生偏誤。沒有預設值。
如果回應中
formattedAddress
欄位的國家/地區名稱與regionCode
相符,則formattedAddress
會省略國家/地區代碼。這個參數對adrFormatAddress
沒有任何影響,後者一律會包含國家/地區名稱 (如果可用) 或shortFormattedAddress
(絕不會包含該名稱)。大多數 CLDR 代碼與 ISO 3166-1 代碼相同,只有少數例外。舉例來說,英國的 ccTLD 是「uk」(.co.uk),而 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。根據適用法律,這個參數可能會影響結果。
strictTypeFiltering
與
includeType
參數搭配使用。如果設為true
,系統只會傳回符合includeType
指定類型的地點。如果為 false,回應會包含與指定類型不符的地點。
Text Search 範例
透過查詢字串尋找地點
以下範例顯示有關「Spicy Vegetarian Food in Australia, Australia」的要求:
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」(詩人素食飲食) 的「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 類型 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 視窗。