logo
Tutorials Examples naver map js api v3 네이버 지도 API Service

StaticObjects: Service

naver.maps. Service

Service 객체는 NAVER 지도 API v3을 이용해 호출할 수 있는 서버 API들을 메서드로 제공합니다.

Tutorials

Members


<static, readonly> CoordinatesType

CoordinatesType 객체는 좌표 체계의 이름을 나타냅니다.

Properties
Name Type Default Description
LATLNG string epsg:4326

위/경도(WGS 84) 좌표계를 나타냅니다.

UTMK string nhn:2048

UTMK 좌표계를 나타냅니다.

TM128 string nhn:128

TM128(KATECH) 좌표계를 나타냅니다.

EPSG3857 string epsg:3857

구글맵(EPSG3857) 좌표계를 나타냅니다.


<static, readonly> GeocodeStatus

GeocodeStatus Geocode 응답 상태를 나타냅니다.

Properties
Name Type Default Description
OK string OK

정상 응답

INVALID_REQUEST string INVALID_REQUEST

요청 에러

SYSTEM_ERROR string SYSTEM_ERROR

예외처리가 안된 에러


<static, readonly> OrderType

OrderType 객체는 변환 작업 이름을 나타냅니다.

Properties
Name Type Default Description
LEGAL_CODE string legalcode

좌표를 법정동으로 나타냅니다.

ADDR string addr

좌표를 행정동으로 나타냅니다.

ROAD_ADDR string roadaddr

좌표를 지번 주소로 나타냅니다.

ADM_CODE string admcode

좌표를 도로명 주소로 나타냅니다.


<static, readonly> ReverseGeocodeStatusCode

ReverseGeocodeStatusCode ReverseGeocode 응답 상태 코드를 나타냅니다.

Properties
Name Type Default Description
CODE_0 string 0

정상적인 기능수행 및 반환된 결과가 있는 경우

CODE_3 string 3

정상적인 기능수행 및 반환된 결과가 없는 경우

CODE_100 string 100

요청 파라미터가 잘못된 경우

CODE_900 string 900

정의되지 않은 에러


<static, readonly> ReverseGeocodeStatusName

ReverseGeocodeStatusName ReverseGeocode 응답 상태 이름을 나타냅니다.

Properties
Name Type Argument Default Description
OK string ok

정상적인 기능수행 및 반환된 결과가 있는 경우

NO_RESULTS string <optional>
no result

정상적인 기능수행 및 반환된 결과가 없는 경우

INVALID_REQUEST string <optional>
invalid request

요청 파라미터가 잘못된 경우

UNKNOWN_ERROR_IO_ERROR string <optional>
unknown error / io error

정의되지 않은 에러


<static, readonly> Status

Status 객체는 서비스의 응답 상태를 나타냅니다.

Properties
Name Type Default Description
OK number 200

요청이 성공한 상태입니다.

ERROR number 500

요청이 실패한 상태입니다.

Methods

fromAddrToCoord()

특정 주소의 좌표를 반환하는 geocode API를 호출합니다.

See

fromCoordToAddr()

특정 좌표에 해당하는 주소를 반환하는 reversegeocode API를 호출합니다.

See

geocode(options, callback)

특정 주소의 좌표를 반환하는 geocode API를 호출합니다.

Parameters
Name Type Description
options ServiceOptions

서버 API 호출 시 전달할 옵션

Properties
Name Type Description
query string

주소 검색을 위한 주소

coordinate string

검색 중심 좌표. lon,lat 형식

filter string

검색 결과 필터링 조건. ’필터 타입@코드1;코드2;… ’ 형식 예) HCODE@4113554500;4113555000 - HCODE: 행정동 코드 - BCODE: 법정동 코드

page number

페이지 번호

count number

결과 목록 크기

callback function

결과 반환 시 실행할 콜백 함수

Properties
Name Type Argument Description
status naver.maps.Service.Status

응답 결과에 대한 상태 코드

response GeocodeResponse <optional>

응답 본문

reverseGeocode(options, callback)

특정 좌표에 해당하는 주소를 반환하는 reversegeocode API를 호출합니다.

Parameters
Name Type Description
options ServiceOptions

서버 API 호출 시 전달할 옵션

Properties
Name Type Description
coords string | Coord | CoordLiteral

주소 검색을 위한 입력 좌표

sourcecrs string

입력 좌표계 코드

targetcrs string

출력 좌표계 코드

orders string

변환 작업 이름

callback function

결과 반환 시 실행할 콜백 함수

Properties
Name Type Argument Description
status naver.maps.Service.Status

응답 결과의 상태 코드

response ReverseGeocodeResponse <optional>

응답 본문

Type Definitions


Addition0

Addition0은 추가정보 나타냅니다. 지번 주소인 경우 reserved, 도로명 주소인 경우 건물정보

Type:
Properties
Name Type Description
type string

도로명 주소이고 건물정보가 있는경우 ‘building’

value string

도로명 주소이고 건물정보가 있는경우 건물명


