장소 세부정보

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

청구서 수신 주소가 유럽 경제 지역에 있는 경우 2025년 7월 8일부터 Google Maps Platform EEA 서비스 약관 이 서비스 이용에 적용됩니다. 기능은 리전에 따라 다릅니다. 자세히 알아보기

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

장소 세부정보

Place 객체는 특정 장소에 관한 정보를 제공합니다. PlacesClient.fetchPlace()를 호출하여 Place 객체를 가져올 수 있습니다. ID로 장소 가져오기 가이드를 참고하세요.

장소를 요청할 때 반환할 장소 데이터를 지정해야 합니다. 이렇게 하려면 반환할 데이터를 지정하는 Place.Field 값의 목록을 전달하세요. 이 목록은 각 요청의 비용에 영향을 미치므로 중요한 고려사항입니다.

장소 데이터 결과는 비워둘 수 없으므로 데이터가 있는 장소 결과만 반환됩니다. 예를 들어 요청된 장소에 사진이 없으면 결과에 photos 필드가 표시되지 않습니다.

다음 예에서는 요청에서 반환되는 데이터를 지정하기 위해 세 개의 Place.Field 값 목록을 전달합니다.

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.RATING)

자바

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);
  

장소 객체 데이터 필드에 액세스

Place 객체를 가져온 후 객체의 메서드를 사용하여 요청에 지정된 데이터 필드에 액세스합니다. Place 객체에 필드가 누락된 경우 관련 메서드는 null을 반환합니다. 아래는 사용 가능한 메서드의 몇 가지 예입니다.

모든 메서드의 전체 목록은 Place API 참조를 확인하세요.

• getAddress() - 사람이 읽을 수 있는 형식의 장소 주소입니다.
• getAddressComponents() - 이 장소의 주소 구성요소 List입니다. 이러한 구성요소는 장소의 주소에 관한 구조화된 정보를 추출하기 위해 제공됩니다(예: 장소가 위치한 도시 찾기). 주소 형식 지정에는 이러한 구성요소를 사용하지 마세요. 대신 현지화된 형식이 지정된 주소를 제공하는 getAddress()를 호출하세요.
• getId() - 장소의 텍스트 식별자입니다. 이 페이지의 나머지 부분에서 장소 ID에 대해 자세히 알아보세요.
• getLatLng() - 장소의 지리적 위치로, 위도 및 경도 좌표로 지정됩니다.
• getName() - 장소의 이름입니다.

• getOpeningHours() - 장소의 OpeningHours입니다. OpeningHours.getWeekdayText()를 호출하여 각 요일의 영업시간을 나타내는 문자열 목록을 반환합니다. OpeningHours.getPeriods()를 호출하여 getWeekdayText()에서 제공하는 데이터와 동일한 자세한 정보가 포함된 period 객체 목록을 반환합니다.

  참고: 장소가 항상 열려 있는 경우 시간대는 일요일 자정으로 표시되고 closeEvent은 null입니다.

  Place 객체에는 다음 7일 동안의 장소 영업시간을 반환하는 getCurrentOpeningHours() 메서드와 다음 7일 동안의 장소 보조 영업시간을 반환하는 getSecondaryOpeningHours()도 포함되어 있습니다.

• isOpen() - 장소가 현재 영업 중인지 여부를 나타내는 불리언입니다. 시간을 지정하지 않으면 기본값은 현재 시간입니다. isOpen는 Place.Field.UTC_OFFSET과 Place.Field.OPENING_HOURS가 모두 사용 가능한 경우에만 반환됩니다. 정확한 결과를 얻으려면 원래 장소 요청에서 Place.Field.BUSINESS_STATUS 및 Place.Field.UTC_OFFSET 필드를 요청하세요. 요청되지 않은 경우 비즈니스가 운영 중인 것으로 간주됩니다. isOpen을 장소 세부정보와 함께 사용하는 방법은 이 동영상을 참고하세요.

  참고: 이 메서드는 지원 중단되었습니다. 대신 PlacesClient.isOpen(IsOpenRequest request)를 사용하세요. 자세한 내용은 열기 상태 가져오기를 참고하세요.

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

Kotlin

val name = place.name
val address = place.address
val location = place.latLng

      

자바

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

ID로 장소 가져오기

장소 ID는 장소를 고유하게 나타내는 텍스트 식별자입니다. Android용 Places SDK에서는 Place.getId()를 호출하여 장소의 ID를 검색할 수 있습니다. Place Autocomplete 서비스는 제공된 검색어 및 필터와 일치하는 각 장소의 장소 ID도 반환합니다. 장소 ID를 저장했다가 나중에 이를 사용하여 Place 객체를 다시 가져올 수도 있습니다.

