지오코딩 서비스

개요

지오코딩은 주소(예: '1600 Amphitheatre Parkway, Mountain View, CA')를 마커나 지도를 배치하는 데 사용할 수 있는 지리 좌표(예: 위도 37.423021 및 경도 -122.083739)로 변환하는 과정입니다.

역 지오코딩은 지리 좌표를 인간이 읽을 수 있는 주소로 변환하는 과정입니다(역 지오코딩(주소 조회) 참고).

지오코더를 사용하여 지정된 장소 ID의 주소를 찾을 수도 있습니다.

Maps JavaScript API는 사용자 입력에서 동적으로 지오코딩 및 역 지오코딩하기 위한 지오코더 클래스를 제공합니다. 알려진 정적 주소를 지오코딩하려면 지오코딩 웹 서비스를 참고하세요.

시작하기

Maps JavaScript API에서 지오코딩 서비스를 사용하려면 먼저 Maps JavaScript API를 위해 설정한 것과 동일한 프로젝트의 Google Cloud 콘솔에서 Geocoding API를 사용 설정해야 합니다.

사용 설정된 API의 목록을 보려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔로 이동합니다.
  2. 프로젝트 선택 버튼을 클릭한 후 Maps JavaScript API를 위해 설정한 것과 동일한 프로젝트를 선택하고 열기를 클릭합니다.
  3. 대시보드의 API 목록에서 Geocoding API를 찾습니다.
  4. 목록에 API가 표시되면 완료된 것입니다. API가 표시되지 않으면 API를 사용 설정하세요.
    1. 페이지 상단에서 API 사용 설정을 선택하여 라이브러리 탭을 표시합니다. 또는 왼쪽 사이드 메뉴에서 라이브러리를 선택합니다.
    2. Geocoding API를 검색한 후 결과 목록에서 선택합니다.
    3. 사용 설정을 선택합니다. 과정이 완료되면 Geocoding API가 대시보드의 API 목록에 표시됩니다.

가격 정보 및 정책

가격 정보

2018년 7월 16일부터 지도, 경로, 장소에 사용한 만큼만 지불하는 새로운 요금제가 도입되었습니다. JavaScript 지오코딩 서비스 사용 시 적용되는 새로운 가격 및 사용량 한도에 대한 자세한 내용은 Geocoding API의 사용량 및 결제를 참고하세요.

정책

지오코딩 서비스는 Geocoding API에 설명된 정책에 따라 사용해야 합니다.

지오코딩 요청

Google 지도 API는 외부 서버를 호출해야 하므로 지오코딩 서비스 액세스는 비동기식입니다. 따라서 요청 완료 시 실행할 콜백 메서드를 전달해야 합니다. 이 콜백 메서드가 결과를 처리합니다. 지오코더에서 두 개 이상의 결과를 반환할 수도 있습니다.

google.maps.Geocoder 생성자 객체를 통해 코드 내에서 Google 지도 API 지오코딩 서비스에 액세스합니다. Geocoder.geocode() 메서드는 지오코딩 서비스 요청을 시작하고 입력 용어가 포함된 GeocoderRequest 객체 리터럴 및 응답 수신 시 실행할 콜백 메서드를 전달합니다.

GeocoderRequest 객체 리터럴에는 다음 필드가 포함됩니다.

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

필수 매개변수: 다음 필드 중 하나만 제공해야 합니다.

  • address - 지오코딩할 주소.
         또는
    location - 인간이 읽을 수 있는 가장 가까운 주소를 얻으려는 LatLng(또는 LatLngLiteral). 지오코더가 역 지오코딩을 실행합니다. 자세한 내용은 역 지오코딩을 참고하세요.
         또는
    placeId: 인간이 읽을 수 있는 가장 가까운 주소를 얻으려는 장소의 장소 ID. 장소 ID의 주소 가져오기에 대해 자세히 알아보세요.

