카카오 - Rest API 개발가이드(로컬)

카카오맵에 올라가는 데이터와 관련된 API 입니다. 주소를 좌표로 변환하거나 좌표를 주소로 변환, 특정 지역에서 키워드나 카테고리로 장소 검색이 가능합니다.

현재 제공되는 로컬 API는 다음과 같습니다.

• 주소 검색
• 좌표 → 행정구역정보 변환
• 좌표 → 주소 변환
• 좌표계 변환
• 키워드로 장소 검색
• 카테고리로 장소 검색

 

주소 검색Copy URL

주소를 지도 위에 정확하게 표시하기 위해 해당 주소의 좌표 정보를 제공합니다. 주소 유형에 구분없이 변환할 수 있으며, 주소에 해당하는 지번 주소, 도로명 주소, 좌표, 우편번호, 빌딩명 등의 다양한 정보를 함께 제공하여 다양하게 활용할 수 있습니다.

[Request]

GET /v2/local/search/address.{format} HTTP/1.1 Host: dapi.kakao.com Authorization: KakaoAK {app_key}

앱키를 헤더에 담아 GET으로 요청합니다. 원하는 검색어와 함께 결과 형식 파라미터의 값을 선택적으로 추가할 수 있습니다.

키설명필수타입

query	검색을 원하는 질의어	O	String
page	결과 페이지 번호	X(기본 1)	Integer
size	한 페이지에 보여질 문서의 개수	X(기본 10)	1-30 사이 Integer

예를 들면,

curl -v -X GET "https://dapi.kakao.com/v2/local/search/address.json" \ --data-urlencode "query=전북 삼성동 100" \ -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

응답 바디는 JSON 객체로 meta와 documents로 구성됩니다.

meta

키설명타입

total_count	검색어에 검색된 문서수	Integer
pageable_count	total_count 중에 노출가능 문서수	Integer
is_end	현재 페이지가 마지막 페이지인지 여부. 값이 false이면 page를 증가시켜 다음 페이지를 요청할 수 있음.	Boolean

document

키설명타입

address_name	전체 지번 주소 또는 전체 도로명 주소. (input에 따라 결정됨)	String
address_type	address_name의 값의 type. 지명, 도로명, 지번주소, 도로명주소 여부	REGION or ROAD or REGION_ADDR or ROAD_ADDR
x	X 좌표값 혹은 longitude	String
y	Y 좌표값 혹은 latitude	String
address	지번주소 상세 정보	아래 address output 참조
road_address	도로명주소 상세 정보	아래 road_address output 참조

address

키설명타입

address_name	전체 지번 주소	String
region_1depth_name	지역 1Depth명 - 시도 단위	String
region_2depth_name	지역 2Depth명 - 구 단위	String
region_3depth_name	지역 3Depth명 - 동 단위	String
region_3depth_h_name	지역 3Depth 행정동 명칭	String
h_code	행정 코드	String
b_code	법정 코드	String
mountain_yn	산 여부	String
main_address_no	지번 주 번지	String
sub_address_no	지번 부 번지. 없을 경우 ""	String
zip_code	우편번호 (6자리)	String
x	X 좌표값 혹은 longitude	String
y	Y 좌표값 혹은 latitude	String

road_address

키설명타입

address_name	전체 도로명 주소	String
region_1depth_name	지역명1	String
region_2depth_name	지역명2	String
region_3depth_name	지역명3	String
road_name	도로명	String
underground_yn	지하 여부	Y or N
main_building_no	건물 본번	String
sub_building_no	건물 부번. 없을 경우 ""	String
building_name	건물 이름	String
zone_no	우편번호(5자리)	String
x	X 좌표값 혹은 longitude	String
y	Y 좌표값 혹은 latitude	String

