- 인쇄
- PDF
gc
- 인쇄
- PDF
개요
네이버 지도에서는 좌표를 주소를 변환(coordsToAddr)하는 Reverse geocoding 서비스를 제공합니다. Reverse geocoding API를 이용해 특정 좌표에 해당하는 국내 법정동/행정동/지번주소/도로명주소 정보를 얻을 수 있습니다.
Reverse geocoding 서비스는 EPSG(European Petroleum Survey Group)에서 지정한 일부 좌표 체계와 국내에서 주로 사용하는 좌표 체계를 지원합니다.
요청
curl "https://naveropenapi.apigw.gov-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 IDX-NCP-APIGW-API-KEY-ID:{Client ID} |
X-NCP-APIGW-API-KEY | 앱 등록 시 발급 받은 Client SecretX-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.gov-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.gov-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.gov-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.gov-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.gov-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.gov-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.gov-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.gov-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.gov-ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=legalcode
좌표를 지번 주소, 행정 코드로 변환 요청
https://naveropenapi.apigw.gov-ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=addr,admcode
좌표를 지번 주소, 행정 코드, 도로명 주소로 변환 요청
https://naveropenapi.apigw.gov-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 | 정의되지 않은 에러 |