매개변수 옵션:

  • bounds - 지오코딩 결과가 더 눈에 띄게 편향되는 LatLngBounds. bounds 매개변수는 지오코더의 결과에 영향을 줄 뿐이며 결과를 완전히 제한하지는 않습니다. 자세한 내용은 아래의 표시 영역 상세 검색을 참고하세요.
  • componentRestrictions - 결과를 특정 지역으로 제한하는 데 사용됩니다. 자세한 내용은 아래의 구성요소 필터링을 참고하세요.
  • region - 두 자리 유니코드 지역 하위 태그(숫자가 아님)로 지정되는 지역 코드. 대부분의 경우 이러한 태그는 익숙한 두 자리 ccTLD('최상위 도메인') 값에 직접 매핑됩니다. region 매개변수는 지오코더의 결과에 영향을 줄 뿐이며 결과를 완전히 제한하지는 않습니다. 자세한 내용은 아래의 지역 코드 상세 검색을 참고하세요.
  • extraComputations: 이 매개변수에 허용되는 유일한 값은 ADDRESS_DESCRIPTORS입니다. 자세한 내용은 주소 설명자를 참고하세요.
  • fulfillOnZeroResults: 응답에서 ZERO_RESULT 상태에 대한 약속을 처리합니다. 지오코딩 결과가 0개이더라도 응답 수준 필드가 추가로 반환될 수 있으므로 이 작업이 필요할 수 있습니다. 자세한 내용은 검색 결과 없음 시 처리를 참고하세요.

지오코딩 응답

지오코딩 서비스에는 지오코더의 결과를 가져올 때 실행할 콜백 메서드가 필요합니다. 이 콜백은 results 및 status 코드를 이 순서대로 보유할 두 매개변수를 전달해야 합니다.

지오코딩 결과

GeocoderResult 객체는 단일 지오코딩 결과를 나타냅니다. 지오코드 요청이 여러 결과 객체를 반환할 수도 있습니다.

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

