logo
Tutorials Examples naver map js api v3 네이버 지도 API Geocoder를 활용한 주소와 좌표 검색 API 호출하기

Geocoder를 활용한 주소와 좌표 검색 API 호출하기

Geocoder 서브 모듈을 활용하여 주소->좌표 검색(geocode), 좌표->주소 검색(reversegeocode) API를 호출할 수 있습니다.
등록된 Client Id웹 서비스 URL이 일치하는 페이지에서만 정상적으로 사용할 수 있습니다.

주소 <-> 좌표 변환 API 호출 예제는 주소와 좌표 검색 API 사용하기를 참고합니다.

서브 모듈 로드하기

Geocoder를 사용하려면 Geocoder 서브 모듈 JavaScript 파일을 로드해야 합니다. 다음과 같이 파일을 로드합니다.
Geocoder 서브 모듈을 사용하려면 NAVER 지도 API v3이 로드되어 있어야 합니다. 자세한 사항은 서브 모듈 시스템을 참고합니다.

NAVER 지도 API v3은 httphttps 프로토콜을 모두 지원합니다.

<script type="text/javascript" src="https://openapi.map.naver.com/openapi/v3/maps.js?clientId=YOUR_CLIENT_ID&submodules=geocoder"></script>

naver.maps.Service 객체

서버 API 서비스를 활용하려면 naver.maps.Service 정적 객체를 사용합니다.
Service 객체는 서버 API를 호출하는 데 필요한 파라미터와 메서드를 제공합니다.

NAVER 지도 API v3을 통해 호출하는 서버 API는
호출시 마다 애플리케이션의 API 일일 허용량을 사용합니다.

CoordType 객체

CoordType 객체는 서버 API 호출 및 결과로 사용할 좌표 체계명을 나타냅니다.
지원하는 좌표 체계의 목록은 아래와 같습니다.

  • LATLNG: 위/경도 좌표계를 나타냅니다. 기본값
  • TM128: TM128 좌표계를 나타냅니다.

Encoding 객체

Encoding 객체는 서버 API 호출 및 결과 출력 시 사용한 text 인코딩 형태를 나타냅니다.
지원하는 text 인코딩의 목록은 아래와 같습니다.

  • UTF_8: utf-8 인코딩을 나타냅니다.(기본값)
  • EUC_KR: euc-kr 인코딩을 나타냅니다.

Status 객체

Status 객체는 서버 API 호출 결과의 상태를 나타냅니다.

  • OK: 요청이 성공한 상태입니다.
  • ERROR: 요청이 실패한 상태입니다.

서버 API 호출 시 전달하는 callback 함수의 첫 번째 파라미터로 Status값이 전달되며, 이 값으로 요청 결과의 성공 및 실패 여부를 확인할 수 있습니다.

naver.maps.Service.geocode({ address: '모르는 주소' }, function(status, response) {
    if (status === naver.maps.Service.Status.ERROR) {
        return alert('Something wrong!');
    }

    // 성공 시의 response 처리
});

ServiceOptions

ServiceOptions는 서버 API 호출 시 전달할 기본 파라미터를 정의합니다.
coordTypeencoding 파라미터를 정의할 수 있으며, 각 파라미터의 값으로 CoordTypeEncoding 객체를 활용할 수 있습니다.

파라미터명 기본값 설명
coordType naver.maps.Service.CoordType.LATLNG 좌표 체계의 이름
encoding naver.maps.Service.Encoding.UTF_8 서비스 응답의 인코딩

주소 -> 좌표 검색(geocode) API 호출

Geocoder 서브 모듈을 이용해, 주소로 좌표를 검색하는 geocode API를 호출할 수 있습니다.
naver.maps.Service.geocode 또는 naver.maps.Service.fromAddrToCoord 메서드를 사용하여 호출할 수 있습니다.
첫 번째 파라미터로 ServiceOptions 객체에 address 파라미터를 추가한 ***options***를 전달하며, address 옵션은 필수로 전달해야 합니다.

address 파라미터는 검색할 주소의 문자열입니다.

