Text Search

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」

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

透過文字搜尋取得地點清單

Places SDK for iOS (新版) 中的文字搜尋要求應採用下列格式：

Swift

func testPlaceSearchByTextRequestGMPSRequestCreationWithProperties() {
  let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID];
  let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties)
  request.isOpenNow = true
  request.includedType = "restaurant"
  request.maxResultCount = 5
  request.minRating = 3.5
  request.rankPreference = .distance
  request.isStrictTypeFiltering = true
  request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
  request.locationRestriction = GMSPlaceRectangularLocationOption(
       CLLocationCoordinate2D(latitude: 20, longitude: 30),
       CLLocationCoordinate2D(latitude: 40, longitude: 50)
  )
}

Objective-C

- (void)testPlaceSearchByTextRequestGMPSRequestCreationWithProperties {
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationRestriction = GMSPlaceRectangularLocationOption(
    CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50));
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.0);
}

必要參數

  • 欄位清單

    指定要傳回的地點資料屬性。傳遞 GMSPlace 屬性清單，指定要傳回的資料欄位。如果您省略欄位遮罩，要求會傳回錯誤。

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

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

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

      GMSPlacePropertyPlaceID、GMSPlacePropertyName

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

      GMSPlacePropertyAddressComponents、GMSPlacePropertyBusinessStatus、GMSPlacePropertyFormattedAddress、GMSPlacePropertyIconBackgroundColor、GMSPlacePropertyIconImageURL、GMSPlacePropertyCoordinate、GMSPlacePropertyPhotos、GMSPlacePropertyPlusCode、GMSPlacePropertyTypes、GMSPlacePropertyUTCOffsetMinutes、GMSPlacePropertyViewport、GMSPlacePropertyWheelchairAccessibleEntrance

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

      GMSPlacePropertyCurrentOpeningHours、GMSPlacePropertySecondaryOpeningHours、GMSPlacePropertyPhoneNumber、GMSPlacePropertyPriceLevel、GMSPlacePropertyRating、GMSPlacePropertyOpeningHours、GMSPlacePropertyUserRatingsTotal、GMSPlacePropertyWebsite

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

      GMSPlacePropertyCurbsidePickup、GMSPlacePropertyDelivery、GMSPlacePropertyDineIn、GMSPlacePropertyEditorialSummary、GMSPlacePropertyReservable、GMSPlacePropertyServesBeer、GMSPlacePropertyServesBreakfast、GMSPlacePropertyServesBrunch、GMSPlacePropertyServesDinner、GMSPlacePropertyServesLunch、GMSPlacePropertyServesVegetarianFood、GMSPlacePropertyServesWine、GMSPlacePropertyTakeout

  • textQuery

    要搜尋的文字字串，例如「餐廳」、「中正路 123 號」或「臺北最好去的地點」。

自選參數

  • includedType

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

    • request.includedType = "bar"
    • request.includedType = "pharmacy"

  • isOpenNow

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

  • isStrictTypeFiltering

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

  • locationBias

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

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

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

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

      request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.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，則緯度範圍是空白。

  • locationRestriction

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

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

  • maxResultCount

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

  • minRating

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

  • priceLevels

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

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

    例如：

    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    指定結果在回應中的排名方式。根據預設，API 會使用 RELEVANCE (如適用)。舉例來說，如果是「臺北餐廳」這類查詢，則預設值為 RELEVANCE。如果是地理區域查詢 (例如「加州山景城」)，或其他類型的查詢，系統不會套用任何預設值，而且結果會依照後端傳回的順序顯示。

    相關的值包括：

    • .distance：依距離排名結果。
    • .relevance：依關聯性將結果排名。

  • regionCode

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

    如果回應中地址欄位的國家/地區名稱與區碼相符，則地址會省略國家/地區代碼。

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

Text Search 回應

Text Search API 會以 GMSPlace 物件的形式傳回相符項目陣列，每個相符地點都有一個 GMSPlace 物件。