이 필드는 아래에 설명되어 있습니다.

  • types[]는 반환된 결과의 주소 유형을 나타내는 배열입니다. 이 배열에는 결과에 반환되는 지형지물의 유형을 나타내는 0개 이상의 태그 집합이 포함됩니다. 예를 들어 '시카고'의 지오코드는 '시카고'가 도시임을 나타내는 'locality'를 반환하고 시카고가 정치적 독립체임을 나타내는 'political'도 반환합니다. 자세한 내용은 아래의 주소 유형 및 주소 구성요소 유형을 참고하세요.
  • formatted_address는 이 위치의 인간이 읽을 수 있는 주소가 포함된 문자열입니다.

    이 주소는 대개 우편 주소와 일치합니다. 참고: 영국과 같은 일부 국가에서는 라이선스 제한으로 인해 실제 우편 주소의 배포가 허용되지 않습니다.

    형식이 지정된 주소는 하나 이상의 주소 구성요소로 논리적으로 구성됩니다. 예를 들어 주소 '111 8th Avenue, New York, NY'는 '111'(번지), '8th Avenue'(경로), 'New York'(도시) 및 'NY'(미국의 주)로 구성됩니다.

    형식이 지정된 주소를 프로그래매틱 방식으로 파싱하지 마세요. 대신 API 응답에 형식이 지정된 주소 필드 외에 포함되는 개별 주소 구성요소를 사용해야 합니다.

  • address_components[]는 이 주소에 적용할 수 있는 별도의 구성요소가 포함된 배열입니다.

    각 주소 구성요소에는 일반적으로 다음과 같은 필드가 포함됩니다.

    • types[]는 주소 구성요소의 유형을 나타내는 배열입니다. 지원되는 유형의 목록을 참고하세요.
    • long_name은 지오코더에서 반환하는 주소 구성요소의 전체 텍스트 설명 또는 이름입니다.
    • short_name은 주소 구성요소의 축약된 텍스트 이름입니다(해당하는 경우). 예를 들어 알래스카 주의 주소 구성요소에는 long_name 'Alaska'와 두 자리 우편 약어를 사용하는 short_name 'AK'가 포함될 수 있습니다.

    address_components[] 배열에 대한 다음 사실을 참고하세요.

    • 주소 구성요소의 배열에 formatted_address보다 더 많은 구성요소가 포함될 수도 있습니다.
    • formatted_address에 포함된 것 외에 주소가 포함된 모든 정치적 독립체가 배열에 포함되는 것은 아닙니다. 특정 주소가 포함된 모든 정치적 독립체를 가져오려면 역 지오코딩을 사용하여 주소의 위도/경도를 매개변수로 요청에 전달해야 합니다.
    • 응답의 형식이 요청 간에 동일하게 유지되지 않을 수도 있습니다. 특히 address_components의 수는 요청된 주소에 따라 다르며 동일한 주소에 대해서도 시간이 지남에 따라 변경될 수 있습니다. 배열에서 구성요소의 위치가 변경될 수 있습니다. 구성요소의 유형이 변경될 수 있습니다. 특정 구성요소가 이후 응답에서 누락될 수 있습니다.

    자세한 내용은 아래의 주소 유형 및 주소 구성요소 유형을 참고하세요.

  • partial_match는 지오코더가 원래 요청에 대해 정확히 일치하는 결과를 반환하지 않았지만 요청된 주소의 일부분과 일치할 수 있음을 나타냅니다. 원래 요청에 맞춤법 오류 또는 불완전한 주소가 포함되어 있는지 검사할 수도 있습니다.

    부분 일치는 요청에 전달되는 지역 내에 상세 주소가 존재하지 않는 경우 가장 자주 발생합니다. 요청이 동일한 지역에 있는 두 개 이상의 위치와 일치하는 경우에도 부분 일치가 반환될 수 있습니다. 예를 들어 'Hillpar St, Bristol, UK'는 Henry Street 및 Henrietta Street 모두에 대해 부분 일치를 반환합니다. 요청에 맞춤법이 틀린 주소 구성요소가 포함된 경우에는 지오코딩 서비스에서 대체 주소를 제안할 수도 있습니다. 이러한 방식으로 실행된 제안도 부분 일치로 표시될 수 있습니다.

  • place_id는 다른 Google API와 함께 사용할 수 있는 장소의 고유 식별자입니다. 예를 들어 place_id를 Google Places API 라이브러리와 함께 사용하여 전화번호, 영업시간, 사용자 리뷰 등 지역 비즈니스의 세부정보를 가져올 수 있습니다. 장소 ID 개요를 참고하세요.
  • postcode_localities[]는 우편번호에 포함된 모든 지역을 나타내는 배열이며 결과가 여러 지역이 포함된 우편번호인 경우에만 존재합니다.

  • geometry에는 다음 정보가 포함됩니다.

    • location에는 지오코딩된 위도, 경도 값이 포함됩니다. 이 위치는 형식이 지정된 문자열이 아닌 LatLng 객체로 반환됩니다.
    • location_type은 지정된 위치에 대한 추가 데이터를 저장합니다. 현재 다음과 같은 값이 지원됩니다.
      • ROOFTOP은 반환된 결과가 정확한 지오코드를 반영함을 나타냅니다.
      • RANGE_INTERPOLATED는 반환된 결과가 일반적으로 도로에서 정확한 두 지점(예: 교차로) 간에 보간된 근사값을 반영함을 나타냅니다. 상세 주소에 옥상 지오코드를 사용할 수 없는 경우 일반적으로 보간된 결과가 반환됩니다.
      • GEOMETRIC_CENTER는 반환된 결과가 다중선(예: 거리) 또는 다각형(지역)과 같이 결과의 도형 중심임을 나타냅니다.
      • APPROXIMATE는 반환된 결과가 근사값임을 나타냅니다.

    • viewport는 반환된 결과에 권장되는 표시 영역을 저장합니다.
    • 선택적으로 반환되는 bounds는 반환된 결과를 완전히 포함할 수 있는 LatLngBounds를 저장합니다. 참고: 이러한 경계가 권장된 표시 영역과 일치하지 않을 수도 있습니다. 예를 들어 샌프란시스코에는 실질적으로 도시의 일부지만 표시 영역에 반환되면 안 되는 패럴론 섬이 포함됩니다.

