지오코딩 Geocoding

개요

지오코딩은 주소(예: '1600 Amphitheatre Parkway, Mountain View, CA')를 지리적 좌표(예: 위도 37.423021, 경도 122.083739)로 변환하는 프로세스입니다. 이 지리적 좌표를 사용하여 위치 아이콘을 표시하거나 지도를 배치할 수 있습니다.

Google Maps API에서는 사용자 입력에서 동적으로 주소를 지오코딩하기 위한 지오코더 클래스를 제공합니다. 이 요청은 서비스 남용을 방지하기 위해 빈도가 제한됩니다. 대신, 알려진 고정 주소를 지오코딩하려면 지오코딩 웹 서비스 문서를 참조하세요.

지오코딩 요청

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

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

GeocodeRequest 객체 리터럴은 다음 필드를 포함합니다.

{
 address: string,
 latLng: LatLng,
 bounds: LatLngBounds,
 region: string
}

이러한 필드는 다음과 같습니다.

• address(필수*) — 지오코딩하려는 주소입니다.
• latLng(필수*) — 읽을 수 있는 가장 가까운 주소를 얻기 위한 LatLng입니다.
• bounds(선택사항) — 한도 내에서 지오코드 결과를 더 분명하게 하기 위한 LatLngBounds입니다. 자세한 내용은 아래의 뷰포트 바이어스를 참조하세요.
• region(선택사항) — IANA 언어의 region 하위 태그로 지정된 지역 코드입니다. 대부분의 경우 이러한 태그는 익숙한 ccTLD('최상위 도메인') 두 문자 값에 직접 매핑됩니다. 자세한 내용은 아래의 지역 코드 바이어스를 참조하세요.

* 참고: address 또는 latLng를 전달하여 조회할 수 있습니다. latLng를 전달하면 지오코더가 역 지오코드라는 작업을 수행합니다. 자세한 내용은 역 지오코딩을 참조하시기 바랍니다.

bounds 및 region 매개변수는 지오코더의 결과에 영향을 줄뿐이고 완전히 제한하지는 않습니다.

지오코딩 응답

지오코딩 서비스에 콜백 메소드가 있어야 지오코더 결과 검색 시 실행됩니다. 이 콜백은 두 매개변수를 전달하여 results 및 status 코드를 순서대로 보유해야 합니다. 지오코더에서 두 개 이상의 항목을 반환할 수 있기 때문에 GeocoderResults 객체 리터럴은 배열입니다.

지오코딩 결과

GeocoderResults 객체 리터럴은 단일 지오코딩 결과를 나타내는 객체이며 다음과 같은 형식을 취합니다.

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

이러한 필드는 다음과 같습니다.

• types[]는 반환된 결과의 유형을 나타내는 배열입니다. 이 배열은 결과에 반환된 기능의 유형을 식별하는 하나 이상의 태그 집합을 포함합니다. 예를 들어 '시카고'의 지오코드는 'locality'를 반환하여 '시카고'가 도시임을 나타내며 'political'도 반환하여 정치적 구역임을 나타냅니다.
• formatted_address는 이 위치에 대한 읽을 수 있는 주소를 포함하는 문자열입니다. 이 주소는 주로 'postal address'와 일치하고 국가마다 다를 수 있습니다. 영국과 같은 일부 국가에서는 라이선스 제한으로 인해 실제 주소의 배포를 허용하지 않습니다. 이 주소는 일반적으로 하나 이상의 주소 구성요소로 이루어집니다. 예를 들어 '111 8th Avenue, New York, NY'라는 주소에는 '111 8th Avenue'(번지수), 'New York'(도시) 및 'NY'(미국의 주)와 같은 개별 주소 구성요소가 포함됩니다. 아래에서 이러한 주소 구성요소를 설명합니다. 유형에 대한 자세한 내용은 아래의 유형을 참조하세요.
• address_component[]는 위에 설명된 대로 개별 주소 구성요소를 포함하는 배열입니다.

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

  • location은 지오코딩된 위도와 경도 값을 포함합니다. 이 위치는 형식화된 문자열이 아닌 LatLng 객체로 반환됩니다.
  • location_type은 지정된 위치에 대한 추가 데이터를 저장합니다. 현재 지원되는 값은 다음과 같습니다.
    • google.maps.GeocoderLocationType.ROOFTOP은 반환된 결과가 정확한 지오코드를 반영함을 나타냅니다.
    • google.maps.GeocoderLocationType.RANGE_INTERPOLATED는 반환된 결과가 교차점 같은 두 개의 정확한 점 사이에 삽입된 근사값(일반적으로 도로에 대한)을 반영함을 나타냅니다. 삽입된 결과는 일반적으로 옥상 지오코드를 번지수에 사용할 수 없을 때 반환됩니다.
    • google.maps.GeocoderLocationType.GEOMETRIC_CENTER는 반환된 결과가 폴리라인(예: 거리) 또는 폴리곤(지역)과 같이 결과의 형상 중심임을 나타냅니다.
    • google.maps.GeocoderLocationType.APPROXIMATE는 반환된 결과가 근사치임을 나타냅니다.
  
  
  • viewport는 반환된 결과에 대해 권장되는 뷰포트를 저장합니다.
  • 선택적으로 반환되는 bounds는 반환된 결과를 완전히 포함할 수 있는 LatLngBounds를 저장합니다. 이러한 경계는 권장된 뷰포트와 일치하지 않을 수도 있습니다. 예를 들어 샌프란시스코에는 엄밀히 따지면 도시에 속해 있지만 뷰포트에서는 반환되면 안 되는 Farallon 섬이 포함되어 있습니다.

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

