Text Search (新版)

文字搜尋 (新推出) 會根據字串 (例如「臺北披薩」或「臺北披薩店」或「中正路 123 號」) 傳回一組地點的相關資訊。這項服務會傳回與文字字串和任何位置偏誤設定相符的地點清單。

此服務特別適合用於自動化系統中模糊的地址查詢，且字串的非地址元件可能與商家和地址相符。模稜兩可的地址查詢範例包括格式不正確的地址，或是包含非地址元件 (例如商家名稱) 的要求。下表中前兩個範例的要求可能不會傳回任何結果，除非已設定位置 (例如地區、位置限製或位置自訂調整)。

「10 High Street, UK」或「123 Main Street, US」 英國有多個「高街」，美國境內還有多條「主要街道」。 除非已設定位置限制，否則查詢不會傳回符合需求的結果。
「臺北中國菜」 在紐約有多個「連鎖餐廳」地點；沒有街道地址或甚至街道名稱。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 英國 Escher 城市中只有一號「高街」，在美國普萊森頓市只有一道「主要街道」。
「Unique 餐廳 Name 紐約」 在紐約只使用一間名稱的建築物，不需要區分街道地址。
「臺北披薩餐廳」 這項查詢包含地點限制，而「披薩餐廳」是定義明確的地點類型。這個方法會傳回多個結果。
「+1 514-670-8700」

這項查詢包含電話號碼。針對與該電話號碼相關聯的地點，傳回多筆結果。

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

試試看！

Text Search 要求

Text Search 要求是採用下列格式的 HTTP POST 要求：

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

將 JSON 要求內文或標頭中的所有參數，做為 POST 要求的一部分傳遞。例如：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Text Search (新) 回應

Text Search (New) 會傳回 以 JSON 物件做為回應。請在回應中執行下列操作：

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

完整的 JSON 物件格式如下：

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

必要參數

  • FieldMask

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

    欄位遮蓋是不錯的設計做法，可確保您不會要求不必要的資料，避免不必要的處理時間和帳單費用。

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

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

    使用 * 擷取所有欄位。

    X-Goog-FieldMask: *

    請指定下列一或多個欄位：

    • 下列欄位會觸發文字搜尋 (僅限 ID) SKU：

      places.id、places.name*

      * places.name 欄位包含地點資源名稱，格式為：places/PLACE_ID。使用 places.displayName 存取地點的文字名稱。

    • 下列欄位會觸發 Text Search (Basic) SKU：

      places.accessibilityOptions、places.addressComponents、places.adrFormatAddress、places.businessStatus、places.displayName、places.formattedAddress、places.googleMapsUri、places.iconBackgroundColor、places.iconMaskBaseUri、places.location、places.photos、places.plusCode、places.primaryType、places.primaryTypeDisplayName、places.shortFormattedAddress、places.subDestinations、places.types、places.utcOffsetMinutes、places.viewport

    • 下列欄位會觸發 Text Search (Advanced) SKU：

      places.currentOpeningHours、places.currentSecondaryOpeningHours、places.internationalPhoneNumber、places.nationalPhoneNumber、places.priceLevel、places.rating、places.regularOpeningHours、places.regularSecondaryOpeningHours、places.userRatingCount、places.websiteUri

    • 下列欄位會觸發 Text Search (Preferred) SKU：

      places.allowsDogs、 places.curbsidePickup、 places.delivery、 places.dineIn、 places.editorialSummary、 places.evChargeOptions、 places.fuelOptions、 places.goodForChildren、 places.goodForGroups、 places.goodForWatchingSports、 places.liveMusic、 places.menuForChildren、 places.parkingOptions、 places.paymentOptions、 places.outdoorSeating、 places.reservable、 places.restroom、 places.reviews、 /places.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • textQuery

    要搜尋的文字字串，例如「餐廳」、「中正路 123 號」或「臺北最好去的地點」。API 會根據這個字串傳回候選相符項目，並會依據觀察到的關聯性排序結果。