두 번째 파라미터는 요청의 결과를 처리할 callback 함수입니다.

fromAddrToCoord 편의 메서드는 내부적으로 geocode 메서드를 호출하며, 동일하게 동작합니다.

naver.maps.Service.geocode({
        address: '불정로 6'
    }, function(status, response) {
        if (status !== naver.maps.Service.Status.OK) {
            return alert('Something wrong!');
        }

        var result = response.result, // 검색 결과의 컨테이너
            items = result.items; // 검색 결과의 배열

        // do Something
    });

요청이 성공하면 callback 함수의 두 번째 파라미터로 아래와 같은 형태의 json 객체 response가 전달됩니다.

{
  "result": {
    "total": 1,
    "userquery": "불정로 6",
    "items": [
      {
        "address": "경기도 성남시 분당구 불정로 6 그린팩토리",
        "addrdetail": {
          "country": "대한민국",
          "sido": "경기도",
          "sigugun": "성남시 분당구",
          "dongmyun": "불정로",
          "rest": " 6 그린팩토리"
        },
        "isRoadAddress": true,
        "point": {
          "x": 127.1052133,
          "y": 37.3595316
        }
      }
    ]
  }
}

response 형태에 대한 자세한 내용은 GeocodeResponse를 참조합니다.

NAVER 지도 API v3을 이용해 호출하는 서버 API는 호출할 때마다 애플리케이션의 API 일일 허용량을 사용합니다.

좌표 -> 주소 검색(reversegeocode) API 호출

Geocoder 서브 모듈을 이용해, 좌표로 주소를 검색하는 reversegeocode API를 호출할 수 있습니다.
naver.maps.Service.reverseGeocode 또는 naver.maps.Service.fromCoordToAddr 메서드를 사용하여 호출할 수 있습니다.
첫 번째 파라미터로 ServiceOptions 객체에 location 파라미터를 추가한 ***options***를 전달하며, location 옵션은 필수로 전달해야 합니다.

location 파라미터는 검색할 좌표이며, Coord 객체 또는 CoordLiteral 형태로 전달합니다.

두 번째 파라미터는 요청의 결과를 처리할 callback 함수입니다.

fromCoordToAddr 편의 메서드는 내부적으로 reverseGeocode 메서드를 호출하며, 동일하게 동작합니다.

naver.maps.Service.reverseGeocode({
        location: new naver.maps.LatLng(37.3595316, 127.1052133),
    }, function(status, response) {
        if (status !== naver.maps.Service.Status.OK) {
            return alert('Something wrong!');
        }

        var result = response.result, // 검색 결과의 컨테이너
            items = result.items; // 검색 결과의 배열

        // do Something
    });

요청이 성공하면 callback 함수의 두 번째 파라미터로 아래와 같은 형태의 json 객체 response가 전달됩니다.

{
  "result": {
    "total": 2,
    "userquery": "127.1052133,37.3595316",
    "items": [
      {
        "address": "경기도 성남시 분당구 정자동 178-1",
        "addrdetail": {
          "country": "대한민국",
          "sido": "경기도",
          "sigugun": "성남시 분당구",
          "dongmyun": "정자동",
          "rest": "178-1"
        },
        "isRoadAddress": false,
        "point": {
          "x": 127.1052208,
          "y": 37.3595122
        }
      },
      {
        "address": "경기도 성남시 분당구 불정로 6 그린팩토리",
        "addrdetail": {
          "country": "대한민국",
          "sido": "경기도",
          "sigugun": "성남시 분당구",
          "dongmyun": "불정로",
          "rest": "6 그린팩토리"
        },
        "isRoadAddress": true,
        "point": {
          "x": 127.1052133,
          "y": 37.3595316
        }
      }
    ]
  }
}

response 형태에 대한 자세한 내용은 ReverseGeocodeResponse를 참조합니다.

NAVER 지도 API v3을 이용해 호출하는 서버 API는 호출할 때마다 애플리케이션의 API 일일 허용량을 사용합니다.

Examples: 주소와 좌표 검색 API 사용하기