텍스트 검색(신규)

플랫폼 선택: Android iOS JavaScript 웹 서비스

유럽 경제 지역 (EEA) 개발자

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

필수 매개변수 외에도 텍스트 검색 (신규)은 더 나은 결과를 위해 선택적 매개변수를 사용하여 쿼리 구체화를 지원합니다.

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

요청 매개변수와 응답을 처리할 콜백 메서드(GMSPlaceSearchByTextResultCallback 유형)를 정의하는 GMSPlaceSearchByTextRequest 객체를 전달하여 GMSPlacesClient searchByTextWithRequest:를 호출하여 텍스트 검색 요청을 합니다.

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

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

이 예시 텍스트 검색 요청은 응답 GMSPlace 객체에 검색 결과의 각 GMSPlace 객체에 대한 장소 이름과 장소 ID가 포함되도록 지정합니다. 또한 응답을 필터링하여 '음식점' 유형의 장소만 반환합니다.

Places Swift SDK

let restriction = GMSPlaceRectangularLocationOption(
      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
}

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

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
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(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.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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 (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

텍스트 검색 응답

텍스트 검색 API는 일치하는 장소당 하나의 GMSPlace 객체가 있는 형식의 GMSPlace 객체 형식으로 일치하는 항목의 배열을 반환합니다.

영업 상태 가져오기

GMSPlacesClient 객체에는 호출에 지정된 시간을 기준으로 장소가 현재 영업 중인지 여부를 나타내는 응답을 반환하는 isOpenWithRequest (Swift의 경우 isOpenRequest, GooglePlacesSwift의 경우 isPlaceOpenRequest)라는 멤버 함수가 포함되어 있습니다.

이 메서드는 다음을 포함하는 GMSPlaceIsOpenWithRequest 유형의 단일 인수를 사용합니다.

  • GMSPlace 객체 또는 장소 ID를 지정하는 문자열 필요한 필드로 장소 객체를 만드는 방법에 관한 자세한 내용은 장소 세부정보를 참고하세요.
  • 확인하려는 시간을 지정하는 선택적 NSDate (Obj-C) 또는 Date (Swift) 객체 시간이 지정되지 않은 경우 기본값은 현재입니다.
  • 응답을 처리하는 GMSPlaceOpenStatusResponseCallback 메서드
  • >

GMSPlaceIsOpenWithRequest 메서드에는 GMSPlace 객체에 다음 필드가 설정되어 있어야 합니다.

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

이러한 필드가 장소 객체에 제공되지 않거나 장소 ID를 전달하는 경우 메서드는 GMSPlacesClient GMSFetchPlaceRequest:를 사용하여 가져옵니다.

isOpenWithRequest 응답

isOpenWithRequest는 비즈니스가 영업 중인지, 폐업했는지 또는 상태를 알 수 없는지 나타내는 status라는 불리언 값이 포함된 GMSPlaceIsOpenResponse 객체를 반환합니다.

언어 영업 중인 경우 값 폐업한 경우 값 상태를 알 수 없는 경우 값
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

isOpenWithRequest 결제

  • GMSPlacePropertyUTCOffsetMinutesGMSPlacePropertyBusinessStatus 필드는 Basic Data SKU에 따라 요금이 청구됩니다. 나머지 영업시간은 Place Details Enterprise SKU에 따라 요금이 청구됩니다.
  • 이전 요청에서 GMSPlace 객체에 이러한 필드가 이미 있는 경우 다시 요금이 청구되지 않습니다.

예: GMSPlaceIsOpenWithRequest 요청하기

다음 예에서는 기존 GMSPlace 객체 내에서 GMSPlaceIsOpenWithRequest를 초기화하는 방법을 보여줍니다.

Places Swift SDK

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }
        

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

페이지로 나누기

텍스트 검색은 첫 번째 텍스트 검색 호출 응답에서 반환되는 페이지로 나누기 객체hasNextPage 불리언을 제공합니다. 다음 페이지를 사용할 수 있는 경우 fetchNextPage() 함수를 사용하여 로드할 수 있습니다.

다음 예에서는 다음 페이지를 사용할 수 있는지 확인한 후 페이지를 로드하는 방법을 보여줍니다.

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}
    

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];
    