ID로 장소를 가져오려면 PlacesClient.fetchPlace()를 호출하여 FetchPlaceRequest를 전달합니다.

API는 Task에서 FetchPlaceResponse를 반환합니다. FetchPlaceResponse에는 제공된 장소 ID와 일치하는 Place 객체가 포함됩니다.

다음 코드 예는 fetchPlace()를 호출하여 지정된 장소의 세부정보를 가져오는 방법을 보여줍니다.

Kotlin

// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

자바

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

참고: PlacesClient 초기화에 관한 자세한 내용은 Places API 클라이언트 초기화를 참고하세요.

CancellationToken을 사용하여 요청 클래스 (예: FetchPlaceRequest)에 대한 요청을 취소할 수 있습니다. 취소는 최선의 방식으로 실행됩니다. 취소 요청이 발행되면 응답이 반환되지 않습니다. 취소 토큰을 발급해도 특정 요청이 취소된다고 보장할 수 없으며, 응답이 반환되지 않더라도 요청에 대한 요금이 청구될 수 있습니다.

열람 상태 가져오기

PlacesClient.isOpen(IsOpenRequest request) 메서드는 호출에 지정된 시간을 기준으로 장소가 현재 영업 중인지 여부를 나타내는 IsOpenResponse 객체를 반환합니다.

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

• Place 객체 또는 장소 ID를 지정하는 문자열입니다.
  참고: Place 객체에는 유효한 장소 ID가 포함되어야 합니다.
• 1970-01-01T00:00:00Z부터의 시간을 밀리초 단위로 지정하는 선택적 시간 값입니다. 시간을 지정하지 않으면 기본값은 현재 시간입니다.

이 메서드를 사용하려면 Place 객체에 다음 필드가 있어야 합니다.

• Place.Field.BUSINESS_STATUS
• Place.Field.CURRENT_OPENING_HOURS
• Place.Field.OPENING_HOURS
• Place.Field.UTC_OFFSET

이러한 필드가 Place 객체에 제공되지 않거나 장소 ID를 전달하는 경우 메서드는 PlacesClient.fetchPlace()를 사용하여 필드를 가져옵니다. 필수 필드를 사용하여 장소 객체를 만드는 방법에 관한 자세한 내용은 장소 세부정보를 참고하세요.

참고: Place.Field.UTC_OFFSET 및 Place.Field.BUSINESS_STATUS에 대한 fetchPlace() 호출에는 Places Basic Data SKU가 청구됩니다. Place.Field.CURRENT_OPENING_HOURS 및 Place.Field.OPENING_HOURS에 대한 fetchPlace() 호출에는 Places Contact Data SKU가 청구됩니다.

다음 예에서는 장소가 현재 영업 중인지 확인합니다. 이 예에서는 장소 ID만 isOpen()에 전달합니다.

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

      

자바

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

      

다음 예에서는 Place 객체를 전달하는 isOpen() 호출을 보여줍니다. Place 객체에는 유효한 장소 ID가 포함되어야 합니다.

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.UTC_OFFSET
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

      

자바

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields = new ArrayList<>(Arrays.asList(
        Place.Field.BUSINESS_STATUS,
        Place.Field.CURRENT_OPENING_HOURS,
        Place.Field.ID,
        Place.Field.OPENING_HOURS,
        Place.Field.UTC_OFFSET
));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

      

앱에 특성 표시

앱에서 장소 리뷰를 비롯한 장소 정보를 표시하는 경우 저작자 표시도 함께 표시해야 합니다. 자세한 내용은 저작자 표시를 참고하세요.

장소 ID에 대한 추가 정보

Android용 Places SDK에서 사용되는 장소 ID는 Places API에서 사용되는 식별자와 동일합니다. 각 장소 ID는 하나의 장소만 나타낼 수 있지만 하나의 장소에 두 개 이상의 장소 ID가 있을 수 있습니다. 장소에 새 장소 ID가 부여되는 다른 상황도 있습니다. 예를 들어 비즈니스가 새 위치로 이전하는 경우에 이러한 문제가 발생할 수 있습니다.

장소 ID를 지정하여 장소를 요청하면 장소가 아직 존재하는 경우 항상 동일한 장소가 응답으로 반환됩니다. 하지만 응답에는 요청에 있는 장소 ID와 다른 장소 ID가 포함될 수 있습니다.

자세한 내용은 장소 ID 개요를 참고하세요.