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

Geocoder 서브 모듈을 활용하여 주소->좌표 검색(geocode), 좌표->주소 검색(reversegeocode) API를 호출할 수 있습니다.
등록된 Client Id와 웹 서비스 URL이 일치하는 페이지에서만 정상적으로 사용할 수 있습니다.
Geocoder 서브 모듈은 Geocoding API와 ReverseGeocoding API를 호출합니다.
Geocoder 서브 모듈을 사용하고자 할 경우 Module:geocoder의 사전 준비 사항을 참고하세요.

Geocoder는 Geocoding와 ReverseGeocoding의 일일 허용량을 사용합니다.

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

서브 모듈 로드하기

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

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

네이버 클라우드 플랫폼

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

공공기관용

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

금융기관용

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

naver.maps.Service 객체

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

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

CoordinatesType 객체

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

LATLNG: 위/경도(WGS 84) 좌표계를 나타냅니다. 기본값
TM128: TM128(KATECH) 좌표계를 나타냅니다.
UTMK: UTMK 좌표계를 나타냅니다.
EPSG3857: 구글맵(EPSG3857) 좌표계를 나타냅니다.

Status 객체

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

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

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

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

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

ServiceOptions

ServiceOptions는 서버 API 호출 시 전달할 기본 파라미터를 정의합니다.
sourcecrs, targetcrs, orders 파라미터를 정의할 수 있으며, 각 파라미터의 값으로 CoordinatesType 및 [OrderType] 객체를 활용할 수 있습니다.

파라미터명	기본값	설명
sourcecrs	naver.maps.Service.CoordinatesType.LATLNG	좌표 체계의 이름
targetcrs	naver.maps.Service.CoordinatesType.LATLNG	좌표 체계의 이름
orders	naver.maps.Service.OrderType.ADDR	변환 작업 이름

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

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

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

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

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

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

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

        // do Something
    });

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

{
  "v2": {
    "status": "OK",
    "meta": {
      "totalCount": 1,
      "page": 1,
      "count": 1
    },
  "addresses": [
    {
        "roadAddress": "경기도 성남시 분당구 불정로 6 그린팩토리",
        "jibunAddress": "경기도 성남시 분당구 정자동 178-1 그린팩토리",
        "englishAddress": "6, Buljeong-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea",
        "addressElements": [
          {
            "types": [
              "POSTAL_CODE"
            ],
          "longName": "13561",
          "shortName": "",
          "code": ""
          }
        ],
        "x": "127.10522081658463",
        "y": "37.35951219616309",
        "distance": 20.925857741585514
    }
  ],
  "errorMessage": ""
  }
}

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

Geocode의 상세 설명은 Geocoding API를 참조합니다.

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

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

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

coords 파라미터는 검색할 좌표이며, 경도,위도로 된 문자열(예: 128.12345,37.98776) 또는 Coord 객체 형태로 전달합니다.