주변 검색 (신규)

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

Nearby Search (New) 요청은 원으로 지정된 검색할 영역을 입력으로 받습니다. 이 영역은 원의 중심점의 위도 및 경도 좌표와 미터 단위의 반경으로 정의됩니다. 이 요청은 지정된 검색 영역 내에서 각각 GMSPlace 객체로 표현되는 일치하는 장소의 목록을 반환합니다.

기본적으로 응답에는 검색 영역 내의 모든 유형의 장소가 포함됩니다. 선택적으로 응답에 명시적으로 포함하거나 응답에 제외할 장소 유형 목록을 지정하여 응답을 필터링할 수 있습니다. 예를 들어 응답에 '레스토랑', '제과점', '카페' 유형의 장소만 포함하거나 '학교' 유형의 모든 장소를 제외하도록 지정할 수 있습니다.

주변 검색 (신규) 요청

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

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

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

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

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

GooglePlacesSwift

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
}

주변 검색 응답

Nearby Search API는 일치하는 장소당 하나의 GMSPlace 객체를 사용하여 GMSPlace 객체의 형태로 일치 항목의 배열을 반환합니다.

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

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

필수 매개변수

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

  • 필드 목록

    장소 세부정보를 요청할 때는 장소의 GMSPlace 객체에 필드 마스크로 반환할 데이터를 지정해야 합니다. 필드 마스크를 정의하려면 GMSPlaceProperty의 값 배열을 GMSPlaceSearchNearbyRequest 객체로 전달합니다. 필드 마스킹은 불필요한 데이터를 요청하지 않도록 하는 좋은 설계 방법이며, 이렇게 하면 불필요한 처리에 드는 시간과 요금을 막을 수 있습니다.

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

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

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

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

      GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

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

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

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

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

    GooglePlacesSwift

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

  • locationRestriction

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

선택적 매개변수

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

  • includeTypes/excludedTypes, IncludePrimaryTypes/excludedPrimaryTypes

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

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

    장소는 연결된 표 A 유형의 여러 유형 값도 가질 수 있습니다. 예를 들어 음식점의 유형은 "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment"일 수 있습니다. includedTypes 및 excludedTypes를 사용하여 장소와 연결된 유형 목록의 결과를 필터링합니다.

    검색에 여러 유형의 제한사항을 지정하면 모든 제한사항을 충족하는 장소만 반환됩니다. 예를 들어 {"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 객체에는 저작자 표시와 작성자 저작자 표시가 포함될 수 있습니다. 앱에 리뷰를 표시하는 경우 저작자 표시 또는 작성자 저작자 표시도 표시해야 합니다.

자세한 내용은 기여 분석 문서를 참고하세요.