gc

개요

네이버 지도에서는 좌표를 주소를 변환(coordsToAddr)하는 Reverse geocoding 서비스를 제공합니다. Reverse geocoding API를 이용해 특정 좌표에 해당하는 국내 법정동/행정동/지번주소/도로명주소 정보를 얻을 수 있습니다.
Reverse geocoding 서비스는 EPSG(European Petroleum Survey Group)에서 지정한 일부 좌표 체계와 국내에서 주로 사용하는 좌표 체계를 지원합니다.

요청

curl "https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?coords={입력_좌표}&sourcecrs={좌표계}&orders={변환_작업_이름}&output={출력_형식}" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v

요청 파라미터

참고
  • sourcecrs, targetcrs, orders, output 파라미터의 경우 해당 파라미터 입력이 되지 않으면 default값(기본값)으로 호출됩니다. 각 파라미터별 default값은 다음 설명을 참고부탁드립니다.
  • default값이 아닌 값을 원할 경우 해당 파라미터를 명시적으로 호출하시면 됩니다.
  • orders 파라미터를 호출하지 않을 경우 : 법정,행정 결과 리턴
  • 상세주소를 원할 경우 : orders=legalcode,admcode,addr,roadaddr로 호출
  • (상세주소 호출에 orders 파라미터값으로 legalcode나 admcode를 추가로 넣어 호출하는 이유 : 해안선 부근, 신규택지 등 상세주소 없는 지역의 경우 API 결과로 ‘결과없음’이 아닌 법정 혹은 행정동 단위 결과까지라도 받을 수 있음)
파라미터 데이터 타입 필수 여부 설명
request string N 요청 서비스 이름.
Reverse geocoding에서는 coordsToaddr을 사용합니다.
default값(기본값)은 coordToaddr입니다.
예) request=coordsToaddr
coords string  Y 입력 좌표.
예) coords=128.12345,37.98776
sourcecrs string N 입력 좌표계 코드.
default값(기본값)은 위경도 좌표계(epsg:4326)입니다.
지원되는 좌표계 코드는 좌표 체계를 참고하세요.
예) sourcecrs=epsg:4326 (위경도 좌표계)
sourcecrs=nhn:2048 (utm-k 좌표계)
sourcecrs=nhn:128 (katech 좌표계)
sourcecrs=epsg:3857 (구글 좌표계)
targetcrs string N 출력 좌표계 코드.
default값(기본값)은 위경도 좌표계(epsg:4326)입니다.
지원되는 좌표계 코드는 좌표 체계를 참고하세요.
예) targetcrs=epsg:4326 (위경도 좌표계)
targetcrs=nhn:2048 (utm-k 좌표계)
targetcrs=nhn:128 (katech 좌표계)
targetcrs=epsg:3857 (구글 좌표계)
orders string N 변환 작업 이름.
default값(기본값)은 legalcode,admcode입니다.
사용 가능한 값은 다음과 같습니다.
- legalcode: 좌표 to 법정동
- admcode: 좌표 to 행정동
- addr: 좌표 to 지번 주소
- roadaddr: 좌표 to 도로명 주소(새주소)
여러 개의 값을 입력할 수 있으며, orders 요청순으로 결과가 표시됩니다.
예) orders=legalcode
orders=addr,admcode
orders=addr,admcode,roadaddr
orders=legalcode,addr,admcode,roadaddr
output string N 출력 형식.
사용 가능한 값은 json, xml입니다.
default값(기본값)은 xml입니다.
예) output=json
output=xml
callback string N jsonp 통신을 위해 콜백처리가 필요한 경우 넘겨줄 콜백이름
output=json일 경우에만 해당됨
callback에서 지정한 이름으로 json 데이터를 감싸서 반환합니다.
예) callback=abc

좌표 체계