예를 들면,

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "meta": { "total_count": 4, "pageable_count": 4, "is_end": true }, "documents": [ { "address_name": "전북 익산시 부송동 100", "y": "35.97664845766847", "x": "126.99597295767953", "address_type": "REGION_ADDR", "address": { "address_name": "전북 익산시 부송동 100", "region_1depth_name": "전북", "region_2depth_name": "익산시", "region_3depth_name": "부송동", "region_3depth_h_name": "삼성동", "h_code": "4514069000", "b_code": "4514013400", "mountain_yn": "N", "main_address_no": "100", "sub_address_no": "", "zip_code": "570972", "x": "126.99597295767953", "y": "35.97664845766847" }, "road_address": { "address_name": "전북 익산시 망산길 11-17", "region_1depth_name": "전북", "region_2depth_name": "익산시", "region_3depth_name": "부송동", "road_name": "망산길", "underground_yn": "N", "main_building_no": "11", "sub_building_no": "17", "building_name": "", "zone_no": "54547", "y": "35.976749396987046", "x": "126.99599512792346" } }, ... ] }

 

좌표 -> 행정구역정보 변환Copy URL

다양한 좌표계에 대한 좌표값을 받아 해당 좌표에 부합되는 행정동, 법정동을 얻는 API로 대략적인 지역 정보를 제공하여 해당 위치에 맞는 다른 서비스(맛집, 날씨 등등)를 연계하는데 활용이 가능합니다.

[Request]

GET /v2/local/geo/coord2regioncode.{format} HTTP/1.1 Host: dapi.kakao.com Authorization: KakaoAK {app_key}

앱키를 헤더에 담아 GET으로 요청합니다. 원하는 좌표와 함께 좌표체계 파라미터의 값을 선택적으로 추가할 수 있습니다.

키설명필수타입

x	x 좌표로 경위도인 경우 longitude	O	String
y	y 좌표로 경위도인 경우 latitude	O	String
input_coord	x, y 로 입력되는 값에 대한 좌표 체계	X(기본 WGS84)	WGS84 or WCONGNAMUL or CONGNAMUL or WTM or TM
output_coord	결과에 출력될 좌표 체계	X(기본 WGS84)	WGS84 or WCONGNAMUL or CONGNAMUL or WTM or TM
lang	응답을 받을 언어를 설정. ko 나 en 중 하나를 설정	X(기본 ko)	String

예를 들면,

curl -v -X GET "https://dapi.kakao.com/v2/local/geo/coord2regioncode.json?x=127.1086228&y=37.4012191" \ -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

응답 바디는 JSON 객체로 meta와 documents로 구성됩니다.

meta

키설명타입

total_count

매칭된 문서수

Integer

document

키설명타입

region_type	지상/지하/공중 여부	H(행정동) or B(법정동)
address_name	전체 지역 명칭	String
region_1depth_name	지역 1Depth명 - 시도 단위(바다지역시 존재안함)	String
region_2depth_name	지역 2Depth명 - 구 단위(바다지역시 존재안함)	String
region_3depth_name	지역 3Depth명 - 동 단위(바다지역시 존재안함)	String
region_4depth_name	지역 4Depth명 - region_type 이 법정동이며, 리 영역인 경우만 존재	String
code	region 코드	String
x	X 좌표값 혹은 longitude	String
y	Y 좌표값 혹은 latitude	String

예를 들면,

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "meta": { "total_count": 2 }, "documents": [ { "region_type": "B", "address_name": "경기도 성남시 분당구 삼평동", "region_1depth_name": "경기도", "region_2depth_name": "성남시 분당구", "region_3depth_name": "삼평동", "region_4depth_name": "", "code": "4113510900", "x": 127.10459896729914, "y": 37.40269721785548 }, { "region_type": "H", "address_name": "경기도 성남시 분당구 삼평동", "region_1depth_name": "경기도", "region_2depth_name": "성남시 분당구", "region_3depth_name": "삼평동", "region_4depth_name": "", "code": "4113565500", "x": 127.1163593869371, "y": 37.40612091848614 } ] }

 