自選參數

  • includedType

    讓系統在結果中只限於符合表 A 定義的指定類型的地點。只能指定一種類型。例如：

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

  • languageCode

    傳回結果時使用的語言。

    • 查看支援語言清單。Google 會經常更新支援的語言，因此這份清單可能會有遺漏。
    • 如未提供 languageCode，API 會預設為 en。如果您指定的語言代碼無效，API 會傳回 INVALID_ARGUMENT 錯誤。
    • API 會盡可能提供使用者和當地使用者都能讀取的街道地址。為了達成這個目標，系統會以當地語言傳回街道地址，並在必要時音譯為可由使用者讀取的指令碼，並觀察慣用語言。所有其他地址都會以偏好語言傳回。地址元件都是以相同語言傳回，從第一個元件中選出。
    • 如果名稱未提供您偏好的語言，API 會使用最接近的值。
    • 偏好語言對於 API 選擇傳回的結果組合及傳回順序的影響微乎其微。地理編碼器解讀縮寫的方式會因語言而異，例如街道類型的縮寫，或者對某種語言可能有效的同義詞。

  • locationBias

    指定要搜尋的區域。這個位置可以做為自訂調整，這表示系統會傳回指定位置周圍的結果，包括指定區域以外的結果。

    您可以指定 locationRestriction 或 locationBias，但不能同時指定兩者。您可以將 locationRestriction 視為指定結果所在的區域，而 locationBias 是用於指定結果的鄰近區域，但可以不在該區域。

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

    • 圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑必須介於 0.0 到 50000.0 (含) 之間。預設半徑為 0.0。例如：

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • 矩形是經緯度可視區域，以兩條對角線對角線和高點對稱。低點標記矩形的西南角，高點則代表矩形的東北角。

      系統會將可視區域視為封閉區域，也就是涵蓋區域的邊界。緯度邊界必須介於 -90 到 90 度 (含) 之間，且經度邊界必須介於 -180 到 180 度 (含) 之間：

      • 如果 low = high，可視區域由該單一點組成。
      • 如果 low.longitude > high.longitude，經度範圍會反轉 (可視區域與 180 度的經度線相交)。
      • 如果 low.longitude = -180 度且 high.longitude = 180 度，可視區域會包含所有經度。
      • 如果 low.longitude = 180 度且 high.longitude = -180 度，則經度範圍為空白。
      • 如果 low.latitude > high.latitude，則緯度範圍是空白。

      必須填入最低和高的值，代表的方塊不得留空。空白的可視區域會導致錯誤。

      舉例來說，以下可視區域涵蓋紐約市：

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    指定要搜尋的區域。系統不會傳回指定區域以外的結果。將區域指定為矩形可視區域。如要瞭解如何定義可視區域，請參閱 locationBias 的說明。

    您可以指定 locationRestriction 或 locationBias，但不能同時指定兩者。您可以將 locationRestriction 視為指定結果所在的區域，而 locationBias 是用於指定結果的鄰近區域，但可以不在該區域。

  • maxResultCount

    指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設) 之間。

  • evOptions

    指定參數，用於識別可用電動車 (EV) 充電連接器和充電速率。

    • connectorTypes

      依據地點的電動車充電連接器類型篩選。不支援任何連接器類型的地點會遭到篩除。支援的電動車充電連接器類型包括綜合 (AC 和 DC) 充電器、Tesla 充電器、GB/T 相容充電器 (適用於中國的電動車快速充電)，以及電源插座。詳情請參閱參考說明文件。

    • minimumChargingRateKw

      依最低電動車充電率 (單位為千瓦) 篩選地點。任何充電速率低於最低充電率的地點都會遭到篩除。舉例來說，如要尋找充電速率至少為 10 千瓦的電動車充電器，可以將這項參數設為「10」。

  • minRating

    限制系統只傳回使用者平均評分大於或等於這個上限的結果。值必須介於 0.0 至 5.0 (含) 之間，以 0.5 為單位。例如：0、0.5、1.0、...、5.0 (含頭尾)。值會無條件進位至最接近的 0.5 倍數。舉例來說，如果值為 0.6，則會排除評分小於 1.0 的所有結果。

  • openNow

    如果設為 true，則僅傳回在查詢時營業中的地點。如果設為 false，則會傳回所有商家 (不論營業狀態為何)。 如果您將這個參數設為 false，系統會傳回 Google 地點介面集資料庫中未指定營業時間的地點。

  • priceLevels

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

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

    例如：

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • rankPreference

    依據查詢類型指定結果在回應中的排名方式：

    • 如果是如「紐約市餐廳」等類別查詢，系統會預設 RELEVANCE (依搜尋關聯性排名結果)。 您可以將 rankPreference 設為 RELEVANCE 或 DISTANCE (依距離排名結果)。
    • 如果是非類別查詢 (例如「加州山景城」)，建議您不要設定 rankPreference。

  • regionCode

    用於設定回應格式的區碼，指定為 雙字元 CLDR 代碼值。此外，這項參數也會對搜尋結果產生偏誤。沒有預設值。

    如果回應中 formattedAddress 欄位的國家/地區名稱與 regionCode 相符，則 formattedAddress 會省略國家/地區代碼。這個參數對 adrFormatAddress 沒有任何影響，後者一律會包含國家/地區名稱 (如果可用) 或 shortFormattedAddress (絕不會包含該名稱)。

    大多數 CLDR 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。根據適用法律，這個參數可能會影響結果。

  • strictTypeFiltering

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

Text Search 範例

透過查詢字串尋找地點

以下範例顯示有關「Spicy Vegetarian Food in Australia, Australia」的要求：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

請注意，X-Goog-FieldMask 標頭會指定回應包含下列資料欄位：places.displayName,places.formattedAddress。隨後回應的形式為：

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

在欄位遮罩中加入更多資料類型，以傳回其他資訊。舉例來說，您可以新增 places.types,places.websiteUri，在回應中加入餐廳類型和網址：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

回應現在會以下列格式顯示：

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

依價格等級篩選地點

使用 priceLevel 選項，篩選出價格為低價位或中價位的餐廳：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

本範例也會使用 X-Goog-FieldMask 標頭，將 places.priceLevel 資料欄位新增至回應，因此格式如下：

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

新增其他選項來縮小搜尋範圍，例如 includedType、minRating、rankPreference、openNow，以及選用參數中所述的其他參數。

搜尋某個區域內的地點

使用 locationRestriction 或 locationBias 將搜尋範圍限制在特定區域，但不能同時使用兩者。您可以將 locationRestriction 視為指定結果必須落在哪個區域，並將 locationBias 視為指定結果的鄰近區域，但可以不在該區域。

下例顯示針對「Spicy Vegetarian Food」(詩人素食飲食) 的「Spicy Vegetarian Food」要求，這項要求調整成在舊金山市中心某點的 500 公尺以內。這項要求只會傳回營業中地點的前 10 筆結果。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food",
  "openNow": true,
  "maxResultCount": 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",
    "maxResultCount": 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
          }
        ]
      }
    }
  ]
}

試試看！

您可以透過 API Explorer 提出範例要求 熟悉 API 和 API 選項

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

  2. 視需要展開「Show standard parameters」，並將 fields 參數設為欄位遮罩。

  3. 視需要編輯要求主體。

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

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