Text Search (新版)

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

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」

這個查詢包含電話號碼。這個 API 會傳回與該電話號碼相關聯的地點多筆結果。

您可以透過 API Explorer 提出即時要求，熟悉 API 和 API 選項：

試試看！

文字搜尋要求

文字搜尋要求是以下格式的 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 (新版) 回覆

文字搜尋 (新版) 會傳回 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 (Basic) SKU：

      places.accessibilityOptions、places.addressComponents、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.primaryType、places.primaryTypeDisplayName、places.pureServiceAreaBusiness、places.shortFormattedAddress、places.subDestinations、places.types、places.utcOffsetMinutes、places.viewport

      *places.googleMapsLinks 欄位處於 GA 前預覽階段，因此不會收費，也就是說，在預覽期間使用時不會產生 $0 的帳單。

    • 以下欄位會觸發 Text Search (Advanced) 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 (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.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"

  • 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

    指定用於識別可用的電動車 (EV) 充電接頭和充電費率的參數。

    • connectorTypes

      依據地點提供的電動車充電連接器類型進行篩選。系統會篩除不支援任何連接器類型的地方。支援的電動車充電連接器類型包括組合式 (AC 和 DC) 充電器、Tesla 充電器、符合 GB/T 標準的充電器 (適用於中國的電動車快速充電)，以及牆壁插座充電器。詳情請參閱參考說明文件。

      • 如要篩選特定支援的連接器的結果，請將 connectorTypes 設為該值。例如，如要尋找 J1772 類型 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

      依據最低電動車充電率 (以千瓦 [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 沒有影響，因為 adrFormatAddress 一律會在可用時加入國家/地區名稱，而 shortFormattedAddress 則永遠不會加入國家/地區名稱。

    大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是「大不列顛與北愛爾蘭聯合王國」實體)。這個參數可能會影響根據適用法律產生的結果。

  • strictTypeFiltering

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

文字搜尋範例

透過查詢字串尋找地點

以下範例顯示「Spicy Vegetarian Food in Sydney, 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 資料欄位新增至 response，因此格式如下：

{
  "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 將廣告調整至某個區域

以下範例顯示「vegetarian food」的文字搜尋要求，偏向舊金山市區某個地點 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"
}

試試看！

您可以使用 API Explorer 建立範例要求，熟悉 API 和 API 選項。

  1. 選取頁面右側的 API 圖示 展開 API Explorer。。

  2. 您可以選擇展開「顯示標準參數」，然後將 fields 參數設為欄位遮罩。

  3. 您可以選擇編輯要求主體。

  4. 選取「執行」按鈕。在彈出式對話方塊中，選擇要用來提出要求的帳戶。

  5. 在 API Explorer 面板中，選取展開圖示 展開 API Explorer。 來展開 API Explorer 視窗。