--- title: "gc" slug: "ai-naver-mapsreversegeocoding-gc" tags: ["Reverse Geocoding", "Maps"] updated: 2026-09-17T09:10:00Z published: 2026-09-17T09:10:00Z canonical: "api-fin.ncloud-docs.com/ai-naver-mapsreversegeocoding-gc" --- > ## Documentation Index > Fetch the complete documentation index at: https://api-fin.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # gc ## 개요 네이버 지도에서는 좌표를 주소를 변환(coordsToAddr)하는 Reverse geocoding 서비스를 제공합니다. Reverse geocoding API를 이용해 특정 좌표에 해당하는 국내 법정동/행정동/지번주소/도로명주소 정보를 얻을 수 있습니다. Reverse geocoding 서비스는 EPSG(European Petroleum Survey Group)에서 지정한 일부 좌표 체계와 국내에서 주로 사용하는 좌표 체계를 지원합니다. ## 요청 ``` curl "https://naveropenapi.apigw-pub.fin-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) 지원되는 좌표계 코드는 [좌표 체계](/docs/ai-naver-mapsreversegeocoding-gc#%EC%A2%8C%ED%91%9C-%EC%B2%B4%EA%B3%84) 참고 바람 예) sourcecrs=epsg:4326 (위경도 좌표계) sourcecrs=nhn:2048 (utm-k 좌표계) sourcecrs=nhn:128 (katech 좌표계) sourcecrs=epsg:3857 (구글 좌표계) | | targetcrs | string | N | - 출력 좌표계 코드 default값(기본값)은 위경도 좌표계(epsg:4326) 지원되는 좌표계 코드는 [좌표 체계](/docs/ai-naver-mapsreversegeocoding-gc#%EC%A2%8C%ED%91%9C%EC%B2%B4%EA%B3%84) 참고 바람 예) 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](http://en.wikipedia.org/wiki/CcTLD) 참고 바람 | | region.area0.coords.center | | 행정 구역의 중심 좌표 | | region.area0.coords.center.crs | string | - 좌표계 코드 지원되는 좌표계 코드는 [좌표 체계](/docs/ai-naver-mapsreversegeocoding-gc#%EC%A2%8C%ED%91%9C%EC%B2%B4%EA%B3%84) 참고 바람 | | 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 | - 좌표계 코드 지원되는 좌표계 코드는 [좌표 체계](/docs/ai-naver-mapsreversegeocoding-gc#%EC%A2%8C%ED%91%9C%EC%B2%B4%EA%B3%84)를 참고하세요. | | 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 | - 좌표계 코드 지원되는 좌표계 코드는 [좌표 체계](/docs/ai-naver-mapsreversegeocoding-gc#%EC%A2%8C%ED%91%9C%EC%B2%B4%EA%B3%84) 참고 바람 | | 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 | - 좌표계 코드 지원되는 좌표계 코드는 [좌표 체계](/docs/ai-naver-mapsreversegeocoding-gc#%EC%A2%8C%ED%91%9C%EC%B2%B4%EA%B3%84) 참고 바람 | | 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 | - 좌표계 코드 지원되는 좌표계 코드는 [좌표 체계](/docs/ai-naver-mapsreversegeocoding-gc#%EC%A2%8C%ED%91%9C%EC%B2%B4%EA%B3%84) 참고 바람 | | 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-pub.fin-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-pub.fin-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-pub.fin-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-pub.fin-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-pub.fin-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-pub.fin-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-pub.fin-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-pub.fin-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-pub.fin-ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=legalcode` - 좌표를 지번 주소, 행정 코드로 변환 요청 `https://naveropenapi.apigw-pub.fin-ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=addr,admcode` - 좌표를 지번 주소, 행정 코드, 도로명 주소로 변환 요청 `https://naveropenapi.apigw-pub.fin-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 | 정의되지 않은 오류 |