주소는 지오코더에서 브라우저의 기본 언어 설정이나 language 매개변수를 사용하여 API JavaScript를 로드할 때 지정된 언어를 사용하여 반환합니다. 자세한 내용은 현지화를 참고하세요.

주소 유형 및 주소 구성요소 유형

GeocoderResult의 types[] 배열은 주소 유형을 나타냅니다. types[] 배열은 GeocoderAddressComponent 내에 반환되어 특정 주소 구성요소의 유형을 나타낼 수도 있습니다. 지오코더에서 반환하는 주소의 유형은 여러 가지입니다. 유형은 태그로 간주될 수도 있습니다. 예를 들어 많은 도시가 political 및 locality 유형으로 태그됩니다.

주소 유형과 주소 구성요소 유형 모두에서 다음과 같은 유형이 지오코더에 의해 지원되고 반환됩니다.

  • street_address는 정확한 상세 주소를 나타냅니다.
  • route는 이름이 지정된 경로(예: 'US 101')를 나타냅니다.
  • intersection은 일반적으로 두 주요 도로의 주요 교차로를 나타냅니다.
  • political은 정치적 독립체를 나타냅니다. 일반적으로 이 유형은 특정 행정 구역의 다각형을 나타냅니다.
  • country는 전국적인 정치적 독립체를 나타내고 일반적으로 지오코더에서 반환하는 순위가 가장 높은 유형입니다.
  • administrative_area_level_1은 국가 수준 아래 첫 번째 행정 독립체를 나타냅니다. 미국에서 이 행정 구역 수준은 주입니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다. 대부분의 경우 administrative_area_level_1 짧은 이름은 ISO 3166-2 하위 구역이나 기타 널리 보급된 목록들과 거의 일치하지만 지오코딩 결과는 다양한 신호와 위치 데이터를 기반으로 하기 때문에 이러한 일치가 보장되지는 않습니다.
  • administrative_area_level_2는 국가 수준 아래 두 번째 행정 독립체를 나타냅니다. 미국에서 이 행정 구역 수준은 카운티입니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
  • administrative_area_level_3은 국가 수준 아래 세 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
  • administrative_area_level_4는 국가 수준 아래 네 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
  • administrative_area_level_5는 국가 수준 아래 다섯 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
  • administrative_area_level_6은 국가 수준 아래 여섯 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
  • administrative_area_level_7은 국가 수준 아래 일곱 번째 행정 독립체를 나타냅니다. 이 유형은 하위 행정 구역을 나타냅니다. 모든 국가에 이러한 행정 구역 수준이 표시되지는 않습니다.
  • colloquial_area는 일반적으로 사용되는 독립체의 대체 이름을 나타냅니다.
  • locality는 도시 또는 마을로 통합된 정치적 독립체를 나타냅니다.
  • sublocality는 지역 아래 첫 번째 행정 독립체를 나타냅니다. 일부 위치의 경우 추가 유형 중 하나(sublocality_level_1~sublocality_level_5)를 받을 수도 있습니다. 각 하위 지역 수준은 하나의 행정 독립체입니다. 숫자가 클수록 더 작은 지리적 영역을 나타냅니다.
  • neighborhood는 이름이 지정된 동네를 나타냅니다.
  • premise는 이름이 지정된 위치, 일반적으로 공통된 이름을 가진 건물 또는 여러 건물을 나타냅니다.
  • subpremise는 아파트, 동/호수, 스위트와 같이 부지 수준 아래 주소 지정이 가능한 항목을 나타냅니다.
  • plus_code는 위도와 경도에서 파생된 인코딩된 위치 참조를 나타냅니다. Plus Code는 상세 주소가 없는(건물에 번호가 지정되지 않거나 거리 이름이 없는) 장소의 상세 주소 대신 사용할 수 있습니다. 자세한 내용은 https://plus.codes를 참고하세요.
  • postal_code는 국가 내에서 우편물을 보낼 때 사용되는 우편번호를 나타냅니다.
  • natural_feature는 유명한 자연 지형지물을 나타냅니다.
  • airport는 공항을 나타냅니다.
  • park는 이름이 지정된 공원을 나타냅니다.
  • point_of_interest는 이름이 지정된 관심 장소를 나타냅니다. 일반적으로 이러한 '관심 장소'는 '엠파이어 스테이트 빌딩' 또는 '에펠탑'과 같이 다른 카테고리에 쉽게 포함되지 않는 유명한 지역 항목입니다.

