텍스트 검색(신규)

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

이 기능을 사용하려면 Places API (신규), 차세대 Places API입니다. 자세한 내용은 API를 사용 설정합니다.

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

이 서비스는 모호한 주소를 만들 때 특히 유용하며 자동 시스템의 쿼리를 문자열의 주소가 아닌 구성요소는 사업체 뿐만 아니라 있습니다. 모호한 주소 검색어의 예로는 형식이 잘못된 주소가 있습니다. 비즈니스 이름과 같이 주소가 아닌 구성요소가 포함된 요청을 말합니다. 처음 두 예와 같은 요청은 위치 (예: 지역, 위치 제한, 위치 상세 검색)가 설정됩니다.

'서울특별시 강남구 테헤란로 152' 또는 '서울특별시 강남구 테헤란로 152'	영국의 여러 '하이 스트리트' 미국에 있는 여러 '메인 스트리트'가 있습니다. 위치 제한이 없는 한 쿼리는 원하는 결과를 반환하지 않습니다. 설정합니다.
"서울 체인점"	여러 '체인 레스토랑' 뉴욕 지점 상세 주소 또는 도로명도 있습니다.
'10 High Street, Escher UK' 또는 "서울특별시 강남구 테헤란로 152"	영국 에셔 시에는 'High Street'가 1개만 있고, 미국 캘리포니아 주 플레젠튼 시에는 'Main Street'가 1개만 있습니다.
'UniqueRestaurantName New York'	뉴욕에 이 이름을 가진 시설이 하나뿐임 상세 주소 없음 확인할 수 있습니다
'뉴욕 피자 레스토랑'	이 쿼리에는 위치 제한과 '피자 식당'이 포함되어 있습니다. 은 장소 유형도 있습니다. 여러 결과를 반환합니다.
'[phone]'	이 쿼리에는 전화번호가 포함되어 있습니다. 다음에 대한 여러 결과를 반환합니다. 해당 전화번호와 연결된 장소가 표시됩니다. 참고: 검색 시 최상의 결과를 얻으려면 전화번호에 국가 코드와 공백을 차례로 입력하세요. regionCode 설정 매개변수를 사용해야 합니다.

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

GMSPlacesClient searchByTextWithRequest:를 호출하여 텍스트 검색을 요청합니다. 전달 GMSPlaceSearchByTextRequest 객체는 GMSPlaceSearchByTextResultCallback, 응답을 처리합니다

GMSPlaceSearchByTextRequest 객체는 필수 및 선택 매개변수 입니다. 필수 매개변수는 다음과 같습니다.

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

이 텍스트 검색 요청 예시는 응답 GMSPlace 객체가 검색에 각 GMSPlace 객체의 장소 이름과 장소 ID가 포함됩니다. 있습니다. 또한 응답을 필터링하여 유형의 장소만 반환합니다. '음식점'이라고 입력합니다.

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;
      }
    }
  }
];

iOS용 Places Swift SDK (미리보기)

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 객체의 필드 은 비워둘 수 없습니다. 예를 들어 필드 목록에 GMSPlacePropertyPhotos 응답으로 photos 필드를 요청하고 응답에서 photos 필드를 요청합니다. 비어 있으면 응답 GMSPlace 객체에서 생략됩니다.

영업 개시 상태 가져오기

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

참고: 지원 중단된 GMSPlace isOpen: 및 GMSPlace isOpenAtDate: 함수는 정확하지 않을 수 있으며 Places API (신규)와 함께 사용해서는 안 됩니다.

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

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

GMSPlaceIsOpenWithRequest 메서드를 사용하려면 GMSPlace 객체에 다음 필드를 설정해야 합니다.

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

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

응답 isOpenWithRequest개

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

언어	열려 있는 경우 값	닫힌 경우의 값	상태를 알 수 없는 경우 값
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown
GooglePlacesSwift(미리보기)	true	false	nil

isOpenWithRequest 결제

• GMSPlacePropertyUTCOffsetMinutes 및 GMSPlacePropertyBusinessStatus 필드는 Basic Data SKU에 따라 요금이 청구됩니다. 남은 영업시간은 Place Details (Advanced) SKU에 따라 요금이 청구됩니다.
• 이전 요청의 이러한 필드가 GMSPlace 객체에 이미 있는 경우 다시 요금이 청구되지 않습니다.
• 경고 GMSPlace 객체에 이러한 필드가 없으면 Basic Data SKU에 다시 요금이 청구됩니다. 나머지 영업시간에는 Place Details(고급) SKU에 따라 요금이 청구됩니다. 프로젝트에서 isOpenWithRequest를 사용하는 경우 필요한 장소 세부정보를 가져오는 것이 좋습니다.

예: GMSPlaceIsOpenWithRequest 요청 실행

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

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
            }
          }];
          

GooglePlacesSwift

          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
          }
          

필수 매개변수

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"
  참고: 표 B 응답에서만 반환됩니다 다음의 값은 사용할 수 없습니다. 표 B 필터로 사용합니다.

• isOpenNow

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

• isStrictTypeFiltering

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

• locationBias

  검색할 영역을 지정합니다. 이 위치는 편향 역할을 합니다. 즉, 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과가 반환될 수 있습니다.

  locationRestriction 또는 locationBias 중 하나를 지정할 수 있지만 둘 다 지정할 수는 없습니다. locationRestriction는 결과가 포함되어야 하는 리전 및 locationBias 결과가 근처에 있어야 하지만 외부에 있을 수 있는 리전 지정 확인할 수 있습니다.

  참고: locationBias 및 locationRestriction를 모두 생략하면 API는 기본적으로 IP 편향을 사용합니다. IP 바이어스를 통해 API는 기기의 결과에 편향된 IP 주소를 입력하세요.
  참고: locationBias 매개변수는 textQuery에 Market in Barcelona와 같은 명시적인 위치 이 경우 locationBias는 무시됩니다.

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

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

    request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

  • 직사각형은 위도-경도 표시 영역으로, 2로 표현됩니다. 대각선으로 낮은 점과 높은 점들을 마주 보고 있습니다. 최저점은 직사각형의 남서쪽 모서리를 표시하고, 최고점은 직사각형의 북동쪽 모서리를 나타냅니다.

    표시 영역은 즉, 해당 경계를 포함합니다. 위도 경계 범위는 -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 결과가 근처에 있어야 하지만 외부에 있을 수 있는 리전 지정 확인할 수 있습니다.

  참고: 둘 다 생략하는 경우 locationBias 및 locationRestriction 그리고 API 는 기본적으로 IP 바이어스를 사용합니다. IP 상세 검색을 통해 API는 결과를 편중할 수 있습니다.

• 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

  참고: PRICE_LEVEL_FREE은 허용되지 않습니다. 응답을 채우는 데만 사용됩니다.

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

  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 속성입니다. 최대 다섯 개의 GMSPlaceReview 객체입니다. 각 GMSPlaceReview 객체에는 속성 및 작성자 속성이 포함될 수 있습니다. 앱에 리뷰를 표시하는 경우 저작자 표시 또는 작성자 저작자 표시도 표시해야 합니다.

자세한 내용은 기여 분석이 있습니다.