주소 구성요소 유형

반환된 결과 내 types[] 배열은 주소 유형을 나타냅니다. 이러한 유형이 address_components[] 배열 내에 반환되어 특정 주소 구성요소의 유형을 나타낼 수도 있습니다. 지오코더 내 주소는 여러 유형일 수 있으며 이러한 유형은 '태그'로 간주될 수 있습니다. 예를 들어 여러 도시는 political 및 locality 유형으로 태그가 지정됩니다.

지원되는 유형은 다음과 같으며 HTTP 지오코더에 의해 반환됩니다.

• street_address는 정확한 번지수를 나타냅니다.
• route는 이름이 지정된 경로(예: 'US 101')를 나타냅니다.
• intersection은 일반적으로 두 주요 도로의 주요 교차로를 나타냅니다.
• political은 정치적 구역을 나타냅니다. 일반적으로 이 유형은 몇몇 도시 행정구역의 폴리곤을 나타냅니다.
• country는 국가 정치적 구역을 나타내고 일반적으로 지오코더에 의해 반환되는 최상위 유형입니다.
• administrative_area_level_1은 국가 수준 아래 첫 번째 도시 구역을 나타냅니다. 미국 내에서 이러한 행정구역 수준은 주입니다. 모든 국가가 이러한 행정구역 수준을 나타내지는 않습니다.
• administrative_area_level_2는 국가 수준 아래 두 번째 도시 구역을 나타냅니다. 미국 내에서 이러한 행정구역 수준은 카운티입니다. 모든 국가가 이러한 행정구역 수준을 나타내지는 않습니다.
• administrative_area_level_3은 국가 수준 아래 세 번째 도시 구역을 나타냅니다. 이 유형은 작은 도시 구획을 나타냅니다. 모든 국가가 이러한 행정구역 수준을 나타내지는 않습니다.
• colloquial_area는 구역에 일반적으로 사용되는 대체 이름을 나타냅니다.
• locality는 편입된 시/군/구의 정치적 구역을 나타냅니다.
• sublocality는 locality 아래 첫 번째 도시 구역을 나타냅니다.
• neighborhood는 이름이 지정된 인근 지역을 나타냅니다.
• premise는 이름이 지정된 위치, 일반적으로 공통 이름을 가진 건물 또는 여러 건물을 나타냅니다.
• subpremise는 이름이 지정된 위치 아래 첫 번째 구역, 일반적으로 공통 이름을 가진 여러 건물 내 한 건물을 나타냅니다.
• postal_code는 국가 내에서 우편을 보낼 때 주소로 사용되는 우편번호를 나타냅니다.
• natural_feature는 주요 자연지물을 나타냅니다.
• airport는 공항을 나타냅니다.
• park는 이름이 지정된 공원을 나타냅니다.

위에 나열된 유형 외에도 주소 구성요소는 다음 유형을 나타낼 수 있습니다.

• post_box는 특정 우편함을 나타냅니다.
• street_number는 정확한 상세 주소를 나타냅니다.
• floor는 건물 주소의 층을 나타냅니다.
• room은 건물 주소의 사무실을 나타냅니다.

상태 코드

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

