장소 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입니다.

Places API(신규)

Places API를 사용하면 텍스트 검색 (신규) 합니다.

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"
      }
    },
  ...
}

이제 이미지, 이미지 및 오디오와 같은 Place Details (신규) 다음과 같이 요청 URL에 장소 ID를 포함하여 요청을 처리합니다.

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

Places API

Places API를 사용하면 장소 검색 요청

다음 예는 '음식점' 유형의 장소에 대한 검색 요청입니다. 호주 시드니의 한 지점에서 반경 1,500미터 이내에 있는 'cruise':

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"
}

이제 장소 세부정보 요청, place_id 매개변수에 장소 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를 새로고침할 수 있습니다. Place Details 요청, 장소 ID만 지정 이 필드가 fields 매개변수에 포함됩니다.

Places API(신규)

예를 들어 장소 세부정보 (신규)를 사용하는 경우는 다음과 같습니다.

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

Places API

기존 Place Details 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) 또는 Place 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