좌표 -> 주소 변환Copy URL

좌표 정보를 통해서 해당 좌표의 구주소와 도로명 주소 정보를 표출하는 API 입니다. ()도로명주소 정보는 좌표에 따라서 표출되지 않을수 있습니다.

[Request]

GET /v2/local/geo/coord2address.{format} HTTP/1.1 Host: dapi.kakao.com Authorization: KakaoAK {app_key}

앱키를 헤더에 담아 GET으로 요청합니다. 원하는 좌표와 함께 좌표체계 파라미터의 값을 선택적으로 추가할 수 있습니다.

키설명필수타입

x	x 좌표로 경위도인 경우 longitude	O	String
y	y 좌표로 경위도인 경우 latitude	O	String
input_coord	x, y 로 입력되는 값에 대한 좌표 체계	X(기본 WGS84)	WGS84 or WCONGNAMUL or CONGNAMUL or WTM or TM

예를 들면,

curl -v -X GET "https://dapi.kakao.com/v2/local/geo/coord2address.json?x=127.423084873712&y=37.0789561558879&input_coord=WGS84" \ -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

응답 바디는 JSON 객체로 meta와 documents로 구성됩니다.

meta

키설명타입

total_count

변환된 구(지번)주소/신주소 의 개수.

0 or 1

document

키설명타입

address	지번주소 상세 정보	아래 address output 참조
road_address	도로명주소 상세 정보	아래 road_address output 참조

address

키설명타입

address_name	전체 지번 주소	String
region_1depth_name	지역 1Depth명 - 시도 단위	String
region_2depth_name	지역 2Depth명 - 구 단위	String
region_3depth_name	지역 3Depth명 - 동 단위	String
main_address_no	지번 주 번지	String
sub_address_no	지번 부 번지. 없을 경우 ""	String
zip_code	우편번호 (6자리)	String

road_address

키설명타입

address_name	전체 도로명 주소	String
region_1depth_name	지역 1Depth명 - 시도 단위	String
region_2depth_name	지역 2Depth명 - 구 단위	String
region_3depth_name	지역 3Depth명 - 면 단위	String
road_name	도로명	String
underground_yn	지하 여부	Y or N
main_building_no	건물 본번	String
sub_building_no	건물 부번. 없을 경우 ""	String
building_name	건물 이름	String
zone_no	우편번호(5자리)	String

예를 들면,

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "meta": { "total_count": 1 }, "documents": [ { "road_address": { "address_name": "경기도 안성시 죽산면 죽산초교길 69-4", "region_1depth_name": "경기", "region_2depth_name": "안성시", "region_3depth_name": "죽산면", "road_name": "죽산초교길", "underground_yn": "N", "main_building_no": "69", "sub_building_no": "4", "building_name": "무지개아파트", "zone_no": "17519" }, "address": { "address_name": "경기 안성시 죽산면 죽산리 343-1", "region_1depth_name": "경기", "region_2depth_name": "안성시", "region_3depth_name": "죽산면 죽산리", "mountain_yn": "N", "main_address_no": "343", "sub_address_no": "1", "zip_code": "456894" } } ] }

 

좌표계 변환Copy URL

x, y 값과 입력/출력 좌표계를 지정하여 변환된 좌표값을 얻을 수 있습니다. 가지고 있는 contents 의 좌표값을 새로운 좌표계의 값으로 변경하여 서로 다른 좌표계간 데이터 호환이 가능하도록 하는데 사용 가능합니다.

[Request]

GET /v2/local/geo/transcoord.{format} HTTP/1.1 Host: dapi.kakao.com Authorization: KakaoAK {app_key}

앱키를 헤더에 담아 GET으로 요청합니다. 원하는 좌표와 함께 좌표체계 파라미터의 값을 선택적으로 추가할 수 있습니다.

키설명필수타입

