텍스트 검색(신규)

텍스트 검색은 문자열을 기반으로 일련의 장소에 대한 정보를 반환합니다. 예: '서울의 피자', '오타와 근처의 신발 가게', '중앙로 123' 이 서비스는 텍스트 문자열 및 설정된 위치 편중과 일치하는 장소 목록을 반환합니다.

이 서비스는 자동화된 시스템에서 모호한 주소 쿼리를 할 때 특히 유용하며 문자열의 주소가 아닌 구성요소가 주소 및 업체와 일치할 수 있습니다. 모호한 주소 쿼리의 예로는 형식이 잘못된 주소 또는 비즈니스 이름과 같이 주소가 아닌 구성요소가 포함된 요청이 있습니다. 처음 두 예와 같은 요청은 위치 (예: 지역, 위치 제한, 위치 상세 검색)가 설정되지 않은 한 0개의 결과를 반환할 수 있습니다.

'10 High Street, UK' 또는 '123 Main Street, US' 영국에 여러 '하이 스트리트', 미국에 여러 '메인 스트리트' 위치 제한이 설정되지 않으면 쿼리가 원하는 결과를 반환하지 않습니다.
"서울 체인점" 뉴욕에 있는 여러 '체인점' 위치가 있지만 상세 주소나 도로명은 없습니다.
'10 High Street, Escher UK' 또는 '123 Main Street, Pleasanton US' 영국 에셔시의 '하이 스트리트' 1곳, 미국 캘리포니아주 플레즌턴 시의 '메인 스트리트' 1곳
'UniqueRestaurantName New York' 뉴욕에서 이 이름을 사용하는 시설이 하나만 있으므로 구별하기 위해 상세 주소가 필요하지 않습니다.
"서울의 피자 가게" 이 쿼리에는 위치 제한이 포함되어 있으며 '피자 레스토랑'은 잘 정의된 장소 유형입니다. 여러 결과를 반환합니다.
'+1 514-670-8700'

이 쿼리에는 전화번호가 포함되어 있습니다. 이 함수는 해당 전화번호와 연결된 장소에 대해 여러 결과를 반환합니다.

텍스트 검색으로 장소 목록 가져오기

GMSPlacesClient searchByTextWithRequest:를 호출하고 요청 매개변수 및 GMSPlaceSearchByTextResultCallback 유형의 콜백 메서드를 정의하는 GMSPlaceSearchByTextRequest 객체를 전달하여 응답을 처리합니다.

GMSPlaceSearchByTextRequest 객체는 요청에 대한 모든 필수 매개변수와 선택 매개변수를 지정합니다. 필수 매개변수는 다음과 같습니다.

  • GMSPlaceProperty에 정의된 대로 GMSPlace 객체에서 반환할 필드의 목록으로, 필드 마스크라고도 합니다. 필드 목록에 필드를 하나 이상 지정하지 않거나 필드 목록을 생략하면 호출이 오류를 반환합니다.
  • 텍스트 쿼리

이 텍스트 검색 요청 예에서는 응답 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 API는 일치하는 장소당 하나의 GMSPlace 객체와 함께 GMSPlace 객체의 형태로 일치하는 항목의 배열을 반환합니다.

응답의 GMSPlace 객체에는 데이터 필드와 함께 다음 멤버 함수가 포함되어 있습니다.

  • isOpen는 지정된 시간에 장소의 영업 여부를 계산합니다.
  • isOpenAtDate는 지정된 날짜에 장소의 개점 여부를 계산합니다.

필수 매개변수

GMSPlaceSearchByTextRequest 객체를 사용하여 검색에 필요한 매개변수를 지정합니다.

  • 필드 목록

    반환할 장소 데이터 속성을 지정합니다. 반환할 데이터 필드를 지정하는 GMSPlace 속성의 목록을 전달합니다. 필드 마스크를 생략하면 요청에서 오류가 반환됩니다.

    필드 목록은 불필요한 데이터를 요청하지 않도록 하는 좋은 설계 방법이며 불필요한 처리 시간과 청구 비용을 방지하는 데 도움이 됩니다.

    다음 필드 중 하나 이상을 지정합니다.

    • 다음 필드는 Text Search (ID Only) 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, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

  • textQuery

    검색할 텍스트 문자열입니다(예: '레스토랑', '중앙로 123' 또는 '샌프란시스코에서 방문하기 가장 좋은 장소').

선택적 매개변수

GMSPlaceSearchByTextRequest 객체를 사용하여 검색을 위한 선택적 매개변수를 지정합니다.

  • includedType

    표 A에 정의된 지정된 유형과 일치하는 장소로 결과를 제한합니다. 하나의 유형만 지정할 수 있습니다. 예를 들면 다음과 같습니다.

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

  • isOpenNow

    true인 경우 쿼리 전송 시 영업 중인 장소만 반환합니다. false인 경우 영업 중 상태에 관계없이 모든 비즈니스를 반환합니다. 이 매개변수를 false로 설정하면 Google Places 데이터베이스에 영업시간을 지정하지 않은 장소가 반환됩니다.

  • 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

    쿼리 유형에 따라 응답에서 결과의 순위가 지정되는 방식을 지정합니다.

    • '뉴욕의 식당'과 같은 범주형 쿼리의 경우 .relevance (검색 관련성을 기준으로 결과 순위 지정)가 기본값입니다. rankPreference을 .relevance 또는 .distance (거리별 결과 순위)로 설정할 수 있습니다.
    • 'Mountain View, CA'와 같이 범주형이 아닌 쿼리의 경우 rankPreference을 설정하지 않은 상태로 두는 것이 좋습니다.

  • regionCode

    응답 형식을 지정하는 데 사용되는 지역 코드로, 2자리 CLDR 코드 값으로 지정됩니다. 이 매개변수는 검색결과에도 편향 효과를 줄 수 있습니다. 기본값은 없습니다.

    응답의 주소 필드 국가 이름이 지역 코드와 일치하면 국가 코드가 주소에서 생략됩니다.

    대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 눈에 띄는 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)이지만 ISO 3166-1 코드는 'gb' (기술적으로 '영국 및 북아일랜드' 엔티티)입니다. 매개변수는 관련 법률에 따라 결과에 영향을 미칠 수 있습니다.

앱에 특성 표시

앱이 GMSPlacesClient에서 얻은 정보(예: 사진, 리뷰)를 표시하는 경우 필수 저작자 표시도 표시해야 합니다.

예를 들어 GMSPlacesClient 객체의 reviews 속성에는 최대 5개의 GMSPlaceReview 객체의 배열이 포함됩니다. 각 GMSPlaceReview 객체에는 속성 및 작성자 속성이 포함될 수 있습니다. 앱에서 리뷰를 표시하는 경우 저작자 표시나 작성자의 저작자 표시도 표시해야 합니다.

자세한 내용은 저작자 표시에 관한 문서를 참고하세요.