gc
    • PDF

    gc

    • PDF

    Article Summary

    개요

    네이버 지도에서는 좌표를 주소를 변환(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 결과로 '결과없음'이 아닌 법정 혹은 행정동 단위 결과까지라도 받을 수 있음)
    파라미터데이터 타입필수 여부설명
    requeststringN- 요청 서비스 이름
    Reverse geocoding에서는 coordsToaddr 사용
    default값(기본값)은 coordToaddr
    예) request=coordsToaddr
    coordsstringY- 입력 좌표
    예) coords=128.12345,37.98776
    sourcecrsstringN- 입력 좌표계 코드
    default값(기본값)은 위경도 좌표계(epsg:4326)
    지원되는 좌표계 코드는 좌표 체계를 참고
    예) sourcecrs=epsg:4326 (위경도 좌표계)
    sourcecrs=nhn:2048 (utm-k 좌표계)
    sourcecrs=nhn:128 (katech 좌표계)
    sourcecrs=epsg:3857 (구글 좌표계)
    targetcrsstringN- 출력 좌표계 코드
    default값(기본값)은 위경도 좌표계(epsg:4326)
    지원되는 좌표계 코드는 좌표 체계를 참고
    예) targetcrs=epsg:4326 (위경도 좌표계)
    targetcrs=nhn:2048 (utm-k 좌표계)
    targetcrs=nhn:128 (katech 좌표계)
    targetcrs=epsg:3857 (구글 좌표계)
    ordersstringN- 변환 작업 이름
    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
    outputstringN- 출력 형식
    사용 가능한 값은 json, xml
    default값(기본값)은 xml
    예) output=json
    output=xml
    callbackstringN- jsonp 통신을 위해 콜백처리가 필요한 경우 넘겨줄 콜백이름
    output=json일 경우에만 해당됨
    callback에서 지정한 이름으로 json 데이터를 감싸서 반환
    예) callback=abc

    좌표 체계

    이름코드연동 서비스구분GCS 정보PCS 정보비고
    구글맵EPSG:3857PCSWGS_1984WGS_19846378137 (Semi_Minor)298.2572236GreenwichDegreeM0000Meter1
    WGS 84 경위도EPSG:4326GCSWGS_1984WGS_19846378137298.2572236GreenwichDegree해당없음해당없음해당없음해당없음해당없음해당없음해당없음
    UTM-KNHN:2048PCSD_ITRF_2000GRS_19806378137298.2572221GreenwichDegreeTM127.5382,000,0001,000,000Meter0.9996
    KATECH(TM128)NHN:128매쉬업맵, 백과사전, 웹 OpenAPIPCSD_Korean_Datum_1985Bessel 18416377397.155299.1528128GreenwichDegreeTM12838600,000400,000Meter0.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 는 요청 바디를 필요로 하지 않습니다.

    응답

    응답 바디

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

    참고

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

    • 일반 읍면동

      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을 반환하며, 상세 코드는 다음과 같습니다.

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

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

    HttpStatusCodeErrorCodeErrorMessageDescription
    400100invalid request요청 파라미터가 잘못된 경우
    500900unknown error / io error정의되지 않은 오류

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

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.