Text Search (新版)

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

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

簡介

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

除了必要參數，Text Search (新版) 也支援使用選用參數來調整查詢，以獲得更理想的結果。

您可以使用 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: *

    指定下列一或多個欄位：

    • 以下欄位會觸發 Text Search Essentials ID Only SKU：

      places.attributions
      places.id
      places.name*
      nextPageToken
      places.movedPlace
      places.movedPlaceId

      * 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.searchUri
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * 地址描述符號通常適用於印度境內的消費者，其他地區則為實驗功能。

    • 下列欄位會觸發 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
      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 會根據這個字串傳回候選相符項目，並會依據觀察到的關聯性排序結果。

    Text Search (新版) 不適用於模稜兩可的查詢，包括：

    查詢類型 範例
    概念或限制過多，例如單一查詢中包含多個地點、道路或城市名稱 「Market Street San Francisco San Jose Airport」
    Google 地圖未顯示郵政地址元素 「C/O John Smith 123 Main Street」
    「P.O. Box 13 San Francisco」
    商家、連鎖店或類別的名稱，加上這些實體不適用的地點 「德州達拉斯附近的 Tesco」
    有多種解讀方式的模稜兩可查詢 「充電器退貨」
    不再使用的舊名稱 "Middlesex United Kingdom"
    非地理空間元素或意圖 「Ventura Harbor 有幾艘船？」
    非官方或自訂名稱 「The Jenga」
    「The Helter Skelter」
    經緯度座標 「37.422131,-122.084801」

選用參數

  • includedType

    讓系統在結果中只顯示符合表 A 所定義類型的地點。只能指定一個類型。例如：

    • "includedType":"bar"
    • "includedType":"pharmacy"

    視適用性而定，文字搜尋 (新版) 會對特定查詢套用類型篩選條件。舉例來說，類型篩選器可能不會套用至特定地址的查詢 (「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 則可視為指定結果可能位於或靠近的區域，但結果也可能位於該區域外。

    將區域指定為矩形可視區域或圓形。

    • 圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑必須介於 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

    指定參數，用於識別可用的電動車充電接頭和充電速率。

    • 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，您可以將其傳遞至後續要求，存取下一頁。

  • pageToken

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

  • priceLevels

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

    下列類型的地點可能會顯示價格等級：

    如果指定 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，系統只會傳回符合 includedType 指定類型的地點。如果設為 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 限制區域

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

取得地址描述元

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

以下範例顯示聖荷西購物中心附近的 Text Search (新版) 地點要求。在本例中，您會在欄位遮罩中加入 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 選項。

  1. 選取頁面右側的 API 圖示 api。

  2. 視需要編輯要求參數。

  3. 選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。

  4. 在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen 即可展開 APIs Explorer 視窗。