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」

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

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

呼叫 GMSPlacesClient searchByTextWithRequest: 並傳遞用於定義要求參數和回呼方法 (類型為 GMSPlaceSearchByTextResultCallback) 的 GMSPlaceSearchByTextRequest 物件,即可發出 Text Search 要求來處理回應。

GMSPlaceSearchByTextRequest 物件會指定要求的所有必要選用參數。必要參數包括:

  • 要在 GMSPlace 物件中傳回的欄位清單,該欄位也稱為「欄位遮罩」,由 GMSPlaceProperty 定義。如果您未在欄位清單中指定至少一個欄位,或是省略欄位清單,呼叫會傳回錯誤。
  • 文字查詢

這個文字搜尋要求範例指定 GMSPlace 回應物件,其中包含搜尋結果中每個 GMSPlace 物件的地點名稱和地點 ID。這也會篩選回應,只傳回「餐廳」類型的地點。

Swift

// Create the GMSPlaceSearchByTextRequest object.
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)
)

// Array to hold the places in the response
placeResults = [];

let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  self.placeResults = results
}

GMSPlacesClient.shared().searchByTextWithRequest(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
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);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> _Nullable placeResults, NSError * _Nullable error) {
  if (placeResults.count > 0) {
      // Get list of places.
      _placeResults = placeResults;
  }
}];

GooglePlacesSwift

let restriction = RectangularLocationRestriction(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Text Search 回應

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

除了資料欄位,回應中的 GMSPlace 物件還包含下列成員函式:

  • isOpen 會計算地點在特定時間是否營業中。
  • isOpenAtDate 會計算地點在特定日期是否營業。

必要參數

請使用 GMSPlaceSearchByTextRequest 物件指定搜尋所需的參數。

  • 欄位清單

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

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

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

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

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

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

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

      GMSPlacePropertyCurbsidePickupGMSPlacePropertyDeliveryGMSPlacePropertyDineInGMSPlacePropertyEditorialSummaryGMSPlacePropertyReservableGMSPlacePropertyReviewsGMSPlacePropertyServesBeerGMSPlacePropertyServesBreakfastGMSPlacePropertyServesBrunchGMSPlacePropertyServesDinnerGMSPlacePropertyServesLunchGMSPlacePropertyServesVegetarianFoodGMSPlacePropertyServesWineGMSPlacePropertyTakeout
  • textQuery

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

自選參數

使用 GMSPlaceSearchByTextRequest 物件指定搜尋的選用參數。

  • includedType

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

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

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

  • isStrictTypeFiltering

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

  • locationBias

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

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

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

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

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

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

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

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

在應用程式中顯示作者資訊

如果應用程式顯示從 GMSPlacesClient 取得的資訊 (例如相片和評論),應用程式也必須顯示必要的作者資訊。

例如,GMSPlacesClient 物件的 reviews 屬性包含最多五個 GMSPlaceReview 物件的陣列。每個 GMSPlaceReview 物件皆可包含作者資訊和作者作者資訊。如果您在應用程式中顯示評論,則您也必須顯示所有作者資訊或作者作者資訊。

如需更多資訊,請參閱歸因說明文件。