주변 검색 (신규)

플랫폼 선택: Android iOS JavaScript 웹 서비스
유럽 경제 지역 (EEA) 개발자

주변 검색(신규) 요청은 검색할 지역을 입력으로 사용합니다. 이 지역은 원의 중심점의 위도 및 경도 좌표와 반지름(미터)으로 정의된 원으로 지정됩니다. 요청은 지정된 검색 영역 내에서 일치하는 장소 목록을 반환하며, 각 장소는 GMSPlace 객체로 표시됩니다.

기본적으로 응답에는 검색 영역 내의 모든 유형의 장소가 포함됩니다. 선택적으로 응답에 명시적으로 포함하거나 제외할 장소 유형 목록을 지정하여 응답을 필터링할 수 있습니다. 예를 들어 'restaurant', 'bakery', 'cafe' 유형의 장소만 응답에 포함하거나 'school' 유형의 장소를 모두 제외하도록 지정할 수 있습니다.

Nearby Search (신규) 요청

요청 매개변수와 응답을 처리하는 GMSPlaceSearchNearbyResultCallback 유형의 콜백 메서드를 정의하는 GMSPlaceSearchNearbyRequest 객체를 전달하여 GMSPlacesClient searchNearbyWithRequest:를 호출하여 주변 검색 요청을 합니다.

GMSPlaceSearchNearbyRequest 객체는 요청의 모든 필수 및 선택 매개변수를 지정합니다. 필수 매개변수는 다음과 같습니다.

  • GMSPlace 객체에서 반환할 필드의 목록입니다. GMSPlaceProperty에 의해 정의된 필드 마스크라고도 합니다. 필드 목록에 필드를 하나 이상 지정하지 않거나 필드 목록을 생략하면 호출에서 오류가 반환됩니다.
  • 위치 제한, 즉 검색 영역을 정의하는 원입니다.

이 예시 주변 검색 요청은 검색 결과의 각 GMSPlace 객체에 대한 장소 이름 (GMSPlacePropertyName)과 장소 좌표(GMSPlacePropertyCoordinate)가 응답 GMSPlace 객체에 포함되도록 지정합니다. 또한 '레스토랑' 및 '카페' 유형의 장소만 반환하도록 응답을 필터링합니다.

Places Swift SDK

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [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().searchNearby(with: request, callback: callback)

Objective-C

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

주변 검색 응답

주변 검색 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 결제

  • GMSPlacePropertyUTCOffsetMinutes 및 GMSPlacePropertyBusinessStatus 필드는 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
            }
          }];

필수 매개변수

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

  • 필드 목록

    장소 세부정보를 요청할 때는 장소의 GMSPlace 객체에서 반환할 데이터를 필드 마스크로 지정해야 합니다. 필드 마스크를 정의하려면 GMSPlaceProperty에서 GMSPlaceSearchNearbyRequest 객체로 값 배열을 전달합니다. 필드 마스크를 사용하면 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있습니다.

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

    • 다음 필드는 Nearby Search Pro SKU를 트리거합니다.

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

    • 다음 필드는 Nearby Search Enterprise SKU를 트리거합니다.

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • 다음 필드는 Nearby Search Enterprise Plus SKU를 트리거합니다.

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

    다음 예에서는 요청에서 반환된 GMSPlace 객체에 name 및 placeID 필드가 포함되도록 지정하기 위해 두 개의 필드 값 목록을 전달합니다.

    Places Swift SDK

    // Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

    Swift

    // Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

    Objective-C

    // Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

  • locationRestriction

    검색할 영역을 정의하는 GMSPlaceLocationRestriction 객체입니다. 이 영역은 중심점과 반지름(미터)으로 정의된 원으로 지정됩니다. 반지름은 0.0 이상 50000.0 이하여야 합니다. 기본 반경은 0.0입니다. 요청에서 0.0보다 큰 값으로 설정해야 합니다.

선택적 매개변수

