장소 세부정보 (신규)

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

이 기능을 사용하려면 차세대 Places API인 Places API (신규)를 사용 설정해야 합니다. 자세한 내용은 API 사용 설정을 참조하세요.

iOS용 Places SDK (신규)는 장소의 이름 및 주소, 위도/경도 좌표로 지정된 지리적 위치, 장소 유형 (나이트클럽, 애완동물 전문점, 박물관 등) 등 장소에 대한 풍부한 정보를 앱에 제공합니다. 특정 장소의 이 정보에 액세스하려면 장소를 고유하게 식별하는 안정적인 식별자인 장소 ID를 사용하면 됩니다.

장소 세부정보 가져오기

GMSPlace 클래스에는 장소 데이터 필드 (신규)에 표시된 모든 데이터 필드를 비롯하여 특정 장소에 대한 정보가 포함됩니다. GMSPlacesClient fetchPlaceWithRequest:를 호출하고 GMSFetchPlaceRequest 객체와 GMSPlaceResultCallback 유형의 콜백 메서드를 전달하여 GMSPlace 객체를 가져옵니다.

GMSFetchPlaceRequest 객체는 다음을 지정합니다.

• (필수) Google 지역 정보 데이터베이스 및 Google 지도에 있는 장소의 고유 식별자인 장소 ID입니다.
• (필수) GMSPlace 객체에서 반환할 필드 목록으로, GMSPlaceProperty에 의해 정의된 대로 필드 마스크라고도 합니다. 필드 목록에 필드를 1개 이상 지정하지 않거나 필드 목록을 생략하면 호출이 오류가 반환됩니다.
• (선택사항) 응답 형식을 지정하는 데 사용되는 지역 코드입니다.
• (선택사항) 자동 완성 (신규) 세션을 종료하는 데 사용되는 세션 토큰입니다.

Place Details 요청하기

이 예에서는 ID로 장소를 가져오고 다음 매개변수를 전달합니다.

• ChIJV4k8_9UodTERU5KXbkYpSYs의 장소 ID입니다.
• 장소 이름과 웹사이트 URL을 반환하도록 지정하는 필드 목록입니다.
• 결과를 처리할 GMSPlaceResultCallback.

API가 지정된 콜백 메서드를 호출하여 GMSPlace 객체를 전달합니다. 장소를 찾을 수 없는 경우 장소 객체는 nil입니다.

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

GooglePlacesSwift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

장소 세부정보 응답

장소 세부정보는 장소에 대한 세부정보가 포함된 GMSPlace 객체를 반환합니다. 필드 목록에 지정된 필드만 GMSPlace 객체에 채워집니다.

참고: 응답 GMSPlace 객체의 필드는 비워둘 수 없습니다. 예를 들어 필드 목록에 응답으로 photos 필드를 요청하는 GMSPlacePropertyPhotos가 포함되어 있고 응답의 photos 필드가 비어 있으면 응답 GMSPlace 객체에서 생략됩니다.

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

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

참고: 이 기능은 iOS용 Places SDK를 사용 설정한 경우에만 사용할 수 있습니다. iOS용 Places SDK (신규)를 사용 설정한 경우에는 사용할 수 없습니다. 자세한 내용은 SDK 버전 선택을 참고하세요.

필수 매개변수

GMSFetchPlaceRequest 객체를 사용하여 필수 매개변수를 지정합니다.

장소 ID

iOS용 Places SDK에서 사용되는 장소 ID는 Places API, Android용 Places SDK, 기타 Google API에서 사용되는 것과 동일합니다. 각 장소 ID는 한 장소만 참조할 수 있지만, 단일 장소가 2개 이상의 장소 ID를 가질 수 있습니다.

장소가 새 장소 ID를 얻을 수 있는 상황이 있습니다. 예를 들어, 사업체를 새 위치로 이전하는 경우에 이러한 상황이 발생할 수 있습니다.

장소 ID를 지정하여 장소를 요청하면 응답에서 항상 동일한 장소를 수신하게 됩니다 (장소가 여전히 존재하는 경우). 그러나 응답에 요청에 있는 것과 다른 장소 ID가 포함될 수도 있습니다.

필드 목록

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

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

• 다음 필드는 Place Details (ID Only) SKU를 트리거합니다.

  GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

• 다음 필드는 Place Details (Location Only) SKU를 트리거합니다.

  GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

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

  GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyWheelchairAccessibleEntrance

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

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

• 다음 필드는 Place Details (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]
    

선택적 매개변수

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

regionCode

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

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

대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 특별한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)인 반면 ISO 3166-1 코드는 'gb' (기술적으로 '영국 및 북아일랜드'의 항목)입니다. 매개변수는 관련 법률에 따라 결과에 영향을 줄 수 있습니다.

sessionToken

세션 토큰은 자동 완성(신규) 호출을 '세션'으로 추적하는 사용자 생성 문자열입니다. Autocomplete (New)는 세션 토큰을 사용하여 사용자 자동 완성 검색의 쿼리 및 장소 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 세션 토큰은 자동 완성 (New) 호출 다음에 오는 Place Details (New) 호출에 전달됩니다. 자세한 내용은 세션 토큰을 참조하세요.

앱에 특성 표시

앱이 GMSPlacesClient에서 획득한 정보(예: 사진 및 리뷰)를 표시할 때 필수 저작자 표시도 표시해야 합니다.

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

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