빈 유형 목록은 예를 들어 프랑스의 리외디와 같이 특정한 주소 요소에 대해 알려진 유형이 없다는 것을 나타냅니다.

위의 유형 외에 아래의 유형이 주소 구성 요소에 포함될 수도 있습니다.

참고: 이 목록은 전체 목록이 아니며 변경될 수 있습니다.

  • floor는 건물 주소의 층을 나타냅니다.
  • establishment는 일반적으로 아직 분류되지 않은 장소를 나타냅니다.
  • landmark는 탐색을 돕기 위해 참조로 사용되는 주변 장소를 나타냅니다.
  • point_of_interest는 이름이 지정된 관심 장소를 나타냅니다.
  • parking는 주차장 또는 주차 시설을 나타냅니다.
  • post_box는 특정 사서함을 나타냅니다.
  • postal_town은 일부 국가에서 우편 주소에 사용되는 locality 및 sublocality와 같은 지리적 영역의 그룹을 나타냅니다.
  • room은 건물 주소의 방을 나타냅니다.
  • street_number는 정확한 번지를 나타냅니다.
  • bus_station, train_station, transit_station은 버스, 기차, 대중교통 정류장의 위치를 나타냅니다.

상태 코드

status 코드는 다음 값 중 하나를 반환할 수 있습니다.

  • "OK"는 오류가 발생하지 않았음을 나타냅니다. 주소가 성공적으로 파싱되었고 한 개 이상의 지오코드가 반환되었습니다.
  • "ZERO_RESULTS"는 지오코딩이 성공했지만 반환된 결과가 없음을 나타냅니다. 지오코더가 존재하지 않는 address에 전달된 경우 이러한 결과가 발생할 수도 있습니다.
  • "OVER_QUERY_LIMIT"는 할당량을 초과했음을 나타냅니다.
  • "REQUEST_DENIED"는 요청이 거부되었음을 나타냅니다. 웹페이지에서 지오코더를 사용할 수 없습니다.
  • "INVALID_REQUEST"는 일반적으로 쿼리(address, components 또는 latlng)가 누락되었음을 나타냅니다.
  • "UNKNOWN_ERROR"는 서버 오류로 인해 요청을 처리하지 못했음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.
  • "ERROR"는 요청 시간이 초과되었거나 Google 서버에 연결하는 데 문제가 발생했음을 나타냅니다. 다시 시도하면 요청이 성공할 수도 있습니다.

이 예에서는 주소를 지오코딩하고 반환된 위도와 경도 값에 마커를 배치합니다. 핸들러는 익명 함수 리터럴로 전달됩니다.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

예 보기

표시 영역 상세 검색

지오코딩 서비스에 (경계 상자로 표시된) 지정된 표시 영역의 결과를 선택하도록 지시할 수 있습니다. GeocoderRequest 객체 리터럴 내에 bounds 매개변수를 설정하여 이 표시 영역의 경계를 정의하면 됩니다. 상세 검색은 경계 내의 결과만을 선택합니다. 이 경계 외부에 관련성이 더 높은 결과가 있는 경우 이 결과가 포함될 수도 있습니다.

