장소 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 저장에 관해 알아보세요.

다음 예는 Places API (신규) 및 Places API의 아이콘 URL을 요청하는 방법을 보여줍니다.

Places API(신규)

Places API를 사용하여 텍스트 검색 (신규) 요청을 실행하면 장소 ID를 찾을 수 있습니다.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

응답에는 아래와 같이 id 필드에 장소 ID가 포함됩니다.

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

이제 요청 URL에 장소 ID를 포함하여 장소 세부정보 (신규) 요청을 할 수 있습니다.

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

Places API

Places API를 사용하여 장소 검색 요청을 실행하여 장소 ID를 찾을 수 있습니다.

다음 예는 오스트레일리아 시드니의 지점에서 반경 1,500m 이내에 있으며 '크루즈'라는 단어가 포함된 '식당' 유형의 장소에 대한 검색 요청입니다.

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

응답에는 다음 스니펫과 같이 place_id 필드에 장소 ID가 포함됩니다.

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

이제 장소 ID를 place_id 매개변수에 넣고 장소 세부정보 요청을 보낼 수 있습니다.

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

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

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

저장된 장소 ID 갱신

12개월 이상 지난 장소 ID는 갱신하는 것이 좋습니다. 장소 ID는 fields 매개변수의 장소 ID 필드만 지정하고 Place Details 요청을 실행하여 무료로 갱신할 수 있습니다.

Places API(신규)

예를 들어 장소 세부정보 (신규)를 사용합니다.

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

Places API

예를 들어 기존 장소 세부정보 API를 사용합니다. 

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

그러면 Place Detail New (IDs Only) 또는 Places Details - ID Refresh SKU가 실행됩니다.

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

장소 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