다크 모드
리버스 지오코딩
리버스 지오코딩(Reverse Geocoding)은 위도(latitude)와 경도(longitude) 좌표를 실제 주소나 지명으로 변환하는 기능입니다.
이 API는 여러 위치 좌표를 한 번에 처리하여 각 위치의 상세 주소와 행정동, 법정동 정보를 제공합니다. 한 번의 요청으로 최대 5건의 좌표에 대한 정보를 조회할 수 있습니다.
DANGER
Request
요청 호출 방식과 각 요청 헤더에 포함될 내용을 안내합니다. 요청이 실패할 경우 문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.
호출 방식
| Method | URL |
|---|---|
GET | https://apis-navi.kakaomobility.com/affiliate/address/v1/reverse_geocode |
요청 헤더(Header)
| Parameter | Description |
|---|---|
| Authorization | KakaoAK ${REST_API_KEY} {REST_API_KEY}: 카카오디벨로퍼스에서 발급 받은 REST API 키 |
| Content-Type | application/json |
요청 코드 예제
bash
curl --location --request GET 'http://apis-navi.kakaomobility/affiliate/address/v1/reverse_geocode?locations=35.85425241569661%2C128.54793746293046%7C37.566535%2C126.9779692%7C35.1795543%2C129.0756416%7C129.0756416%2C35.1795543%7C35.85425241569661%2C128.54793746293046&locale=ko&hbinfo=true' \
-H "Authorization: KakaoAK ${REST_API_KEY}" // 카카오디벨로퍼스에서 발급 받은 API 키 값요청에 대한 파라미터는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
locations | String | 위도/경도 좌표 입력 (최대 5개까지 입력 가능) 좌표 수만큼 ${Y좌표},${X좌표}를 |(또는 인코딩 된 문자인 %7C)로 연결하여 입력(예: " 37.5665,126.9780|35.1796,129.0756") | 필수 |
locale | String | 응답 언어 설정 다음 중 하나 • ko: 한국어• en: 영어(기본값: ko) | 선택 |
shape | Boolean | 지번 주소의 필지와 도로명 주소의 건물 형상 정보 제공 여부 • true: 형상 정보 제공• false: 형상 정보 미제공(기본값: false) | 선택 |
hbinfo | Boolean | 행법정동 정보 제공 여부 • true: 행법정동 정보 제공• false: 행법정동 정보 미제공(기본값: false) | 선택 |
Response
응답 성공 시 요청에 대한 성공 여부를 HTTP 상태 코드로, 요청 본문은 JSON 포맷으로 전달합니다.
응답 코드 예제
json
{
"trans_id": "0198ea1406797b3487f4e32431b06d9c",
"addresses": [
{
"result_code": "SUCCESS",
"result_msg": "성공",
"old": {
"name": "대구광역시 달서구 감삼동 305",
"main_no": "305",
"slave_no": "",
"san": "N"
},
"new": {
"name": "대구광역시 달서구 달구벌대로 지하 1665",
"road_name": "달구벌대로",
"building": "대구지하철2호선 감삼역",
"zone_no": "42641",
"jiha": "Y",
"main_no": "1665",
"slave_no": "",
"ent_x": 128.54734888026798,
"ent_y": 35.85421275027106
},
"hinfo": {
"type": "H",
"code": "2729056300",
"name": "죽전동",
"full_name": "대구광역시 달서구 죽전동",
"name0": "대한민국",
"code1": "2700000000",
"name1": "대구광역시",
"short_name1": "대구",
"code2": "2729000000",
"name2": "달서구",
"code3": "2729056300",
"name3": "죽전동",
"childcount": 0,
"x": 128.5407744311022,
"y": 35.85418300183227
},
"binfo": {
"type": "B",
"code": "2729011300",
"name": "감삼동",
"full_name": "대구광역시 달서구 감삼동",
"name0": "대한민국",
"code1": "2700000000",
"name1": "대구광역시",
"short_name1": "대구",
"code2": "2729000000",
"name2": "달서구",
"code3": "2729011300",
"name3": "감삼동",
"x": 128.54208999017484,
"y": 35.85001662863011
}
},
{
"result_code": "SUCCESS",
"result_msg": "성공",
"old": {
"name": "서울특별시 중구 태평로1가 31",
"main_no": "31",
"slave_no": "",
"san": "N"
},
"new": {
"name": "서울특별시 중구 세종대로 110",
"road_name": "세종대로",
"building": "서울특별시청",
"zone_no": "04524",
"jiha": "N",
"main_no": "110",
"slave_no": "",
"ent_x": 126.9777062790784,
"ent_y": 37.56620502187806
},
"hinfo": {
"type": "H",
"code": "1114055000",
"name": "명동",
"full_name": "서울특별시 중구 명동",
"name0": "대한민국",
"code1": "1100000000",
"name1": "서울특별시",
"short_name1": "서울",
"code2": "1114000000",
"name2": "중구",
"code3": "1114055000",
"name3": "명동",
"childcount": 0,
"x": 126.98607733575658,
"y": 37.56131225045804
},
"binfo": {
"type": "B",
"code": "1114010300",
"name": "태평로1가",
"full_name": "서울특별시 중구 태평로1가",
"name0": "대한민국",
"code1": "1100000000",
"name1": "서울특별시",
"short_name1": "서울",
"code2": "1114000000",
"name2": "중구",
"code3": "1114010300",
"name3": "태평로1가",
"x": 126.97728421482302,
"y": 37.56756438574504
}
},
{
"result_code": "SUCCESS",
"result_msg": "성공",
"old": {
"name": "부산광역시 연제구 연산동 1000",
"main_no": "1000",
"slave_no": "",
"san": "N"
},
"new": {
"name": "부산광역시 연제구 중앙대로 1001",
"road_name": "중앙대로",
"building": "부산광역시청, 부산광역시의회",
"zone_no": "47545",
"jiha": "N",
"main_no": "1001",
"slave_no": "",
"ent_x": 129.0756227110175,
"ent_y": 35.179099267935605
},
"hinfo": {
"type": "H",
"code": "2647069000",
"name": "연산제5동",
"full_name": "부산광역시 연제구 연산제5동",
"name0": "대한민국",
"code1": "2600000000",
"name1": "부산광역시",
"short_name1": "부산",
"code2": "2647000000",
"name2": "연제구",
"code3": "2647069000",
"name3": "연산제5동",
"childcount": 0,
"x": 129.07877257737533,
"y": 35.184613522809194
},
"binfo": {
"type": "B",
"code": "2647010200",
"name": "연산동",
"full_name": "부산광역시 연제구 연산동",
"name0": "대한민국",
"code1": "2600000000",
"name1": "부산광역시",
"short_name1": "부산",
"code2": "2647000000",
"name2": "연제구",
"code3": "2647010200",
"name3": "연산동",
"x": 129.08672826060786,
"y": 35.17572167323599
}
},
{
"result_code": "INVALID_LAT_LNG",
"result_msg": "입력한 위도/경도 값이 올바르지 않습니다."
},
{
"result_code": "SUCCESS",
"result_msg": "성공",
"old": {
"name": "대구광역시 달서구 감삼동 305",
"main_no": "305",
"slave_no": "",
"san": "N"
},
"new": {
"name": "대구광역시 달서구 달구벌대로 지하 1665",
"road_name": "달구벌대로",
"building": "대구지하철2호선 감삼역",
"zone_no": "42641",
"jiha": "Y",
"main_no": "1665",
"slave_no": "",
"ent_x": 128.54734888026798,
"ent_y": 35.85421275027106
},
"hinfo": {
"type": "H",
"code": "2729056300",
"name": "죽전동",
"full_name": "대구광역시 달서구 죽전동",
"name0": "대한민국",
"code1": "2700000000",
"name1": "대구광역시",
"short_name1": "대구",
"code2": "2729000000",
"name2": "달서구",
"code3": "2729056300",
"name3": "죽전동",
"childcount": 0,
"x": 128.5407744311022,
"y": 35.85418300183227
},
"binfo": {
"type": "B",
"code": "2729011300",
"name": "감삼동",
"full_name": "대구광역시 달서구 감삼동",
"name0": "대한민국",
"code1": "2700000000",
"name1": "대구광역시",
"short_name1": "대구",
"code2": "2729000000",
"name2": "달서구",
"code3": "2729011300",
"name3": "감삼동",
"x": 128.54208999017484,
"y": 35.85001662863011
}
}
]
}요청 응답에 대한 객체 정보는 다음과 같습니다.
| Name | Type | Description |
|---|---|---|
trans_id | String | 주소 변환 요청 ID |
addresses | Object[] | 주소 정보 입력 좌표 개수만큼 순서대로 결과 반환 |
result_code | String | 결과 코드 |
result_msg | String | 결과 메시지 |
old | Object | 지번 주소 정보 |
name | String | 전체 지번 주소 |
main_no | String | 지번 주번지 |
slave_no | String | 지번 부번지, 없을 경우 빈 문자열("") 반환 |
san | String | 산 여부, Y 또는 N |
shape | Object[] | 지번 형상 정보 |
exterior | Object[] | 형상 외형을 구성하는 좌표 리스트 |
x | Double | 경도 |
y | Double | 위도 |
interior | Object[] | 형상 내부의 홀 N개를 나타내는 좌표 리스트 N개 배열 |
x | Double | 경도 |
y | Double | 위도 |
new | Object | 도로명 주소 정보 |
name | String | 전체 도로명 주소 |
road_name | String | 도로명 |
building | String | 건물 이름 |
zone_no | String | 우편번호(5자리) |
jiha | String | 지하 여부, Y 또는 N |
main_no | String | 건물 본번 |
slave_no | String | 건물 부번, 없을 경우 빈 문자열("") 반환 |
ent_x | Double | 건물/건물군의 주출입구 경도(x) 좌표 |
ent_y | Double | 건물/건물군의 주출입구 위도(y) 좌표 |
shape | Object[] | 건물 형상 정보 |
exterior | Object[] | 형상 외형을 구성하는 좌표 리스트 |
x | Double | 경도 |
y | Double | 위도 |
interior | Object[] | 형상 내부의 홀 N개를 나타내는 좌표 리스트 N개 배열 |
x | Double | 경도 |
y | Double | 위도 |
hinfo | Object | 행정동 정보 |
type | String | "H" 고정 (행정동 구분자) |
code | String | 행정동 코드 |
name | String | 행정동 명칭 |
full_name | String | 행정동 전체 명칭 |
name0 | String | 국가 레벨 명칭 |
code1 | String | 시도 코드 |
name1 | String | 시도 명칭 |
short_name1 | String | 시도 축약 명칭 |
code2 | String | 시군구 코드 |
name2 | String | 시군구 명칭 |
code3 | String | 행정동(읍면동) 코드 |
name3 | String | 행정동(읍면동) 명칭 |
childcount | Integer | 하위 행정구역 개수 |
x | Double | 행정동 폴리곤 내부 중심점 경도(x) |
y | Double | 행정동 폴리곤 내부 중심점 위도(y) |
binfo | Object | 법정동 정보 |
type | String | "B" 고정 (법정동 구분자) |
code | String | 법정동 코드 |
name | String | 법정동 명칭 |
full_name | String | 법정동 전체 명칭 |
name0 | String | 국가 레벨 명칭 |
code1 | String | 시도 코드 |
name1 | String | 시도 명칭 |
short_name1 | String | 시도 축약 명칭 |
code2 | String | 시군구 코드 |
name2 | String | 시군구 명칭 |
code3 | String | 법정동(읍면동) 코드 |
name3 | String | 법정동(읍면동) 명칭 |
code4 | String | 리 코드 |
name4 | String | 리 명칭 |
x | Double | 법정동 폴리곤 내부 중심점 경도(x) |
y | Double | 법정동 폴리곤 내부 중심점 위도(y) |