Addition1

Addition1은 추가정보 나타냅니다. 지번 주소인 경우 reserved, 도로명 주소인 경우 우편번호

Type:
Properties
Name Type Description
type string

도로명 주소이고 우편번호정보가 있는경우 ‘zipcode’

value string

도로명 주소이고 우편번호정보가 있는경우 우편번호


Addition2

Addition2은 추가정보 나타냅니다. 지번 주소인 경우 reserved, 도로명 주소인 경우 도로코드

Type:
Properties
Name Type Description
type string

도로명 주소일경우 ‘roadGroupCode’

value string

도로명 주소일경우 도로코드(12자리 road group code)


Addition3

Addition3 reserved

Type:

Addition4

Addition4 reserved

Type:

AddressItem

AddressItem은 특정 주소의 정보를 나타냅니다. (deprecated)

Type:
Properties
Name Type Description
address string

개별 주소의 전체 텍스트

addrdetail object

개별 주소의 상세 정보

Properties
Name Type Description
country string

개별 주소의 국가명

sido string

개별 주소가 속한 특별시/광역시/도에 해당되는 정보

sigugun string

개별 주소가 속한 일반시/구/군/면 해당되는 정보

dongmyun string

개별 주소가 속한 동/면/리에 해당되는 정보

rest string

지번 주소 또는 도로명과 같은 개별 주소의 나머지 정보

isRoadAddress boolean

해당 주소가 도로명 주소인지 여부

point PointObjectLiteral

개별 주소의 좌표


AddressItemV2

AddressItemV2은 주소 검색 결과를 나타냅니다.

Type:
Properties
Name Type Description
roadAddress string

도로명 주소

jibunAddress string

지번 주소

englishAddress string

영어 주소

addressElements array

주소를 이루는 요소들

x string

x 좌표(경도)

y string

y 좌표(위도)

distance string

검색 중심 좌표로부터의 거리(단위: 미터)


Area0

Area0은 국가 정보를 나타냅니다.

Type:
Properties
Name Type Description
name string

국가 코드 최상위 도메인 두 자리

coords Coords

행정 구역과 관련된 좌표


Area1

Area1은 행정 구역 단위 명칭 1 정보 나타냅니다.

Type:
Properties
Name Type Description
name string

대한민국인 경우 행정안전부에서 공시된 시/도 명칭

coords Coords

행정 구역과 관련된 좌표


Area2

Area2은 행정 구역 단위 명칭 2 정보 나타냅니다.

Type:
Properties
Name Type Description
name string

대한민국인 경우 행정안전부에서 공시된 시/군/구 명칭

coords Coords

행정 구역과 관련된 좌표


Area3

Area3은 행정 구역 단위 명칭 3 정보 나타냅니다.

Type:
Properties
Name Type Description
name string

대한민국인 경우 행정안전부에서 공시된 읍/면/동 명칭

coords Coords

행정 구역과 관련된 좌표


Area4

Area4은 행정 구역 단위 명칭 4 정보 나타냅니다.

Type:
Properties
Name Type Description
name string

대한민국인 경우 행정안전부에서 공시된 리 명칭

coords Coords

행정 구역과 관련된 좌표


Coords

Coords은 행정 구역과 관련된 좌표를 나타냅니다.

Type:
Properties
Name Type Description
center object

행정 구역의 중심 좌표

Properties
Name Type Description
crs string

좌표계 코드

x string

x축 좌표, 예) 경위도(epsg:4326)인 경우 위도(longitude)

y string

y축 좌표, 예) 경위도(epsg:4326)인 경우 경도(latitude)


GeocodeResponse

GeocodeResponse는 특정 주소의 좌표를 반환하는 geocode API의 응답 형태입니다.

Type:
Properties
Name Type Description
result object

기존 응답 형식의 내용을 담고 있는 컨테이너. (deprecated)

Properties
Name Type Description
userquery string

API에 질의한 주소

total number

사용자가 질의한 주소에 해당되는 좌표의 결과 수

items Array.<naver.maps.Service~AddressItem>

좌표 목록의 배열

v2 object

API의 응답 내용을 담고 있는 컨테이너.

Properties
Name Type Description
status naver.maps.Service.GeocodeStatus

검색 결과 상태 코드

meta Meta

응답 정보

addresses Array.<naver.maps.Service~AddressItemV2>

주소 검색 결과 목록

errorMessage string

예외 발생 시 메시지

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

Land

Land는 상세주소 정보 나타냅니다.

Type:
Properties
Name Type Description
type string

지번주소의 경우 지적 타입, 예) 대한민국 지번 주소인 경우 1: 일반토지, 2: 산, 도로명주소의 경우 reserved

name string

상세 명칭, 예) 대한민국 지번 주소인 경우 reserved, 대한민국 도로명 주소인 경우 도로명

number1 string

상세 번호 1, 예) 대한민국 지번 주소인 경우 토지 본번호, 대한민국 도로명 주소인 경우 상세주소