이름 코드 연동 서비스 구분 GCS 정보           PCS 정보             비고
구글맵 EPSG:3857   PCS WGS_1984 WGS_1984 6378137 (Semi_Minor) 298.2572236 Greenwich Degree M 0 0 0 0 Meter 1  
WGS 84 경위도 EPSG:4326   GCS WGS_1984 WGS_1984 6378137 298.2572236 Greenwich Degree 해당없음 해당없음 해당없음 해당없음 해당없음 해당없음 해당없음  
UTM-K NHN:2048   PCS D_ITRF_2000 GRS_1980 6378137 298.2572221 Greenwich Degree TM 127.5 38 2,000,000 1,000,000 Meter 0.9996  
KATECH(TM128) NHN:128 매쉬업맵, 백과사전, 웹 OpenAPI PCS D_Korean_Datum_1985 Bessel 1841 6377397.155 299.1528128 Greenwich Degree TM 128 38 600,000 400,000 Meter 0.9999 타원체 변환계수 10개 : TRANSFORM”BADEKAS”,“-145.907,505.034,685.756,-1.162,2.347,1.592,6.342,-3159521.31,4068151.32,3748113.85”

요청 헤더

헤더명 설명
X-NCP-APIGW-API-KEY-ID 앱 등록 시 발급받은 Client ID
X-NCP-APIGW-API-KEY-ID:{Client ID}
X-NCP-APIGW-API-KEY 앱 등록 시 발급 받은 Client Secret
X-NCP-APIGW-API-KEY:{Client Secret}

요청 바디

  • 해당 API 는 요청 바디를 필요로 하지 않습니다.

응답

응답 바디

속성 데이터 타입 설명
name string  변환 작업 이름
code number  코드 정보
code.id string 코드값
code.type string  코드 타입.
예) L: 법정동, A: 행정동, S: 동일법정동 이름 존재하는 행정동
code.mappingId string id와 관련된 매핑 코드.
예) 법정 코드의 매핑된 네이버 동 코드 또는  행정 코드의 매핑된 네이버 동 코드
region   지역 명칭 정보.
region.area0
region.area0.name string 국가 코드 최상위 도메인 두 자리.
자세한 내용은 Country code top-level domain를 참고하세요.
region.area0.coords.center 행정 구역의 중심 좌표
region.area0.coords.center.crs string 좌표계 코드.
지원되는 좌표계 코드는 좌표 체계를 참고하세요.
region.area0.coords.center.x float x축 좌표.
예) 경위도(epsg:4326)인 경우 경도(longitude)
region.area0.coords.center.y float y축 좌표.
예) 경위도(epsg:4326)인 경우 위도(latitude)
region.area1
region.area1.name string 행정 구역 단위 명칭 1.
예) 대한민국인 경우 행정안전부에서 공시된 시/도 명칭
region.area1.coords 행정 구역과 관련된 좌표
region.area1.coords.center 행정 구역의 중심 좌표
region.area1.coords.center.crs string 좌표계 코드.
지원되는 좌표계 코드는 좌표 체계를 참고하세요.
region.area1.coords.center.x float x축 좌표.
예) 경위도(epsg:4326)인 경우 경도(longitude)
region.area1.coords.center.y float y축 좌표.
예) 경위도(epsg:4326)인 경우 위도(latitude)
region.area2
region.area2.name string 행정 구역 단위 명칭 2.
예) 대한민국인 경우 행정안전부에서 공시된 시/군/구 명칭
region.area2.coords 행정 구역과 관련된 좌표
region.area2.coords.center 행정 구역의 중심 좌표
region.area2.coords.center.crs string 좌표계 코드.
지원되는 좌표계 코드는 좌표 체계를 참고하세요.
region.area2.coords.center.x float x축 좌표.
예) 경위도(epsg:4326)인 경우 경도(longitude)
region.area2.coords.center.y float y축 좌표.
예) 경위도(epsg:4326)인 경우 위도(latitude)
region.area3
region.area3.name string 행정 구역 단위 명칭 3.
예) 대한민국인 경우 행정안전부에서 공시된 읍/면/동 명칭
region.area3.coords 행정 구역과 관련된 좌표
region.area3.coords.center 행정 구역의 중심 좌표
region.area3.coords.center.crs string 좌표계 코드.
지원되는 좌표계 코드는 좌표 체계를 참고하세요.
region.area3.coords.center.x float x축 좌표.
예) 경위도(epsg:4326)인 경우 경도(longitude)
region.area3.coords.center.y float y축 좌표.
예) 경위도(epsg:4326)인 경우 위도(latitude)
region.area4
region.area4.name string 행정 구역 단위 명칭 4.
예) 대한민국인 경우 행정안전부에서 공시된 리 명칭)
region.area4.coords 행정 구역과 관련된 좌표
region.area4.coords.center 행정 구역의 중심 좌표
region.area4.coords.center.crs string 좌표계 코드.
지원되는 좌표계 코드는 좌표 체계를 참고하세요.
region.area4.coords.center.x float x축 좌표.
예) 경위도(epsg:4326)인 경우 경도(longitude)
region.area4.coords.center.y float y축 좌표.
예) 경위도(epsg:4326)인 경우 위도(latitude)
land   상세주소 정보  
land.type string  지번주소의 경우 지적 타입.
예) 대한민국 지번 주소인 경우 1: 일반토지, 2: 산  
도로명주소의 경우 reserved
land.name string  상세 명칭.
예) 대한민국 지번 주소인 경우 reserved
대한민국 도로명 주소인 경우 도로명
land.number1  string 상세 번호 1.
예) 대한민국 지번 주소인 경우 토지 본번호
대한민국 도로명 주소인 경우 상세주소 
land.number2 string 상세 번호 2.
예) 대한민국 지번 주소인 경우 토지 부번호
대한민국 도로명 주소인 경우 reserved
land.coords 지적 구역에 관계된 좌표 (reserved)
addition0   추가정보
지번 주소인 경우 reserved
도로명 주소인 경우 건물정보
addition0.type  string 도로명 주소이고 건물정보가 있는경우 ‘building’
addition0.value  string 도로명 주소이고 건물정보가 있는경우 건물명
addition1   추가정보
지번 주소인 경우 reserved
도로명 주소인 경우 우편번호
addition1.type  string 도로명 주소이고 우편번호정보가 있는경우 ‘zipcode’
addition1.value  string 도로명 주소이고 우편번호정보가 있는경우 우편번호
addition2 추가정보
지번 주소인 경우 reserved
도로명 주소인 경우 도로코드
addition2.type string 도로명 주소일경우 ‘roadGroupCode’
addition2.value string 도로명 주소일경우 도로코드(12자리 road group code)
addutuib3~4 reserved

