장소 세부정보

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

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

장소 세부정보

Place 객체는 특정 장소에 대한 정보를 제공합니다. 다음과 같은 방법으로 Place 객체를 보유할 수 있습니다.

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

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

다음 예에서는 3개의 Place.Field 값 목록을 전달하여 요청에서 반환된 데이터를 지정합니다.

Kotlin

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

Java

// Specify the fields to return.
final List placeFields = Arrays.asList(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() - 장소가 현재 영업 중인지 여부를 나타내는 불리언. 시간을 지정하지 않으면 기본값은 현재입니다. isOpenPlace.Field.UTC_OFFSETPlace.Field.OPENING_HOURS를 모두 사용할 수 있는 경우에만 반환됩니다. 정확한 결과를 얻으려면 원래 장소 요청에서 Place.Field.BUSINESS_STATUSPlace.Field.UTC_OFFSET 필드를 요청하세요. 요청하지 않으면 비즈니스가 운영 중인 것으로 가정합니다. isOpen를 장소 세부정보와 함께 사용하는 방법은 이 동영상을 참고하세요.

몇 가지 간단한 예시:

Kotlin



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

      

Java


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

      

버전 3.3.0에 추가된 장소 데이터에 액세스

Android용 Places SDK 버전 3.3.0에서는 Place에 새 데이터가 추가됩니다.

  • 장소 유형: 장소와 연결된 새로운 유형 값입니다.
  • 리뷰: 한 장소에 대한 리뷰 최대 5개
  • 이름 언어 코드: 장소 이름의 언어 코드입니다.

이 데이터에 액세스하려면 Android용 Places SDK (신규)를 사용 설정해야 합니다. 두 SDK 버전의 주요 차이점을 알아보려면 SDK 버전 선택을 참고하세요.

다음 섹션에서는 이 새로운 데이터에 액세스하는 방법을 설명합니다.

새로운 장소 유형에 액세스

각 장소는 하나 이상의 type 값을 연결할 수 있습니다. Android용 Places SDK 버전 3.3.0에는 많은 새로운 유형 값이 추가됩니다. 전체 목록은 확장된 장소 유형을 참고하세요.

Android용 Places SDK 버전 3.2.0 이하에서는 Place.getTypes() 메서드를 사용하여 장소와 연결된 유형 값에 액세스했습니다. Place.getTypes()Place.Types에 의해 정의된 enum 값으로 유형 목록을 반환합니다.

Place.getPlaceTypes() 메서드는 유형 값을 문자열 값 목록으로 반환합니다. 반환되는 값은 Android용 Places SDK의 버전에 따라 다릅니다.

  • Android용 Places SDK (신규): 장소 유형 (신규)에 표시된 표 A와 표 B로 정의된 문자열을 반환합니다. 여기에는 버전 3.3.0에 추가된 모든 장소 유형이 포함됩니다.
  • Android용 Places SDK: Place.Types에 의해 정의된 enum을 반환합니다. 여기에는 버전 3.3.0에 추가된 새 유형이 포함되지 않습니다.

두 SDK 버전의 주요 차이점을 알아보려면 SDK 버전 선택을 참고하세요.

장소 리뷰에 액세스

Android용 Places SDK (신규)에서는 장소에 대한 리뷰가 포함된 Review 클래스를 추가합니다. Place 객체에는 최대 5개의 리뷰가 포함될 수 있습니다.

Review 클래스에는 저작자 표시와 작성자 저작자 표시가 포함될 수도 있습니다. 앱에 리뷰를 표시하는 경우 저작자 표시 또는 작성자 저작자 표시도 표시해야 합니다. 자세한 내용은 리뷰 표시를 참고하세요.

리뷰로 Place 객체를 채우려면 다음을 실행해야 합니다.

  1. Google Cloud 프로젝트를 설정할 때 새 SDK를 사용 설정합니다.
  2. 활동 또는 프래그먼트 내에서 새 SDK를 초기화합니다.
  3. 장소 세부정보 요청의 필드 목록에 Place.Field.REVIEWS를 포함합니다.
  4. PlacesClient.fetchPlace()을 호출합니다. PlacesClient.findCurrentPlace()에서는 리뷰 입력란을 지원하지 않습니다.
  5. Place.getReviews() 메서드를 사용하여 Place 객체의 리뷰 데이터 필드에 액세스합니다.

장소 이름 언어 코드 액세스

기존 Place.getName() 메서드는 장소의 이름이 포함된 텍스트 문자열을 반환합니다. Place 객체를 장소 이름으로 채우려면 장소 세부정보 요청의 필드 목록에 Place.Field.NAME를 포함해야 합니다.

이제 Place 객체에 이름 문자열의 언어 코드가 포함됩니다. Place 객체를 언어 코드로 채우려면 다음을 수행해야 합니다.

  1. Google Cloud 프로젝트를 설정할 때 새 SDK를 사용 설정합니다.
  2. 활동 또는 프래그먼트 내에서 새 SDK를 초기화합니다.
  3. 요청의 필드 목록에 Place.Field.NAME를 포함합니다. 이 값은 장소 이름과 언어 코드를 모두 Place 객체에 포함하도록 응답을 구성합니다.
  4. PlacesClient.fetchPlace()을 호출합니다. PlacesClient.findCurrentPlace()는 언어 코드 필드를 지원하지 않습니다.
  5. Place.getNameLanguageCode() 메서드를 사용하여 Place 객체의 언어 코드 필드에 액세스합니다.

버전 3.3.0에서 리전 코드 설정

Android용 Places SDK (신규)는 장소 세부정보에 지역 코드 요청 매개변수를 추가합니다. 리전 코드는 응답의 형식을 지정하는 데 사용되며 2자리 CLDR 코드 값으로 지정됩니다. 이 매개변수는 검색결과에 편향적인 영향을 줄 수도 있습니다. 기본값은 없습니다. 지역 코드를 설정하려면 새 SDK를 사용 설정해야 합니다.

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

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

ID로 장소 가져오기

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

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

API는 TaskFetchPlaceResponse를 반환합니다. 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")
        }
    }

      

Java


// 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.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()를 사용하여 가져옵니다. 필수 필드로 장소 객체를 만드는 방법에 대한 자세한 내용은 장소 세부정보를 참고하세요.

다음 예는 장소가 현재 영업 중인지 여부를 결정합니다. 이 예에서는 장소 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
}
// ...

      

Java


@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
    }
    // ...
}
// ...

      

Java


@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는 한 장소만 참조할 수 있지만, 단일 장소가 2개 이상의 장소 ID를 가질 수 있습니다. 장소가 새 장소 ID를 얻을 수 있는 다른 상황도 있습니다. 예를 들어 비즈니스가 새 위치로 이전한 경우 이러한 상황이 발생할 수 있습니다.

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

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