本頁面由 Cloud Translation API 翻譯而成。

Text Search (新版)

選取平台： Android iOS JavaScript 網頁服務

歐洲經濟區 (EEA) 開發人員

簡介

Text Search (新版) 可根據字串 (例如「台南魯肉飯」、「西門町附近的鞋店」或「中正路 123 號」)，傳回一組地點的相關資訊。這項服務會傳回與文字字串及位置自訂調整設定相符的地點清單。

這項服務特別適合在自動化系統中進行不明確的地址查詢，字串中非地址的元件也可能與商家和地址相符。地址查詢不明確的例子包括格式不正確的地址，或是包含非地址元件的要求，例如商家名稱。除非設定位置 (例如區域、位置限制或位置偏誤)，否則下表前兩個範例的要求可能會傳回零個結果。

「10 High Street, UK」或「123 Main Street, US」	英國境內有多條「High Street」；美國境內有多條「Main Street」。除非設定位置限制，否則查詢不會傳回所需結果。
「ChainRestaurant New York」	紐約有多個「ChainRestaurant」地點，但沒有街道地址，甚至連街道名稱都沒有。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」	英國埃舍市只有一條「High Street」，美國加州普萊森頓市也只有一條「Main Street」。
「UniqueRestaurantName New York」	紐約只有一家同名店面，因此不需要街道地址來區分。
「紐約的披薩餐廳」	這項查詢包含位置限制，「披薩餐廳」是明確定義的地點類型。並傳回多筆結果。
「+1 514-670-8700」	這項查詢包含電話號碼。系統會傳回與該電話號碼相關聯的多個地點結果。注意：如要獲得最佳電話號碼搜尋結果，請加入國家/地區代碼，並在後面加上空格，然後將 `regionCode` 參數設為對應的國家/地區代碼。電話號碼格式因國家/地區而異，API 會嘗試傳回這些不同格式的結果。

您可以使用 APIs Explorer 提出即時要求，熟悉 API 和 API 選項：

試試看！

Text Search (新版) 要求

文字搜尋 (新版) 要求是以下形式的 HTTP POST 要求：

https://places.googleapis.com/v1/places:searchText