참고

변환 대상 좌표에 따라 다양한 응답 결과가 반환될 수 있습니다. 아래의 각 경우를 참고하세요.

  • 일반 읍면동
    https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=126.9913201,37.5666936&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml
    https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

  • 일반 ‘리’: 법정동 단위인 ‘읍면’ 하위의 ‘리’ 단위 좌표이므로 admcode의 결과에도 code type은 ‘L’로 설정됩니다.
    https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=128.2439084,36.4938906&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

  • 분당구 정자동: 법정동과 동일한 이름의 행정동이 존재합니다(영역은 서로 다름).
    https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=127.1114893,37.3614463&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

  • 세종시 좌표: 시군구 area2 데이터가 없고 세종시 하위의 모든 행정동의 법정동이 동일합니다(영역은 서로 다름).

    • 도담동(법행정동일명): https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=127.2654387,36.5008113&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

    • 조치원읍(법정): https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=127.2923750,36.5929071&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

  • 바다 위(데이터 없음): https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=125.9913201,37.5666936&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

예시

요청 예시

curl "https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=legalcode,admcode" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v
  • 좌표를 법정 코드로 변환 요청
    https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=legalcode
  • 좌표를 지번 주소, 행정 코드로 변환 요청
    https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=addr,admcode
  • 좌표를 지번 주소, 행정 코드, 도로명 주소로 변환 요청
    https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=addr,admcode,roadaddr

응답 예시

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

오류 코드

요청 결과가 정상이면 HTTP 상태 코드 200을 반환하며, 상세 코드는 다음과 같습니다.

code name 설명
0 ok 정상적인 기능수행 및 반환된 결과가 있는 경우
3 no results 정상적인 기능수행 및 반환된 결과가 없는 경우

요청 결과가 정상이 아니면 다음과 같이 반환됩니다.

HttpStatusCode ErrorCode ErrorMessage Description
400 100 invalid request 요청 파라미터가 잘못된 경우
500 900 unknown error / io error 정의되지 않은 오류