x	x 좌표로 경위도인 경우 longitude	O	String
y	y 좌표로 경위도인 경우 latitude	O	String
input_coord	x, y 로 입력되는 값에 대한 좌표 체계	X(기본 WGS84)	WGS84 or WCONGNAMUL or CONGNAMUL or WTM or TM or KTM or UTM or BESSEL or WKTM or WUTM
output_coord	결과에 출력될 좌표 체계	X(기본 WGS84)	WGS84 or WCONGNAMUL or CONGNAMUL or WTM or TM or KTM or UTM or BESSEL or WKTM or WUTM

예를 들면,

curl -v -X GET "https://dapi.kakao.com/v2/local/geo/transcoord.json?x=160710.37729270622&y=-4388.879299157299&input_coord=WTM&output_coord=WGS84" \ -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

응답 바디는 JSON 객체로 meta와 documents로 구성됩니다.

meta

키설명타입

total_count

매칭된 문서수

Integer

document

키설명타입

x	x 좌표로 경위도인 경우 longitude	String
y	y 좌표로 경위도인 경우 latitude	String

예를 들면,

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "meta": { "total_count": 1 }, "documents": [ { "x": 126.57740680000002, "y": 33.453357700000005 } ] }

 

키워드로 장소 검색Copy URL

질의어에 매칭된 장소 검색 결과를 지정된 정렬 기준에 따라 제공합니다. 현재 위치 좌표, 반경 제한, 정렬 옵션, 페이징 등의 기능을 통해 원하는 결과를 요청 할 수 있습니다. 각 장소는 이름, 주소, 좌표, 카테고리 등의 기본 정보와 다양한 부가정보, 다음 지도의 장소 상세 페이지로 연결되는 URL 정보도 제공됩니다.

[Request]

GET /v2/local/search/keyword.{format} HTTP/1.1 Host: dapi.kakao.com Authorization: KakaoAK {app_key}

앱키를 헤더에 담아 GET으로 요청합니다. 원하는 검색어와 함께 결과 형식 파라미터의 값을 선택적으로 추가할 수 있습니다.

키설명필수타입

query	검색을 원하는 질의어	O	String
category_group_code	카테고리 그룹 코드. 결과를 카테고리로 필터링을 원하는 경우 사용.	X	아래 category_group_code 테이블 참고
x	중심 좌표의 X값 혹은 longitude. 특정 지역을 중심으로 검색하려고 할 경우 radius와 함께 사용 가능.	X	String
y	중심 좌표의 Y값 혹은 latitude. 특정 지역을 중심으로 검색하려고 할 경우 radius와 함께 사용 가능.	X	String
radius	중심 좌표부터의 반경거리. 특정 지역을 중심으로 검색하려고 할 경우 중심좌표로 쓰일 x,y와 함께 사용. 단위 meter	X	0~20000 Integer
rect	사각형 범위내에서 제한 검색을 위한 좌표. 지도 화면 내 검색시 등 제한 검색에서 사용가능. 좌측X좌표,좌측Y좌표,우측X좌표,우측Y좌표 형식.	X	String
page	결과 페이지 번호	X(기본 1)	1-45 사이 Integer
size	한 페이지에 보여질 문서의 개수	X(기본 15)	1-15 사이 Integer
sort	결과 정렬 순서. distance 정렬을 워할때는 기준좌표로 쓰일 x,y와 함께 사용.	X(기본 accuracy)	distance or accuracy

category_group_code

code의미

MT1	대형마트
CS2	편의점
PS3	어린이집, 유치원
SC4	학교
AC5	학원
PK6	주차장
OL7	주유소, 충전소
SW8	지하철역
BK9	은행
CT1	문화시설
AG2	중개업소
PO3	공공기관
AT4	관광명소
AD5	숙박
FD6	음식점
CE7	카페
HP8	병원
PM9	약국

예를 들면, 서울 강남구 삼성동 20km 반경에서 카카오프렌즈 매장 검색