在 POST 要求中，將所有參數傳遞至 JSON 要求內文或標頭。例如：

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: *
```
萬用字元「*」會選取所有欄位。不過，雖然在開發期間使用該萬用字元沒問題，但 Google 不建議在正式環境中使用萬用字元 (*) 回應欄位遮罩，因為這樣可能會傳回大量資料。
如需使用 places.iconMaskBaseUri 和 places.iconBackgroundColor 的進一步指引，請參閱「地點圖示」一節。

指定下列一或多個欄位：
- 以下欄位會觸發 Text Search Essentials ID Only SKU：
  places.attributions
  places.id
  places.name^*
  nextPageToken
  
  ^* places.name 欄位包含地點資源名稱，格式為 places/PLACE_ID。在 Pro SKU 中使用 places.displayName 存取地點的文字名稱。
- 下列欄位會觸發 Text Search Pro SKU：
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  places.adrFormatAddress
  places.businessStatus
  places.containingPlaces
  places.displayName
  places.formattedAddress
  places.googleMapsLinks^**
  places.googleMapsUri
  places.iconBackgroundColor
  places.iconMaskBaseUri
  places.location
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* 地址描述符號通常適用於印度境內的消費者，其他地區則為實驗功能。
  
  ^**「places.googleMapsLinks」欄位處於正式發布前預覽階段，因此預覽期間的使用費用為 $0，也就是免付費。
- 下列欄位會觸發 Text Search Enterprise SKU：
  places.currentOpeningHours
  places.currentSecondaryOpeningHours
  places.internationalPhoneNumber
  places.nationalPhoneNumber
  places.priceLevel
  places.priceRange
  places.rating
  places.regularOpeningHours
  places.regularSecondaryOpeningHours
  places.userRatingCount
  places.websiteUri
- 下列欄位會觸發 Text Search Enterprise + Atmosphere SKU：
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  places.routingSummaries^*
  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"
注意： 表格 B 中的值只會顯示在回應中。您無法使用「資料表 B」中的值做為篩選器。
視適用性而定，文字搜尋 (新版) 會對特定查詢套用類型篩選器。舉例來說，類型篩選器可能不會套用至特定地址的查詢 (「123 Main Street」)，但幾乎一律會套用至類別查詢 (「附近的商店」或「購物中心」)。

如要對所有查詢套用類型篩選器，請將 strictTypeFiltering 設為 true。
includePureServiceAreaBusinesses

如果設為 true，回應會包含直接為顧客提供送貨或到府服務，但沒有實體店面的商家。如果設為 false，API 只會傳回有實體營業地點的商家。
languageCode

傳回結果時使用的語言。
- 請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
- 如未提供 languageCode，API 會預設為 en。如果您指定無效的語言代碼，API 會傳回 INVALID_ARGUMENT 錯誤。
- API 會盡量提供使用者和當地人都能辨識的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要根據偏好語言，將地址音譯為使用者可讀取的文字。所有其他地址都會以偏好語言顯示。地址元件一律會以同一種語言傳回，而該語言是從第一個元件中選擇。
- 如果偏好語言沒有名稱，API 會使用最接近的名稱。
- 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言，以不同方式解讀縮寫，例如街道類型縮寫，或在某種語言中有效但在另一種語言中無效的同義字。
locationBias

指定要搜尋的區域。這個位置會做為偏誤，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。

您可以指定 locationRestriction 或 locationBias，但不能兩者同時指定。locationRestriction 可視為指定結果必須位於的區域，而 locationBias 則可視為指定結果可能位於或靠近的區域，但結果也可能位於該區域外。

注意： 如果省略 locationBias 和 locationRestriction，API 預設會使用 IP 偏誤。使用 IP 偏誤時，API 會使用裝置的 IP 位址來偏誤結果。

注意： 如果 textQuery 包含明確位置 (例如 Market in Barcelona)，locationBias 參數可能會遭到覆寫。在這種情況下，系統會忽略 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 則可視為指定結果可能位於或靠近的區域，但結果也可能位於該區域外。

注意： 如果省略 locationBias 和 locationRestriction，API 預設會使用 IP 偏誤。使用 IP 偏誤時，API 會使用裝置的 IP 位址來偏誤結果。
maxResultCount (已淘汰)

已淘汰：這個欄位已淘汰，請改用 pageSize。如果同時指定 maxResultCount 和 pageSize，系統會使用 pageSize 並忽略 maxResultCount。

指定每頁顯示的結果數 (介於 1 和 20 之間)。舉例來說，如果將 maxResultCount 值設為 5，第一頁最多會傳回 5 個結果。如果查詢可傳回更多結果，回應會包含 nextPageToken，您可以將其傳遞至後續要求，存取下一頁。

注意：如果 maxResultCount 為 0 或未指定，API 預設會傳回每頁 20 個結果。如果 maxResultCount 大於 20，API 每頁最多只會傳回 20 個結果。
evOptions

指定參數，用於識別可用的電動車充電接頭和充電速率。
- connectorTypes
  
  依地點提供的電動車充電插頭類型篩選。如果地點不支援任何連接器類型，系統會將其篩除。支援的電動車充電接頭類型包括複合式 (AC 和 DC) 充電器、Tesla 充電器、符合 GB/T 標準的充電器 (適用於中國的電動車快速充電)，以及牆壁插座充電器。詳情請參閱參考說明文件。
  - 如要篩選特定支援的連接器結果，請將 connectorTypes 設為該值。舉例來說，如要尋找 J1772 Type 1 連接器，請將 connectorTypes 設為 EV_CONNECTOR_TYPE_J1772。
  - 如要篩選不支援的連結器結果，請將 connectorTypes 設為 EV_CONNECTOR_TYPE_OTHER。
  - 如要篩選牆上插座類型的連接器結果，請將 connectorTypes 設為 EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET。
  - 如要篩選任何連接器類型的結果，請將 connectorTypes 設為 EV_CONNECTOR_TYPE_UNSPECIFIED，或不要為 connectorTypes 設定值。
- minimumChargingRateKw
  
  依最低電動車充電率 (以千瓦為單位) 篩選地點。系統會篩除任何充電費率低於最低費率的地點。舉例來說，如要尋找充電速率至少為 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，您可以將其傳遞至後續要求，存取下一頁。

注意：如果 pageSize 為 0 或未指定，API 預設會傳回每頁 20 個結果。如果 pageSize 大於 20，API 每頁最多只會傳回 20 個結果。
pageToken

指定前一頁回應主體的 nextPageToken。
priceLevels

將搜尋範圍限制在標示為特定價格等級的地點。預設為選取所有價格等級。

下列類型的地點可能會顯示價格等級：
- 餐飲
- 服務
- 購物
如果指定 priceLevels，回應中就不會包含不支援類型的地點。

指定由 PriceLevel 定義的一或多個值陣列。

例如：
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
注意： 要求中不得使用 PRICE_LEVEL_FREE。僅用於填入回覆內容。
rankPreference

根據查詢類型，指定回覆中結果的排序方式：
- 如果是類別查詢 (例如「紐約市的餐廳」)，預設會使用 RELEVANCE (依搜尋關聯性排序結果)。你可以將 rankPreference 設為 RELEVANCE 或 DISTANCE (依距離排序結果)。
- 如果是「Mountain View, CA」等非類別查詢，建議您將 rankPreference 設為未設定。
regionCode

用於格式化回應的區域代碼，指定為雙字元 CLDR 代碼值。這個參數也可能對搜尋結果產生偏誤效應。沒有預設值。

如果回應中 formattedAddress 欄位的國家/地區名稱與 regionCode 相符，則 formattedAddress 會省略國家/地區代碼。這個參數對 adrFormatAddress 沒有影響，因為 adrFormatAddress 一律會納入國家/地區名稱 (如有)，也不會影響 shortFormattedAddress，因為 shortFormattedAddress 一律不會納入國家/地區名稱。

大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(對應到 .co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體)。視適用法律而定，這項參數可能會影響結果。
strictTypeFiltering

與 includedType 參數搭配使用。如果設為 true，系統只會傳回符合 includeType 指定類型的地點。如果設為 false (預設值)，回應中可能會包含與指定類型不符的地點。

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 是指結果必須靠近的區域，但可以超出該區域。

注意： 使用 locationRestriction 時，您只能將區域指定為矩形檢視區塊。使用 locationBias 時，您可以將區域指定為矩形檢視區塊或圓形。

使用 locationRestriction 限制區域

使用 locationRestriction 參數，將查詢結果限制在指定區域。在要求主體中，指定定義區域邊界的 low 和 high 經緯度值。

以下範例顯示紐約市「素食」的文字搜尋 (新版) 要求。這項要求只會傳回前 10 個營業中的地點。

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

使用 locationBias 調整區域

以下範例顯示「素食」的 Text Search (新版) 要求，並將搜尋範圍限制在舊金山市中心某個點的 500 公尺內。這項要求只會傳回前 10 個營業中的地點。

curl -X POST -d '{
  "textQuery" : "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 電動車充電接頭，且最低充電速率為 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
          }
        ]
      }
    }
  ]
}

搜尋區域服務商家

使用 includePureServiceAreaBusinesses 參數搜尋沒有實體服務地址的商家 (例如行動清潔服務或餐車)。

以下範例顯示在舊金山尋找水電工的要求：

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-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'

在回應中，沒有實體服務地址的商家不會包含 formattedAddress 欄位：

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

指定每頁傳回的結果數

使用 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"
}

取得地址描述元

地址描述符提供地點位置的關係資訊，包括附近地標和所屬區域。

以下範例顯示聖荷西購物中心附近地點的文字搜尋 (新版) 要求。在本例中，您會在欄位遮罩中加入 addressDescriptors：

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

回應會包含要求中指定的地點、附近地標清單和地標與地點的距離，以及區域清單和區域與地點的包含關係：

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

試試看！

您可以使用 APIs Explorer 提出範例要求，熟悉 API 和 API 選項。

選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen 即可展開 APIs Explorer 視窗。

Text Search (新版)

簡介

Text Search (新版) 要求

Text Search (新版) 回應

必要參數

FieldMask

textQuery

選用參數

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

maxResultCount (已淘汰)

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering

Text Search (新版) 範例

透過查詢字串尋找地點

依價位篩選地點

將搜尋範圍限制在特定區域

使用 locationRestriction 限制區域

使用 locationBias 調整區域

搜尋充電速率下限的電動車充電器

搜尋區域服務商家

指定每頁傳回的結果數

取得地址描述元

試試看！