필수 매개변수

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

  • 필드 목록

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

    필드 목록은 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있는 좋은 설계 방법입니다.

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

    • 다음 필드는 텍스트 검색 Essentials ID 전용 SKU를 트리거합니다.

      GMSPlacePropertyPlaceID
    • 다음 필드는 텍스트 검색 Pro SKU를 트리거합니다.

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyName
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance
    • 다음 필드는 텍스트 검색 Enterprise SKU를 트리거합니다.

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite
    • 다음 필드는 텍스트 검색 Enterprise Plus SKU를 트리거합니다.

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout
  • textQuery

    검색할 텍스트 문자열(예: '음식점', '중앙로 123 거리' 또는 '샌프란시스코에서 방문하기 좋은 곳')

선택적 매개변수

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

  • includedType

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

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"
  • isOpenNow

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

  • isStrictTypeFiltering

    includeType 매개변수와 함께 사용됩니다. `true`로 설정하면 true, includeType에 지정된 유형과 일치하는 장소만 반환됩니다. 기본값인 false인 경우 응답에 지정된 유형과 일치하지 않는 장소가 포함될 수 있습니다.

  • locationBias

    검색할 영역을 지정합니다. 이 위치는 바이어스로 사용되므로 지정된 영역 외부의 결과를 포함하여 지정된 위치 주변의 결과를 반환할 수 있습니다.

    locationRestriction 또는 locationBias를 지정할 수 있지만 둘 다 지정할 수는 없습니다. locationRestriction은 결과가 포함되어야 하는 리전을 지정하는 것으로 생각하고 locationBias은 결과가 근처에 있어야 하지만 영역 외부에 있을 수 있는 리전을 지정하는 것으로 생각하세요.

    영역을 직사각형 표시 영역 또는 원으로 지정합니다.

    • 원은 중심점과 반지름(미터)으로 정의됩니다. 반지름 은 0.0~50000.0(포함) 사이여야 합니다. 기본 반지름은 0.0입니다. 예를 들면 다음과 같습니다.

      let request = SearchByTextRequest()
      request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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.

    예를 들면 다음과 같습니다.

        let request = SearchByTextRequest()
        request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
  • rankPreference

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

    • '뉴욕 시의 음식점'과 같은 카테고리 쿼리의 경우 .relevance (검색 관련성을 기준으로 결과 순위 지정)가 기본값입니다. rankPreference.relevance 또는 .distance (거리를 기준으로 결과 순위 지정)로 설정할 수 있습니다.
    • '캘리포니아주 마운틴뷰'와 같은 비카테고리 쿼리의 경우 `rankPreference`를 설정하지 않은 상태로 두는 것이 좋습니다.rankPreference
  • regionCode

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

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

    대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk'(.co.uk)이지만 ISO 3166-1 코드는 'gb'(엄밀히 말하면 '영국' 항목의 경우)입니다. 매개변수는 관련 법률에 따라 결과에 영향을 줄 수 있습니다.

  • shouldIncludePureServiceAreaBusinesses

    true인 경우 검색 결과에 순수 방문 서비스 업체가 반환됩니다. 순수 방문 서비스 업체는 고객을 방문하거나 고객에게 직접 서비스를 제공하지만 비즈니스 주소지에서는 고객에게 서비스를 제공하지 않는 비즈니스입니다.

    예를 들면 다음과 같습니다.

    Places Swift SDK

    let request = SearchByTextRequest()
    request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
    request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
        [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
    request.shouldIncludePureServiceAreaBusinesses = YES;

앱에 특성 표시

앱에서 사진, 리뷰와 같이 GMSPlacesClient, 가져온 정보를 표시하는 경우 앱은 필수 저작자 표시도 표시해야 합니다.

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

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