Android용 Places SDK는 장소 이름 및 주소, 위도/경도 좌표로 지정된 지리적 위치, 장소의 유형 (나이트클럽, 애완동물 가게, 박물관 등)을 포함한 장소에 대한 풍부한 정보를 앱에 제공합니다. 특정 장소의 이 정보에 액세스하려면 장소를 고유하게 식별하는 안정적인 식별자인 장소 ID를 사용하면 됩니다.
장소 세부정보
Place
객체는 특정 장소에 관한 정보를 제공합니다. 다음과 같은 방법으로 Place
객체를 가져올 수 있습니다.
PlacesClient.findCurrentPlace()
호출 – 현재 장소 가져오기 가이드를 참고하세요.PlacesClient.fetchPlace()
호출 – ID로 장소 가져오기 가이드를 참고하세요.
장소를 요청할 때 반환할 장소 데이터를 지정해야 합니다. 이렇게 하려면 반환할 데이터를 지정하는 Place.Field 값 목록을 전달합니다. 이 목록은 각 요청의 비용에 영향을 미치므로 중요한 고려사항입니다.
장소 데이터 결과는 비워둘 수 없으므로 데이터가 있는 장소 결과만 반환됩니다. 예를 들어 요청된 장소에 사진이 없으면 결과에 photos
필드가 표시되지 않습니다.
다음 예에서는 세 개의 Place.Field 값 목록을 전달하여 요청에서 반환된 데이터를 지정합니다.
자바
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Place
객체를 가져온 후 객체의 메서드를 사용하여 요청에 지정된 데이터 필드에 액세스합니다. Place
객체에서 필드가 누락된 경우 관련 메서드는 null을 반환합니다. 다음은 사용 가능한 메서드의 몇 가지 예입니다.
모든 메서드의 전체 목록은 Place
API 참조를 확인하세요.
getAddress()
– 사람이 읽을 수 있는 형식의 장소 주소입니다.getAddressComponents()
– 이 장소에 대한 주소 구성요소의List
입니다. 이러한 구성요소는 장소의 주소에 대한 구조화된 정보를 추출하기 위한 목적(예: 장소가 위치한 도시 찾기)으로 제공됩니다. 주소 형식 지정에 이러한 구성요소를 사용하지 마세요. 대신 현지화된 형식의 주소를 제공하는getAddress()
를 호출하세요.getId()
- 장소의 텍스트 식별자입니다. 이 페이지의 나머지 부분에서 장소 ID에 관해 자세히 알아보세요.getLatLng()
– 장소의 지리적 위치로 위도와 경도 좌표로 지정됩니다.getName()
– 장소의 이름입니다.getOpeningHours()
– 장소의OpeningHours
.OpeningHours.getWeekdayText()
를 호출하여 각 요일의 개점 시간과 폐점 시간을 나타내는 문자열 목록을 반환합니다.OpeningHours.getPeriods()
를 호출하여getWeekdayText()
에서 제공하는 데이터와 동일한 정보가 포함된period
객체 목록을 반환합니다.Place
객체에는 다음 7일 동안 장소의 영업시간을 반환하는getCurrentOpeningHours()
메서드와 향후 7일 동안 장소의 보조 영업시간을 반환하는getSecondaryOpeningHours()
메서드가 포함되어 있습니다.isOpen()
– 장소가 현재 영업 중인지 여부를 나타내는 불리언입니다. 시간을 지정하지 않으면 기본값은 현재입니다.isOpen
는Place.Field.UTC_OFFSET
와Place.Field.OPENING_HOURS
를 모두 사용할 수 있는 경우에만 반환됩니다. 정확한 결과를 얻으려면 원래 장소 요청에서Place.Field.BUSINESS_STATUS
및Place.Field.UTC_OFFSET
필드를 요청하세요. 요청하지 않으면 비즈니스가 영업 중인 것으로 간주됩니다.isOpen
를 장소 세부정보와 함께 사용하는 방법은 이 동영상을 참고하세요.
몇 가지 간단한 예시:
자바
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
Kotlin
val name = place.name val address = place.address val location = place.latLng
ID로 장소 가져오기
장소 ID는 장소를 고유하게 나타내는 텍스트 식별자입니다. Android용 Places SDK에서 Place.getId()
를 호출하여 장소의 ID를 가져올 수 있습니다.
Place Autocomplete 서비스에서는 제공된 쿼리 및 필터와 일치하는 각 장소의 장소 ID도 반환합니다. 장소 ID를 저장하고 나중에 다시 Place
객체를 검색하는 데 사용할 수 있습니다.
ID로 장소를 가져오려면 PlacesClient.fetchPlace()
를 호출하고 FetchPlaceRequest
을 전달합니다.
API는 Task
에 FetchPlaceResponse
를 반환합니다.
FetchPlaceResponse
에는 제공된 장소 ID와 일치하는 Place
객체가 포함되어 있습니다.
다음 코드 예는 fetchPlace()
를 호출하여 지정된 장소의 세부정보를 가져오는 방법을 보여줍니다.
자바
// 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. } });
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") } }
공개 상태 가져오기
PlacesClient.isOpen(IsOpenRequest request)
메서드는 호출에 지정된 시간을 기준으로 장소가 현재 영업 중인지 여부를 나타내는 IsOpenResponse
객체를 반환합니다.
이 메서드는 다음 유형이 포함된 IsOpenRequest
유형의 단일 인수를 사용합니다.
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 객체를 만드는 방법에 대한 자세한 내용은 장소 세부정보를 참고하세요.
다음 예는 장소가 현재 영업 중인지 여부를 확인합니다. 이 예에서는 장소 ID를 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()); // ...
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 } // ...
다음 예는 isOpen()
를 호출하여 Place
객체를 전달하는 방법을 보여줍니다.
Place
객체는 유효한 장소 ID를 포함해야 합니다.
자바
@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()); // ... }); // ...
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 } // ... } // ...
앱에 특성 표시
앱에 장소 정보가 표시되면 저작자 표시도 표시해야 합니다. 기여 분석 문서를 참고하세요.
장소 ID에 대한 추가 정보
Android용 Places SDK에서 사용되는 장소 ID는 Places API에서 사용되는 것과 동일한 식별자입니다. 각 장소 ID는 한 장소만 참조할 수 있지만, 단일 장소에는 2개 이상의 장소 ID가 있을 수 있습니다. 장소가 새 장소 ID를 얻게 하는 다른 상황이 있습니다. 예를 들어 비즈니스가 새 위치로 이전한 경우 이 상황이 발생할 수 있습니다.
장소 ID를 지정하여 장소를 요청하는 경우 응답에서 항상 동일한 장소를 수신하게 됩니다 (장소가 아직 존재하는 경우). 그러나 응답에 요청의 장소 ID와 다른 장소 ID가 포함될 수 있습니다.
자세한 내용은 장소 ID 개요를 참고하세요.