• google.maps.GeocoderStatus.OK는 지오코딩이 성공했음을 나타냅니다.
• google.maps.GeocoderStatus.ZERO_RESULTS는 지오코딩이 성공했지만 반환된 결과가 없음을 나타냅니다. 이는 지오코딩이 존재하지 않는 address 또는 원격 지역의latng을 전달받는 경우 발생할 수 있습니다.
• google.maps.GeocoderStatus.OVER_QUERY_LIMIT는 할당량을 초과되었음을 나타냅니다.
• google.maps.GeocoderStatus.REQUEST_DENIED는 요청이 특정 사유로 인해 거부되었음을 나타냅니다.
• google.maps.GeocoderStatus.INVALID_REQUEST는 일반적으로 쿼리(address 또는 latLng)가 누락되었음을 나타냅니다.

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

  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,
      mapTypeId: google.maps.MapTypeId.ROADMAP
    }
    map = new google.maps.Map(document.getElementById("map_canvas"), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById("address").value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == google.maps.GeocoderStatus.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_canvas" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

예제 보기(geocoding-simple.html)

역 지오코딩(주소 조회)

일반적으로 지오코딩이라는 용어는 읽을 수 있는 주소를 지도 위의 위치로 변환하는 과정을 나타냅니다. 반대로 지도 위의 위치를 읽을 수 있는 주소로 변환하는 과정을 역 지오코딩이라고 합니다.

Geocoder는 역 지오코딩을 직접 지원합니다. 텍스트 address를 제공하는 대신, latLng 매개변수에 쉼표로 구분된 위도/경도 쌍을 제공합니다.

다음 예제에서는 위도/경도 값을 지오코딩하고 위치로 지도의 중심을 이동하여 형식화된 주소로 정보 창을 표시합니다. 두 번째 결과도 반환되는데, 이는 첫 번째 보다 덜 구체적입니다(이 경우 인근지역 이름).

  var geocoder;
  var map;
  var infowindow = new google.maps.InfoWindow();
  var marker;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(40.730885,-73.997383);
    var mapOptions = {
      zoom: 8,
      center: latlng,
      mapTypeId: google.maps.MapTypeId.ROADMAP
    }
    map = new google.maps.Map(document.getElementById("map_canvas"), mapOptions);
  }

  function codeLatLng() {
    var input = document.getElementById("latlng").value;
    var latlngStr = input.split(",",2);
    var lat = parseFloat(latlngStr[0]);
    var lng = parseFloat(latlngStr[1]);
    var latlng = new google.maps.LatLng(lat, lng);
    geocoder.geocode({'latLng': latlng}, function(results, status) {
      if (status == google.maps.GeocoderStatus.OK) {
        if (results[1]) {
          map.setZoom(11);
          marker = new google.maps.Marker({
              position: latlng,
              map: map
          });
          infowindow.setContent(results[1].formatted_address);
          infowindow.open(map, marker);
        }
      } else {
        alert("Geocoder failed due to: " + status);
      }
    });
  }

위 예제에서는 results[1]를 선택하여 두 번째 결과를 표시합니다. 역 지오코더는 흔히 둘 이상의 결과를 반환합니다. 지오코딩 '주소'는 단순한 우편 주소일 뿐만 아니라 위치를 지리적으로 명명하는 모든 방법입니다. 예를 들어 시카고에 있는 한 점을 지오코딩할 때 지오코딩된 점은 번지수, 도시(시카고), 주(일리노이) 또는 국가(미국)로 라벨이 지정될 수 있습니다. 지오코더에게는 모든 것이 주소입니다. 역 지오코더는 이러한 결과를 모두 반환합니다.

역 지오코더는 정치적 구역(국가, 지방, 도시 및 인근지역), 상세 주소 및 우편번호와 일치합니다.

이전 쿼리에서 반환되는 전체 주소 목록은 아래와 같습니다.

results[0].formatted_address: "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
results[1].formatted_address: "Williamsburg, NY, USA",
results[2].formatted_address: "New York 11211, USA",
results[3].formatted_address: "Kings, New York, USA",
results[4].formatted_address: "Brooklyn, New York, USA",
results[5].formatted_address: "New York, New York, USA",
results[6].formatted_address: "New York, USA",
results[7].formatted_address: "United States"

주소는 가장 많이 일치하는 것부터 순서대로 반환됩니다. 일반적으로 보다 정확한 주소가 이 경우에서와 같이 가장 중요한 결과입니다. 여기서는 가장 구체적인 번지수에서 덜 구체적인 정치적 구역에 이르기까지 여러 다른 유형의 주소를 반환합니다(예: 인근지역, 도시, 카운티, 주 등). 보다 일반적인 주소와 일치시키려면 results[].types 필드를 확인하는 것이 좋습니다.

참고: 지오코딩은 정밀 과학이 아닙니다. 지오코더는 특정 허용 범위 내에서 가장 가까운 주소 위치를 검색합니다.

예제 보기(geocoding-reverse.html)

뷰포트 바이어스

지오코딩 서비스가 특정 뷰포트 내의 결과를 선호하도록 지시할 수도 있습니다(경계상자로 표현됨). 이는 bounds 매개변수를 GeocodeRequest 객체 리터럴 내에 설정하여 이 뷰포트의 경계를 정의함으로써 수행할 수 있습니다. 바이어스는 경계 내의 결과만을 선호하지만, 이 경계 외부에 관련성이 더 높은 결과가 있다면 이를 포함될 수 있습니다.

예를 들어 '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"
  }
}

하지만 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"
  }
}

지역 코드 바이어스

region 매개변수를 명시적으로 사용하여 지오코딩 서비스에서 특정 지역에 바이어스된 결과를 반환하도록 설정할 수도 있습니다. 이 매개변수는 IANA 언어 region 하위 태그로 지정된 지역 코드를 취합니다. 대부분의 경우 이러한 태그는 'co.uk'의 'uk'와 같은 익숙한 ccTLD('최상위 도메인') 두 문자 값에 직접 매핑됩니다. 어떤 경우에는 region 태그에서 ISO-3166-1 코드도 지원하는데, 이 코드는 ccTLD 값과 다른 경우가 더러 있습니다(예:'Great Britain'의 경우 'GB').

지오코딩 요청은 주 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"]
  }]
}

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