예를 들어 'Winnetka'의 지오코드는 일반적으로 다음과 같은 시카고의 교외 지역을 반환합니다.

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

하지만 bounds 매개변수를 지정하여 로스앤젤레스 샌 페르난도 밸리의 경계 상자를 정의하면 이 지오코드에서 해당 위치에 있는 'Winnetka'라는 이름의 동네를 반환합니다.

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

지역 코드 상세 검색

region 매개변수를 명시적으로 사용하여 특정 지역에 편중된 결과를 반환하도록 지오코딩 서비스를 설정할 수 있습니다. 이 매개변수는 숫자가 아닌 두 자리 유니코드 지역 하위 태그로 지정된 지역 코드를 사용합니다. 이 태그는 'co.uk'의 'uk'와 같이 익숙한 두 자리 ccTLD('최상위 도메인') 값으로 직접 매핑됩니다. 경우에 따라 region 태그는 ccTLD 값과 다른 ISO-3166-1 코드도 지원합니다(예: 'Great Britain'의 'GB').

region 매개변수를 사용하는 경우:

  • 하나의 국가 또는 지역만 지정하세요. 값이 여러 개인 경우 무시되며 요청이 실패할 수 있습니다.
  • 2자리 지역 하위 태그(유니코드 CLDR 형식)만 사용하세요. 다른 값을 입력하면 오류가 발생합니다.
  • Google Maps Platform 노출 범위 세부정보에 나열된 국가 및 지역만 지원됩니다.

기본 Google 지도 애플리케이션에서 지오코딩을 제공하는 모든 도메인에 대해 지오코딩 요청을 보낼 수 있습니다. 상세 검색은 특정 도메인의 결과만을 선택합니다. 이 도메인 외부에 관련성이 더 높은 결과가 있는 경우 이 결과가 포함될 수도 있습니다.

예를 들면 'Toledo'의 지오코드는 지오코딩 서비스의 기본 도메인이 미국으로 설정되어 있으므로 다음 결과를 반환합니다.

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

region 필드가 'es'(스페인)로 설정된 'Toledo'의 지오코딩은 스페인 도시를 반환합니다.

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

구성 요소 필터링

구성요소 필터를 사용하여 특정 지역으로 제한된 주소 결과를 반환하도록 지오코딩 서비스를 설정할 수 있습니다. componentRestrictions 매개변수에 필터를 지정합니다. 필터 값은 다른 지오코딩 요청과 동일한 방식의 맞춤법 교정 및 부분 일치를 지원합니다.

지오코더는 모든 구성요소 필터와 일치하는 결과만 반환합니다. 즉 필터 사양을 OR이 아닌 AND로 평가합니다.

구성요소 필터는 다음 중 하나 이상의 항목으로 구성됩니다.

  • route는 경로의 긴 이름 또는 짧은 이름과 일치하는 항목을 찾습니다.
  • locality는 지역 및 하위 지역 유형과 일치하는 항목을 찾습니다.
  • administrativeArea는 모든 행정 구역 수준과 일치하는 항목을 찾습니다.
  • postalCode는 우편번호 및 우편번호 접두사와 일치하는 항목을 찾습니다.
  • country는 국가 이름 또는 두 자리 ISO 3166-1 국가 코드와 일치하는 항목을 찾습니다. 참고: API는 국가 정의에 대한 ISO 표준을 따르며 필터링은 해당하는 국가의 ISO 코드를 사용할 때 가장 잘 작동합니다.

다음 예에서는 componentRestrictions 매개변수를 사용하여 country 및 postalCode를 기준으로 필터링하는 방법을 보여줍니다.

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

결과 없음 시 처리

