이 페이지는 Cloud Translation API를 통해 번역되었습니다.

장소 ID

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

장소 ID는 Google 지역 정보 데이터베이스 및 Google 지도에 있는 장소를 고유하게 나타냅니다. 장소 ID는 다음과 같은 지도 API 요청에서 허용됩니다.

Geocoding API 웹 서비스와 Maps JavaScript API의 지오코딩 서비스에서 장소 ID의 주소 가져오기
Routes API, Directions API 웹 서비스와 Maps JavaScript API의 경로 서비스에서 출발지, 목적지, 중간 경유지 지정
Routes API, Distance Matrix API 웹 서비스와 Maps JavaScript API의 거리 행렬 서비스에서 출발지 및 목적지 지정
Places API 웹 서비스, Android용 Places SDK, iOS용 Places SDK, 장소 라이브러리에서 장소 세부정보 가져오기
Maps Embed API에서 장소 ID 매개변수 사용
지도 URL의 검색어 가져오기
Roads API에서 속도 제한 표시
경계를 위한 데이터 기반 스타일 지정에서 경계 다각형 찾기 및 스타일 지정

특정 장소의 ID 찾기

특정 장소의 장소 ID를 찾으시나요? 아래의 장소 ID 찾기를 사용하여 장소를 검색하고 ID를 가져오세요.

또는 Maps JavaScript API 문서의 장소 ID 찾기와 코드를 참고하세요.

개요

장소 ID는 장소를 고유하게 나타내는 텍스트 식별자입니다. 식별자의 길이는 서로 다를 수 있습니다(장소 ID에는 길이 제한이 없음). 예를 들면 다음과 같습니다.

ChIJgUbEo8cfqokR5lP9_Wh_DaM
GhIJQWDl0CIeQUARxks3icF8U8A
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

장소 ID는 비즈니스, 명소, 공원, 교차로 등 대부분의 위치에 사용할 수 있으며 동일한 장소 또는 위치에 서로 다른 여러 장소 ID가 있을 수 있습니다. 장소 ID는 시간이 지남에 따라 변경될 수 있습니다.

Places API와 여러 Google Maps Platform API에서 동일한 장소 ID를 사용할 수 있습니다. 예를 들어 동일한 장소 ID를 사용하여 Places API, Maps JavaScript API, Geocoding API, Maps Embed API, Roads API에서 장소를 참조할 수 있습니다.

장소 ID를 사용하여 장소 세부정보 가져오기

장소 ID를 사용하는 일반적인 방법은 (예를 들어 Maps JavaScript API의 Places API 또는 장소 라이브러리를 사용하여) 장소를 검색한 다음 반환된 장소 ID를 사용하여 장소 세부정보를 가져오는 것입니다. 장소 ID를 저장했다가 나중에 이를 사용하여 동일한 장소 세부정보를 가져올 수도 있습니다. 아래에서 장소 ID 저장에 관해 알아보세요.

Android용 Places SDK를 사용하는 예

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.
    }
});

나중에 사용하기 위해 장소 ID 저장

장소 ID에는 Google Maps Platform 서비스 약관의 3.2.3(b)항에 명시된 캐싱 제한사항이 적용되지 않습니다. 따라서 나중에 사용하기 위해 장소 ID 값을 저장할 수 있습니다.

저장된 장소 ID 갱신

12개월 이상 지난 장소 ID는 갱신하는 것이 좋습니다. 장소 ID는 fields 매개변수의 Place.Field.ID 필드만 지정하고 장소 세부정보를 요청하여 무료로 갱신할 수 있습니다. 그러면 Places Details - ID Refresh SKU가 실행됩니다.

이 요청에서 NOT_FOUND 상태 코드를 반환할 수도 있습니다. 한 가지 방법은 각 장소 ID를 반환한 원래 요청을 저장하는 것입니다. 장소 ID가 무효화되면 이 요청을 다시 실행하여 최신 결과를 얻을 수 있습니다. 이 결과에는 원래 장소가 포함될 수도 있고 포함되지 않을 수도 있습니다. 하지만 이 요청에는 요금이 청구됩니다.

참고: 장소 ID가 무효가 된 후 처음 며칠 동안은 사용된 원래 요청이 장소 또는 쿼리 자동 완성인 경우 이 전략에서 NOT_FOUND가 계속해서 발생할 수 있습니다.

장소 ID 사용 시 오류 코드

INVALID_REQUEST 상태 코드는 지정된 장소 ID가 유효하지 않음을 나타냅니다. 장소 ID가 잘렸거나 다른 방식으로 수정되어 더 이상 올바르지 않은 경우 INVALID_REQUEST가 반환될 수도 있습니다.

NOT_FOUND 상태 코드는 지정된 장소 ID가 더 이상 사용되지 않음을 나타냅니다. 비즈니스가 폐업하거나 새로운 위치로 이전하면 장소 ID가 더 이상 사용되지 않을 수도 있습니다. Google 지도 데이터베이스의 업데이트로 인해 장소 ID가 변경될 수도 있습니다. 이 경우 장소에 새 장소 ID가 부여될 수도 있으며 이전 ID는 NOT_FOUND 응답을 반환합니다.

특히 일부 유형의 장소 ID는 경우에 따라 NOT_FOUND 응답을 유발하거나 API가 응답에 다른 장소 ID를 반환할 수도 있습니다. 여기에는 다음과 같은 장소 ID 유형이 포함됩니다.

Google 지도에 정확한 주소로 존재하지 않지만 주소 범위에서 추론되는 상세 주소
요청에서 도시 또는 지역을 지정하는 긴 경로의 구간
교차로
subpremise 유형의 주소 구성요소가 포함된 장소

이러한 ID는 주로 긴 문자열의 형태를 취합니다(장소 ID에는 길이 제한이 없음). 예를 들면 다음과 같습니다.

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4