curl -v -X GET "https://dapi.kakao.com/v2/local/search/keyword.json?y=37.514322572335935&x=127.06283102249932&radius=20000" \ --data-urlencode "query=카카오프렌즈" \ -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

응답 바디는 JSON 객체로 meta와 documents로 구성됩니다.

meta

키설명타입

total_count	검색어에 검색된 문서수	Integer
pageable_count	total_count 중에 노출가능 문서수. 최대 45.	Integer
is_end	현재 페이지가 마지막 페이지인지 여부. 값이 false이면 page를 증가시켜 다음 페이지를 요청할 수 있음.	Boolean
same_name	질의어의 지역/키워드 분석 정보	아래 same_name output 참조

same_name

키설명타입

region	질의어에서 인식된 지역의 리스트. '중앙로 맛집' 에서 중앙로에 해당하는 지역 리스트	List of String
keyword	질의어에서 지역 정보를 제외한 키워드. '중앙로 맛집' 에서 '맛집'	String
selected_region	인식된 지역 리스트 중, 현재 검색에 사용된 지역 정보.	String

document

키설명타입

id	장소 ID	String
place_name	장소명, 업체명	String
category_name	카테고리 이름	String
category_group_code	중요 카테고리만 그룹핑한 카테고리 그룹 코드. Request에 category_group_code 테이블 참고	String
category_group_name	중요 카테고리만 그룹핑한 카테고리 그룹명. Request에 category_group_code 테이블 참고	String
phone	전화번호	String
address_name	전체 지번 주소	String
road_address_name	전체 도로명 주소	String
x	X 좌표값 혹은 longitude	String
y	Y 좌표값 혹은 latitude	String
place_url	장소 상세페이지 URL	String
distance	중심좌표까지의 거리(x,y 파라미터를 준 경우에만 존재). 단위 meter	String

예를 들면,

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "meta": { "same_name": { "region": [], "keyword": "카카오프렌즈", "selected_region": "" }, "pageable_count": 14, "total_count": 14, "is_end": true }, "documents": [ { "place_name": "카카오프렌즈 코엑스점", "distance": "418", "place_url": "http://place.map.kakao.com/26338954", "category_name": "가정,생활 > 문구,사무용품 > 디자인문구 > 카카오프렌즈", "address_name": "서울 강남구 삼성동 159", "road_address_name": "서울 강남구 영동대로 513", "id": "26338954", "phone": "02-6002-1880", "category_group_code": "", "category_group_name": "", "x": "127.05902969025047", "y": "37.51207412593136" }, ... ] }

 

카테고리로 장소 검색Copy URL

미리 정의된 그룹코드에 해당하는 장소 검색 결과를 지정된 정렬 기준에 따라 제공합니다. 현재 위치 좌표, 반경 제한, 정렬 옵션, 페이징 등의 기능을 통해 원하는 결과를 요청 할 수 있습니다. 각 장소는 이름, 주소, 좌표, 카테고리 등의 기본 정보와 다양한 부가정보, 다음 지도의 장소 상세 페이지로 연결되는 URL 정보도 제공됩니다.

[Request]

GET /v2/local/search/category.{format} HTTP/1.1 Host: dapi.kakao.com Authorization: KakaoAK {app_key}

앱키를 헤더에 담아 GET으로 요청합니다. 원하는 검색어와 함께 결과 형식 파라미터의 값을 선택적으로 추가할 수 있습니다.

키설명필수타입