역 지오코딩의 경우 기본적으로 status=ZERO_RESULTS에서 약속이 중단됩니다. 그러나 이 경우에도 추가 응답 수준 필드인 plus_code 및 address_descriptor가 채워질 수 있습니다. fulfillOnZeroResults 매개변수에 true가 제공되면 약속이 손상되지 않으며 이러한 추가 필드가 있는 경우 약속에서 액세스할 수 있습니다.

다음은 남극의 위도/경도에 대한 이 동작의 예입니다. 역지오코딩 결과가 없더라도 fulfillOnZeroResults=true를 설정하면 약속에서 플러스 코드를 계속 출력할 수 있습니다. 

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

주소 설명어

주소 설명어에는 명소와 지역을 사용하여 위치를 설명하는 데 도움이 되는 추가 정보가 포함됩니다. 주소 설명자 데모를 확인하여 이 기능을 살펴보세요.

주소 설명자는 extraComputations 매개변수를 사용하여 사용 설정할 수 있습니다. 지오코딩 요청, 역 지오코딩 요청 또는 장소 지오코딩 요청에 extra_computations=ADDRESS_DESCRIPTORS를 포함하여 응답에서 주소 설명자를 수신합니다.

장소 지오코딩의 예

다음 쿼리에는 델리의 장소 주소가 포함되어 있습니다.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({ 
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

역 지오코딩의 예

다음 쿼리에는 델리의 위치에 대한 위도/경도 값이 포함되어 있습니다.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

주소 설명자 예

address_descriptor 예시는 다음과 같습니다.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

각 address_descriptor 객체에는 landmarks 및 areas라는 두 배열이 있습니다. landmarks 배열에는 요청된 좌표와의 근접성, 랜드마크의 빈도, 가시성을 고려하여 관련성 순으로 순위가 매겨진 최대 5개의 결과가 포함됩니다. 각 랜드마크 결과에는 다음 값이 포함됩니다.

  • place_id는 랜드마크 결과의 장소 ID입니다. 장소 ID 개요를 참고하세요.
  • display_name는 랜드마크의 표시 이름이며 language_code 및 text를 포함합니다.
  • straight_line_distance_meters는 입력 좌표와 랜드마크 결과 간의 점 간 거리(단위: 미터)입니다.
  • travel_distance_meters는 입력 좌표와 랜드마크 결과 간의 도로 네트워크를 통해 이동한 거리(도로 제한사항 무시)입니다(단위: 미터).
  • spatial_relationship는 입력 좌표와 랜드마크 결과 간의 추정된 관계입니다.
    • "NEAR"는 다음 중 어느 것에도 해당하지 않는 경우의 기본 관계입니다.
    • 입력 좌표가 랜드마크와 연결된 구조물의 경계 내에 포함되는 경우 "WITHIN"입니다.
    • 입력 좌표가 랜드마크 또는 랜드마크의 액세스 포인트에 바로 인접한 경우 "BESIDE"입니다.
    • 입력 좌표가 경로 반대편의 랜드마크와 정반대인 경우 "ACROSS_THE_ROAD"입니다.
    • 입력 좌표가 랜드마크와 동일한 경로에 있지만 "BESIDES" 또는 "ACROSS_THE_ROAD"가 아닌 경우 "DOWN_THE_ROAD"입니다.
    • 입력 좌표가 랜드마크와 직각 경로를 따라 있는 경우 (단일 회전으로 제한됨) "AROUND_THE_CORNER"
    • 입력 좌표가 지형지물과 공간적으로 가깝지만 액세스 포인트와는 멀리 떨어져 있는 경우 "BEHIND"
  • types는 명소의 장소 유형입니다.

areas 객체는 최대 3개의 응답을 포함하며, 동네, 하위 지역, 대규모 단지와 같이 작은 지역을 나타내는 장소로 제한됩니다. 요청된 좌표가 포함된 영역이 먼저 나열되며 가장 작은 영역부터 가장 큰 영역 순으로 정렬됩니다. 각 areas 결과에는 다음 값이 포함됩니다.

  • place_id는 지역 결과의 장소 ID입니다. 장소 ID 개요를 참고하세요.
  • display_name은 지역의 표시 이름으로 language_code 및 text를 포함합니다.
  • containment는 입력 좌표와 영역 결과 간의 예상 포함 관계입니다.
    • "NEAR"는 다음 중 어느 것에도 해당하지 않는 경우의 기본 관계입니다.
    • 입력 좌표가 영역 중앙에 가까울 때 "WITHIN"
    • 입력 좌표가 영역 가장자리에 가까울 때 "OUTSKIRTS"

주소 설명자 노출 범위

이 기능은 일부 국가에서만 사용할 수 있습니다.

이 기능은 미리보기 기능이므로 의견을 보내주시면 감사하겠습니다. address-descriptors-feedback@google.com으로 이메일을 보내주세요.

역 지오코딩(주소 조회)

일반적으로 지오코딩이라는 용어는 사람이 읽을 수 있는 주소를 지도상의 위치로 변환하는 과정을 가리킵니다. 반대로 지도상의 위치를 사람이 읽을 수 있는 주소로 변환하는 과정은 역 지오코딩이라고 합니다.

텍스트 address를 제공하는 대신 location 매개변수에 쉼표로 구분된 위도/경도 쌍을 제공합니다.

다음 예에서는 위도/경도 값을 지오코딩하고 해당 위치로 지도의 중심을 이동하여 형식이 지정된 주소가 포함된 정보 창을 표시합니다.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
예 보기

샘플 사용해 보기

이전 예에서는 results[0]를 선택하여 첫 번째 결과를 표시했습니다. 역 지오코더는 대개 두 개 이상의 결과를 반환합니다. 지오코딩된 주소는 단순히 우편 주소가 아니라 위치를 지리적으로 명명하는 방법입니다. 예를 들어 시카고시의 한 지점을 지오코딩하는 경우 지오코딩된 지점은 상세 주소, 도시(시카고), 주(일리노이) 또는 국가(미국)로 레이블이 지정될 수 있습니다. 지오코더에서는 이 모두가 다 주소입니다. 역 지오코더는 이 결과를 모두 반환합니다.

역 지오코더는 정치적 독립체(국가, 주, 도시 및 동네), 상세 주소 및 우편번호가 일치하는 항목을 찾습니다.

다음은 위 쿼리에서 반환할 수 있는 주소 목록의 예입니다. 

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

주소는 일치도가 가장 높은 주소에서 낮은 주소 순으로 반환됩니다. 일반적으로 이 경우처럼 가장 눈에 띄는 결과가 더 정확한 주소입니다. 가장 구체적인 상세 주소부터 동네. 도시, 카운티, 주와 같이 덜 구체적인 독립체까지 다양한 유형의 주소가 반환됩니다. 더 일반적인 주소와 일치하는 항목을 찾으려면 results[].types 필드를 검사해 보세요.

참고: 역 지오코딩은 과학적으로 정확하지 않습니다. 지오코더는 특정 오차 범위 내에서 주소를 가진 가장 가까운 위치를 찾으려고 시도합니다.

장소 ID의 주소 가져오기

지정된 장소 ID의 주소를 찾으려면 placeId를 제공하세요. 장소 ID는 다른 Google API에 사용할 수 있는 고유 식별자입니다. 예를 들어 Roads API에서 반환된 placeId를 제공하여 스냅된 지점의 주소를 가져올 수 있습니다. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참고하세요.

placeId를 제공하는 경우 요청에 다음 필드를 포함할 수 없습니다.

  • address
  • latLng
  • location
  • componentRestrictions

다음 예에서는 장소 ID를 받아 해당하는 주소를 찾은 다음 그 위치에 지도의 중심을 맞춥니다. 또한 관련 장소의 형식이 지정된 주소를 보여주는 정보 창을 표시합니다.

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
예 보기

샘플 사용해 보기