GMSPlaceSearchNearbyRequest 객체를 사용하여 검색의 선택적 매개변수를 지정합니다.

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    검색 결과를 필터링하는 데 사용되는 표 A의 유형 목록을 지정할 수 있습니다. 각 유형 제한 카테고리에서 최대 50개의 유형을 지정할 수 있습니다.

    장소에는 표 A의 유형 중 단일 기본 유형만 연결될 수 있습니다. 예를 들어 기본 유형은 "mexican_restaurant" 또는 "steak_house"일 수 있습니다. includedPrimaryTypes 및 excludedPrimaryTypes를 사용하여 장소의 기본 유형에 따라 결과를 필터링합니다.

    장소에는 표 A의 유형에서 여러 유형 값이 연결될 수도 있습니다. 예를 들어 레스토랑에는 "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" 유형이 있을 수 있습니다. includedTypes 및 excludedTypes를 사용하여 장소와 연결된 유형 목록의 결과를 필터링합니다.

    "restaurant" 또는 "hotel"과 같은 일반적인 기본 유형을 지정하면 응답에 지정된 유형보다 더 구체적인 기본 유형이 있는 장소가 포함될 수 있습니다. 예를 들어 "restaurant" 기본 유형을 포함하도록 지정합니다. 그러면 응답에 기본 유형이 "restaurant"인 장소가 포함될 수 있지만, "chinese_restaurant" 또는 "seafood_restaurant"와 같은 더 구체적인 기본 유형이 있는 장소도 포함될 수 있습니다.

    여러 유형 제한이 지정된 검색의 경우 모든 제한을 충족하는 장소만 반환됩니다. 예를 들어 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}을 지정하면 반환된 장소는 "restaurant" 관련 서비스를 제공하지만 기본적으로 "steak_house"로 운영되지는 않습니다.

    includedTypes

    검색할 표 A의 장소 유형 목록입니다. 이 매개변수를 생략하면 모든 유형의 장소가 반환됩니다.

    excludedTypes

    검색에서 제외할 표 A의 장소 유형 목록입니다.

    요청에 includedTypes (예: "school")와 excludedTypes (예: "primary_school")를 모두 지정하면 응답에 "school"으로 분류되지만 "primary_school"로는 분류되지 않는 장소가 포함됩니다. 응답에는 includedTypes 중 하나 이상과 일치하고 excludedTypes와 일치하지 않는 장소가 포함됩니다.

    includedTypes과 excludedTypes에 모두 표시되는 유형과 같이 충돌하는 유형이 있으면 INVALID_REQUEST 오류가 반환됩니다.

    includedPrimaryTypes

    검색에 포함할 표 A의 기본 장소 유형 목록입니다.

    excludedPrimaryTypes

    검색에서 제외할 표 A의 기본 장소 유형 목록입니다.

    includedPrimaryTypes과 excludedPrimaryTypes에 모두 표시되는 유형과 같이 충돌하는 기본 유형이 있으면 INVALID_ARGUMENT 오류가 반환됩니다.

  • maxResultCount

    반환할 장소 결과의 최대 수를 지정합니다. 1~20 (기본값) 사이여야 합니다.

  • rankPreference

    사용할 순위 유형입니다. 이 매개변수를 생략하면 결과가 인기도에 따라 순위가 지정됩니다. 다음 중 하나일 수 있습니다.

    • .popularity (기본값) 인기도를 기준으로 결과를 정렬합니다.
    • .distance 지정된 위치로부터의 거리의 오름차순으로 결과를 정렬합니다.

  • regionCode

    대답의 형식을 지정하는 데 사용되는 지역 코드입니다. 2자리 CLDR 코드 값으로 지정됩니다. 기본값은 없습니다.

    응답의 formattedAddress 필드의 국가 이름이 regionCode와 일치하면 국가 코드가 formattedAddress에서 생략됩니다. 이 매개변수는 항상 국가 이름을 포함하는 adrFormatAddress 또는 국가 이름을 포함하지 않는 shortFormattedAddress에는 영향을 미치지 않습니다.

    대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)이지만 ISO 3166-1 코드는 'gb' (기술적으로 '영국' 법인의 경우)입니다. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.

앱에 특성 표시

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

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

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