category_group_code	카테고리 그룹 코드	O	아래 category_group_code 테이블 참고
x	중심 좌표의 X값 혹은 longitude. 특정 지역을 중심으로 검색하려고 할 경우 radius와 함께 사용 가능.	(x,y,radius) 또는 rect 필수	String
y	중심 좌표의 Y값 혹은 latitude. 특정 지역을 중심으로 검색하려고 할 경우 radius와 함께 사용 가능.	(x,y,radius) 또는 rect 필수	String
radius	중심 좌표부터의 반경거리. 특정 지역을 중심으로 검색하려고 할 경우 중심좌표로 쓰일 x,y와 함께 사용. 단위 meter	(x,y,radius) 또는 rect 필수	0~20000 Integer
rect	사각형 범위내에서 제한 검색을 위한 좌표. 지도 화면 내 검색시 등 제한 검색에서 사용가능. 좌측X좌표,좌측Y좌표,우측X좌표,우측Y좌표 형식.	(x,y,radius) 또는 rect 필수	String
page	결과 페이지 번호	X(기본 1)	1-45 사이 Integer
size	한 페이지에 보여질 문서의 개수	X(기본 15)	1-15 사이 Integer
sort	결과 정렬 순서. distance 정렬을 원할때는 기준좌표로 쓰일 x,y 파라미터가 필요.	X(기본 accuracy)	distance or accuracy

category_group_code

code의미

MT1	대형마트
CS2	편의점
PS3	어린이집, 유치원
SC4	학교
AC5	학원
PK6	주차장
OL7	주유소, 충전소
SW8	지하철역
BK9	은행
CT1	문화시설
AG2	중개업소
PO3	공공기관
AT4	관광명소
AD5	숙박
FD6	음식점
CE7	카페
HP8	병원
PM9	약국

예를 들면, 서울 강남구 삼성동 20km 반경에서 약국 검색

curl -v -X GET "https://dapi.kakao.com/v2/local/search/category.json?category_group_code=PM9&rect=127.0561466,37.5058277,127.0602340,37.5142554" \ -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

응답 바디는 JSON 객체로 meta와 documents로 구성됩니다.

meta

키설명타입

total_count	검색어에 검색된 문서수	Integer
pageable_count	total_count 중에 노출가능 문서수. 최대 45.	Integer
is_end	현재 페이지가 마지막 페이지인지 여부. 값이 false이면 page를 증가시켜 다음 페이지를 요청할 수 있음.	Boolean
same_name	질의어의 지역/키워드 분석 정보	아래 same_name output 참조

same_name

키설명타입

region	질의어에서 인식된 지역의 리스트. '중앙로 맛집' 에서 중앙로에 해당하는 지역 리스트	List of String
keyword	질의어에서 지역 정보를 제외한 키워드. '중앙로 맛집' 에서 '맛집'	String
selected_region	인식된 지역 리스트 중, 현재 검색에 사용된 지역 정보.	String

document

키설명타입

id	장소 ID	String
place_name	장소명, 업체명	String
category_name	카테고리 이름	String
category_group_code	중요 카테고리만 그룹핑한 카테고리 그룹 코드. Request에 category_group_code 테이블 참고	String
category_group_name	중요 카테고리만 그룹핑한 카테고리 그룹명. Request에 category_group_code 테이블 참고	String
phone	전화번호	String
address_name	전체 지번 주소	String
road_address_name	전체 도로명 주소	String
x	X 좌표값 혹은 longitude	String
y	Y 좌표값 혹은 latitude	String
place_url	장소 상세페이지 URL	String
distance	중심좌표까지의 거리(x,y 파라미터를 준 경우에만 존재). 단위 meter	String

예를 들면,

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "meta": { "same_name": null, "pageable_count": 11, "total_count": 11, "is_end": true }, "documents": [ { "place_name": "장생당약국", "distance": "", "place_url": "http://place.map.kakao.com/16618597", "category_name": "의료,건강 > 약국", "address_name": "서울 강남구 대치동 943-16", "road_address_name": "서울 강남구 테헤란로84길 17", "id": "16618597", "phone": "02-558-5476", "category_group_code": "PM9", "category_group_name": "약국", "x": "127.05897078335246", "y": "37.506051888130386" }, ... ] }

 

 

https://developers.kakao.com/docs/restapi/local

Kakao Developers_