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

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

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

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

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

    使用 * 擷取所有欄位。

    X-Goog-FieldMask: *

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

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

      places.idplaces.name*

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

      places.accessibilityOptionsplaces.addressComponentsplaces.adrFormatAddressplaces.businessStatusplaces.displayNameplaces.formattedAddressplaces.googleMapsUriplaces.iconBackgroundColorplaces.iconMaskBaseUriplaces.locationplaces.photosplaces.plusCodeplaces.primaryTypeplaces.primaryTypeDisplayNameplaces.shortFormattedAddressplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport
    • 下列欄位會觸發 Text Search (Advanced) SKU

      places.currentOpeningHoursplaces.currentSecondaryOpeningHoursplaces.internationalPhoneNumberplaces.nationalPhoneNumberplaces.priceLevelplaces.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.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

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

    您可以指定 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 (預設) 之間。

  • 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 設為 RELEVANCEDISTANCE (依距離排名結果)。
    • 如果是非類別查詢 (例如「加州山景城」),建議您不要設定 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"
      }
    },
    ...
  ]
}

新增其他選項來縮小搜尋範圍,例如 includedTypeminRatingrankPreferenceopenNow,以及選用參數中所述的其他參數。

搜尋某個區域內的地點

使用 locationRestrictionlocationBias 將搜尋範圍限制在特定區域,但不能同時使用兩者。您可以將 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'

搜尋採用最低充電速率的電動車充電器

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

以下範例顯示 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. 視需要展開「Show standard parameters」,並將 fields 參數設為欄位遮罩

  2. 視需要編輯要求主體

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