Text Search (新版)

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

在自動化系統中進行模糊地址查詢時,這項服務特別實用,而且字串的非地址元件可能會與商家和地址相符。模稜兩可的地址查詢範例是格式不正確的地址,或包含非地址元件 (例如商家名稱) 的要求。如要傳回零個結果,您必須設定位置 (例如區域、位置限制或位置偏好設定),否則下表中前兩個範例要求可能會傳回零個結果。

「英國 10 號」或「美國中正路 123 號」 英國有許多「High Street」;美國有許多「Main Street」。 除非設定位置限制,否則查詢不會傳回理想結果。
「臺北市中餐廳」 紐約有多個「ChainRestaurant」地點,但沒有街道地址或街道名稱。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 英國城市埃舍 (Escher) 只有一個「High Street」;美國加州普萊森頓 (Pleasanton) 只有一個「Main Street」。
「UniqueRestaurantName New York」 紐約只有一家名稱相同的機構,因此不需要提供街道地址來區分。
「紐約市的披薩餐廳」 這個查詢包含位置限制,且「披薩餐廳」是明確定義的地點類型。並傳回多項結果。
「+1 514-670-8700」

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

您可以透過 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 (新版) 回覆

Text Search (新版) 會傳回 做為回應的 JSON 物件。在回覆中:

  • places 陣列包含所有相符的地點。
  • 陣列中的每個位置都由 Place 物件表示。Place 物件包含單一地點的詳細資訊。
  • 透過要求傳遞的 FieldMask 會指定 Place 物件中傳回的欄位清單。

完整的 JSON 物件格式如下:

{
  "places": [
    {
      object (Place)
    }
  ]
}

必要參數

  • FieldMask

    建立回應欄位遮罩,指定要在回應中傳回的欄位清單。使用網址參數 $fieldsfields,或使用 HTTP 標頭 X-Goog-FieldMask,將回應欄位遮罩傳遞至方法。回應中沒有傳回欄位的預設清單。如果省略欄位遮罩,這個方法會傳回錯誤。

    欄位遮罩是良好的設計做法,可確保您不會要求不必要的資料,有助於避免不必要的處理時間和帳單費用。

    指定要傳回的地點資料類型清單 (以半形逗號分隔)。例如擷取地點的顯示名稱和地址。

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    使用 * 擷取所有欄位。

    X-Goog-FieldMask: *

    指定下列一或多個欄位:

    • 以下欄位會觸發 Text Search (ID Only) SKU

      places.attributionsplaces.idplaces.name*nextPageToken

      *places.name 欄位包含地點資源名稱,格式為:places/PLACE_ID。使用 places.displayName 即可存取地點的文字名稱。
    • 以下欄位會觸發 Text Search (Basic) SKU

      places.accessibilityOptionsplaces.addressComponentsplaces.adrFormatAddressplaces.businessStatusplaces.containingPlacesplaces.displayNameplaces.formattedAddressplaces.googleMapsLinks*places.googleMapsUriplaces.iconBackgroundColorplaces.iconMaskBaseUriplaces.locationplaces.photosplaces.plusCodeplaces.primaryTypeplaces.primaryTypeDisplayNameplaces.pureServiceAreaBusinessplaces.shortFormattedAddressplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport

      *places.googleMapsLinks 欄位處於 GA 前預覽階段,因此不會收費,也就是說,在預覽期間使用時不會產生 $0 的帳單。
    • 以下欄位會觸發 Text Search (Advanced) SKU

      places.currentOpeningHoursplaces.currentSecondaryOpeningHoursplaces.internationalPhoneNumberplaces.nationalPhoneNumberplaces.priceLevelplaces.priceRangeplaces.ratingplaces.regularOpeningHoursplaces.regularSecondaryOpeningHoursplaces.userRatingCountplaces.websiteUri
    • 以下欄位會觸發 Text Search (Preferred) SKU

      places.allowsDogsplaces.curbsidePickupplaces.deliveryplaces.dineInplaces.editorialSummaryplaces.evChargeOptionsplaces.fuelOptionsplaces.goodForChildrenplaces.goodForGroupsplaces.goodForWatchingSportsplaces.liveMusicplaces.menuForChildrenplaces.parkingOptionsplaces.paymentOptionsplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.reviews, places.reviews, places.reservableplaces.restroomplaces.reviewsplaces.routingSummariesplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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

    指定要搜尋的區域。這個位置只是自訂調整,因此可傳回指定位置附近的結果,包括指定區域以外的結果。

    您可以指定 locationRestrictionlocationBias,但不能同時指定兩者。請將 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 的說明。

    您可以指定 locationRestrictionlocationBias,但不能兩者同時指定。請將 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 設為 RELEVANCEDISTANCE (依距離排序結果)。
    • 如果是「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 時,回應可能會包含與指定類型不符的地點。

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 資料欄位新增至 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"
      }
    },
    ...
  ]
}

新增其他選項來精進搜尋結果,例如 includedTypeminRatingrankPreferenceopenNow 和其他參數,請參閱可選參數

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

請使用 locationRestrictionlocationBias (不能同時使用兩者),將搜尋範圍限制在特定區域。請將 locationRestriction 視為指定結果必須位於其中的區域,而 locationBias 視為指定結果必須位於附近,但可位於該區域之外的區域。

使用 locationRestriction 限制區域

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

以下範例顯示紐約市內「素食餐點」的 Text Search 要求。這項要求只會傳回營業中地點的前 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'

搜尋具備最低充電率的電動車充電器

使用 minimumChargingRateKwconnectorTypes 搜尋與電動車相容的可用充電器的地點。

以下範例顯示在加州山景市,針對 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 視窗。