number2 string

상세 번호 2, 예) 대한민국 지번 주소인 경우 토지 부번호, 대한민국 도로명 주소인 경우 reserved

coords Coords

지적 구역에 관계된 좌표 (reserved)


Meta

Meta는 응답 정보를 나타냅니다.

Type:
Properties
Name Type Description
totalCount number

총 검색 건수

page number

현재 페이지 번호

count number

페이지 내 결과 개수


Region

Region은 지역 명칭 정보을 나타냅니다.

Type:
Properties
Name Type Description
area0 Area0

국가 정보

area1 Area1

시/도 정보

area2 Area2

시/군/구 정보

area3 Area3

읍/면/동 정보

area4 Area4

리 정보

land Land

상세주소 정보

addition0 Addition0

추가정보

addition1 Addition1

추가정보

addition2 Addition2

추가정보

addition3 Addition3

reserved

addition4 Addition4

reserved


ResultItem

ResultItem은 ReverseGeocode 응답 결과를 나타냅니다.

Type:
Properties
Name Type Description
name string

변환 작업 이름

code object

코드 정보

Properties
Name Type Description
id string

코드값

type string

코드 타입, 예) L: 법정동, A: 행정동, S: 동일법정동 이름 존재하는 행정동

mappingId string

id와 관련된 매핑 코드, 예) 법정 코드의 매핑된 네이버 동 코드 또는 행정 코드의 매핑된 네이버 동 코드

region Region

지역 명칭 정보.


ReverseGeocodeAddress

ReverseGeocodeAddress은 ReverseGeocodeResponse 응답 값으로 만든 주소입니다.

Type:
Properties
Name Type Description
roadAddress string

도로명 주소 (서버 응답 결과에 따라 지번 주소만 있을 수 있음)

jibunAddress string

지번 주소 (서버 응답 결과에 따라 도로명 주소만 있을 수 있음)


ReverseGeocodeResponse

ReverseGeocodeResponse는 특정 좌표에 해당하는 주소를 반환하는 reversegeocode API의 응답 형태입니다.

Type:
Properties
Name Type Description
result object

기존 응답 형식의 내용을 담고 있는 컨테이너. (deprecated)

Properties
Name Type Description
userquery string

API에 질의한 좌표

total number

사용자가 질의한 좌표에 해당되는 주소의 결과 수

items Array.<naver.maps.Service~AddressItem>

주소 목록의 배열

v2 object

API의 응답 내용을 담고 있는 컨테이너.

Properties
Name Type Description
status ReverseGeocodeStatus

응답 상태

results Array.<naver.maps.Service~ResultItem>

주소 목록의 배열

address ReverseGeocodeAddress

주소 결과

Example
{
  "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
        }
      }
    ]
  },
  "v2": {
    "status":{
      "code":0,
      "name":"ok",
      "message":"done"
    },
    "results":[
      {
        "name":"legalcode",
        "code":{
          "id":"2641010100",
          "type":"L",
          "mappingId":"08410101"
        },
        "region":{
          "area0":{
            "name":"kr",
            "coords":{
              "center":{
                "crs":"",
                "x":0.0,
                "y":0.0
              }
            }
          },
          "area1":{
            "name":"부산광역시",
            "coords":{
              "center":{
                "crs":"EPSG:4326",
                "x":129.0750222,
                "y":35.1798159
              }
            }
          },
          "area2":{
            "name":"금정구",
            "coords":{
              "center":{
                "crs":"EPSG:4326",
                "x":129.0921,
                "y":35.243068
              }
            }
          },
          "area3":{
            "name":"두구동",
            "coords":{
              "center":{
                "crs":"EPSG:4326",
                "x":129.1133567,
                "y":35.2982641
              }
            }
          },
          "area4":{
            "name":"",
            "coords":{
              "center":{
                "crs":"",
                "x":0.0,
                "y":0.0
              }
            }
          }
        }
      }
    ],
    address: {
      jibunAddress: "경기도 성남시 분당구 정자동 178-1",
      roadAddress: "경기도 성남시 분당구 불정로 6 NAVER그린팩토리"
    }
  }
}

ReverseGeocodeStatus

ReverseGeocodeStatus은 ReverseGeocode 응답 상태를 나타냅니다.

Type:
Properties
Name Type Description
code naver.maps.Service.ReverseGeocodeStatusCode

응답 상태 코드

name naver.maps.Service.ReverseGeocodeStatusName

응답 상태 이름

message string

응답 상태 설명


ServiceOptions

ServiceOptions는 서버 API 호출 시 전달하기 위한 옵션을 나타냅니다.

Type:
Properties
Name Type Argument Default Description
sourcecrs naver.maps.Service.CoordinatesType <optional>
epsg:4326

입력 좌표계 코드

targetcrs naver.maps.Service.CoordinatesType <optional>
epsg:4326

출력 좌표계 코드

orders naver.maps.Service.OrderType <optional>
legalcode,admcode

변환 작업 이름