gc
  • PDF

gc

  • PDF

개요

네이버 지도에서는 좌표를 주소를 변환(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 정의되지 않은 오류

이 문서가 도움이 되었습니까?

What's Next