페이지 이동경로
  • 문서>
  • 로컬>
  • REST API

로컬

REST API

이 문서는 로컬(Local) API 구현 방법을 소개합니다.

이 문서에 포함된 기능은 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.

주소 검색하기

기본 정보
메서드 URL 인증 방식
GET https://dapi.kakao.com/v2/local/search/address.${FORMAT} REST API 키
권한 사전 설정 카카오 로그인 동의항목
- - - -

주소를 지도 위에 정확하게 표시하기 위해 해당 주소의 좌표 정보를 제공하는 API입니다. 주소에 해당하는 지번 주소, 도로명 주소, 좌표, 우편번호, 빌딩명 등의 다양한 정보를 함께 제공합니다. 이 API는 지번 주소, 도로명 주소 모두 지원합니다.

애플리케이션(이하 앱) REST API 키를 헤더에 담아 GET으로 요청합니다. 검색어와 함께 결과 형식 파라미터의 값을 선택적으로 추가할 수 있습니다.

응답은 JSONXML 형식을 지원합니다. 요청 시 URL의 ${FORMAT} 부분에 원하는 응답 형식을 지정할 수 있습니다. 별도로 포맷을 지정하지 않은 경우 응답은 JSON 형식으로 반환됩니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
경로 변수
이름 타입 설명 필수
FORMAT String 응답 형식(기본값: JSON) X
쿼리 파라미터
이름 타입 설명 필수
query String 검색을 원하는 질의어 O
analyze_type String 검색 결과 제공 방식
다음 중 하나:
similar: 입력한 건물명과 일부만 매칭될 경우에도 확장된 검색 결과 제공, 미지정 시 similar가 적용됨
exact: 주소의 정확한 건물명이 입력된 주소패턴일 경우에 한해, 입력한 건물명과 정확히 일치하는 검색 결과 제공
(기본값: similar)

참고: 품질 향상을 위한 주소 검색 API 업데이트
X
page Integer 결과 페이지 번호
(최소: 1, 최대: 45, 기본값: 1)
X
size Integer 한 페이지에 보여질 문서의 개수
(최소: 1, 최대: 30, 기본값: 10)
X

응답

헤더
이름 설명 필수
Content-type 응답 데이터 타입
content-type: application/json;charset=UTF-8 또는
content-type: text/xml;charset=UTF-8
O
본문
이름 타입 설명
meta Meta 응답 관련 정보
documents Document[] 응답 결과
Meta
이름 타입 설명
total_count Integer 검색어에 검색된 문서 수
pageable_count Integer total_count 중 노출 가능 문서 수
(최대: 45)
is_end Boolean 현재 페이지가 마지막 페이지인지 여부
값이 false면 다음 요청 시 page 값을 증가시켜 다음 페이지 요청 가능
Document
이름 타입 설명
address_name String 전체 지번 주소 또는 전체 도로명 주소, 입력에 따라 결정됨
address_type String address_name의 값의 타입(Type)
다음 중 하나:
REGION(지명)
ROAD(도로명)
REGION_ADDR(지번 주소)
ROAD_ADDR(도로명 주소)
x String X 좌표값, 경위도인 경우 경도(longitude)
y String Y 좌표값, 경위도인 경우 위도(latitude)
address Address 지번 주소 상세 정보
road_address RoadAddress 도로명 주소 상세 정보
Address
이름 타입 설명
address_name String 전체 지번 주소
region_1depth_name String 지역 1 Depth, 시도 단위
region_2depth_name String 지역 2 Depth, 구 단위
region_3depth_name String 지역 3 Depth, 동 단위
region_3depth_h_name String 지역 3 Depth, 행정동 명칭
h_code String 행정 코드
b_code String 법정 코드
mountain_yn String 산 여부, Y 또는 N
main_address_no String 지번 주번지
sub_address_no String 지번 부번지, 없을 경우 빈 문자열("") 반환
x String X 좌표값, 경위도인 경우 경도(longitude)
y String Y 좌표값, 경위도인 경우 위도(latitude)

* zip_code: Deprecated, 우편번호(String), 6자리, 공지 참고

RoadAddress
이름 타입 설명
address_name String 전체 도로명 주소
region_1depth_name String 지역명1
region_2depth_name String 지역명2
region_3depth_name String 지역명3
road_name String 도로명
underground_yn String 지하 여부, Y 또는 N
main_building_no String 건물 본번
sub_building_no String 건물 부번, 없을 경우 빈 문자열("") 반환
building_name String 건물 이름
zone_no String 우편번호(5자리)
x String X 좌표값, 경위도인 경우 경도(longitude)
y String Y 좌표값, 경위도인 경우 위도(latitude)

예제

요청
curl -v -G GET "https://dapi.kakao.com/v2/local/search/address.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "query=전북 삼성동 100" 
응답
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": "",
        "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"
      }
    },
    ...
  ]
}

좌표로 행정구역정보 받기

기본 정보
메서드 URL 인증 방식
GET https://dapi.kakao.com/v2/local/geo/coord2regioncode.${FORMAT} REST API 키
권한 사전 설정 카카오 로그인 동의항목
- - - -

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

앱 REST API 키를 헤더에 담아 GET으로 요청합니다. 좌표와 함께 좌표계 등 파라미터를 선택적으로 추가할 수 있습니다.

응답은 JSONXML 형식을 지원합니다. 요청 시 URL의 ${FORMAT} 부분에 원하는 응답 형식을 지정할 수 있습니다. 별도로 포맷을 지정하지 않은 경우 응답은 JSON 형식으로 반환됩니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
경로 변수
이름 타입 설명 필수
FORMAT String 응답 형식(기본값: JSON) X
쿼리 파라미터
이름 타입 설명 필수
x String X 좌표값, 경위도인 경우 경도(longitude) O
y String Y 좌표값, 경위도인 경우 위도(latitude) O
input_coord String x, y 로 입력되는 값에 대한 좌표계
지원 좌표계: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM
(기본값: WGS84)
X
output_coord String 결과에 출력될 좌표계
지원 좌표계: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM
(기본값: WGS84)
X

응답

헤더
이름 설명 필수
Content-type 응답 데이터 타입
content-type: application/json;charset=UTF-8 또는
content-type: text/xml;charset=UTF-8
O
본문
이름 타입 설명
meta Meta 응답 관련 정보
documents Document[] 응답 결과
Meta
이름 타입 설명
total_count Integer 검색어에 검색된 문서 수
Document
이름 타입 설명
region_type String H(행정동) 또는 B(법정동)
address_name String 전체 지역 명칭
region_1depth_name String 지역 1Depth, 시도 단위
바다 영역은 존재하지 않음
region_2depth_name String 지역 2Depth, 구 단위
바다 영역은 존재하지 않음
region_3depth_name String 지역 3Depth, 동 단위
바다 영역은 존재하지 않음
region_4depth_name String 지역 4Depth
region_type이 법정동이며, 리 영역인 경우만 존재
code String region 코드
x Double X 좌표값, 경위도인 경우 경도(longitude)
y Double Y 좌표값, 경위도인 경우 위도(latitude)

예제

요청
curl -v -G GET "https://dapi.kakao.com/v2/local/geo/coord2regioncode.json?x=127.1086228&y=37.4012191" \
  -H "Authorization: KakaoAK ${REST_API_KEY}"
응답
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
    }
  ]
}

좌표로 주소 변환하기

기본 정보
메서드 URL 인증 방식
GET https://dapi.kakao.com/v2/local/geo/coord2address.${FORMAT} REST API 키
권한 사전 설정 카카오 로그인 동의항목
- - - -

좌표 정보의 지번 주소와 도로명 주소 정보를 반환하는 API입니다. 도로명 주소는 좌표에 따라 반환되지 않을 수 있습니다.

앱 REST API 키를 헤더에 담아 GET으로 요청합니다. 좌표와 함께 좌표계 파라미터를 추가할 수 있습니다.

응답은 JSONXML 형식을 지원합니다. 요청 시 URL의 ${FORMAT} 부분에 원하는 응답 형식을 지정할 수 있습니다. 별도로 포맷을 지정하지 않은 경우 응답은 JSON 형식으로 반환됩니다.

요청 성공 시 응답은 documents 하위에 지번 주소 또는 도로명 주소 상세 정보를 포함합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
쿼리 파라미터
이름 타입 설명 필수
x String X 좌표값, 경위도인 경우 경도(longitude) O
y String Y 좌표값, 경위도인 경우 위도(latitude) O
input_coord String x, y 로 입력되는 값에 대한 좌표계
지원 좌표계: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM
(기본값: WGS84)
X

응답

헤더
이름 설명 필수
Content-type 응답 데이터 타입
content-type: application/json;charset=UTF-8 또는
content-type: text/xml;charset=UTF-8
O
본문
이름 타입 설명
meta Meta 응답 관련 정보
documents Document[] 응답 결과
Meta
이름 타입 설명
total_count Integer 변환된 지번 주소 및 도로명 주소 의 개수, 0 또는 1
Document
이름 타입 설명
address Address 지번 주소 상세 정보, 아래 Address 참고
road_address RoadAddress 도로명 주소 상세 정보, 아래 RoadAddress 참고
Address
이름 타입 설명
address_name String 전체 지번 주소
region_1depth_name String 지역 1Depth명, 시도 단위
region_2depth_name String 지역 2Depth명, 구 단위
region_3depth_name String 지역 3Depth명, 동 단위
mountain_yn String 산 여부, Y 또는 N
main_address_no String 지번 주 번지
sub_address_no String 지번 부 번지, 없을 경우 빈 문자열("") 반환

* zip_code: Deprecated, 우편번호(String), 6자리, 공지 참고

RoadAddress
이름 타입 설명
address_name String 전체 도로명 주소
region_1depth_name String 지역 1Depth, 시도 단위
region_2depth_name String 지역 2Depth, 구 단위
region_3depth_name String 지역 3Depth, 면 단위
road_name String 도로명
underground_yn String 지하 여부, Y 또는 N
main_building_no String 건물 본번
sub_building_no String 건물 부번, 없을 경우 빈 문자열("") 반환
building_name String 건물 이름
zone_no String 우편번호(5자리)

예제

요청
curl -v -G GET "https://dapi.kakao.com/v2/local/geo/coord2address.json?x=127.423084873712&y=37.0789561558879&input_coord=WGS84" \
  -H "Authorization: KakaoAK ${REST_API_KEY}"
응답
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",
      }
    }
  ]
}

좌표계 변환하기

기본 정보
메서드 URL 인증 방식
GET https://dapi.kakao.com/v2/local/geo/transcoord.${FORMAT} REST API 키
권한 사전 설정 카카오 로그인 동의항목
- - - -

x, y 값과 입력 및 출력 좌표계를 지정해 변환된 좌표 값을 구해, 서로 다른 좌표계간 데이터 호환이 가능하도록 합니다.

앱 REST API 키를 헤더에 담아 GET으로 요청합니다. 좌표와 함께 좌표계 파라미터의 값을 선택해 요청합니다.

응답은 JSONXML 형식을 지원합니다. 요청 시 URL의 ${FORMAT} 부분에 원하는 응답 형식을 지정할 수 있습니다. 별도로 포맷을 지정하지 않은 경우 응답은 JSON 형식으로 반환됩니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
쿼리 파라미터
이름 타입 설명 필수
x Double X 좌표값, 경위도인 경우 longitude(경도) O
y Double Y 좌표값, 경위도인 경우 latitude(위도) O
input_coord String x, y 값의 좌표계
지원 좌표계: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM, KTM, UTM, BESSEL, WKTM, WUTM
(기본값: WGS84)
X
output_coord String 변환할 좌표계
지원 좌표계:WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM, KTM, UTM, BESSEL, WKTM, WUTM
(기본값: WGS84)
O

응답

헤더
이름 설명 필수
Content-type 응답 데이터 타입
content-type: application/json;charset=UTF-8 또는
content-type: text/xml;charset=UTF-8
O
본문
이름 타입 설명
meta Meta 응답 관련 정보
documents Document[] 응답 결과
Meta
이름 타입 설명
total_count Integer 매칭된 문서수
Document
이름 타입 설명
x Double X 좌표, 경위도인 경우 경도(longitude)
y Double Y 좌표, 경위도인 경우 위도(latitude)

예제

요청
curl -v -G 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 ${REST_API_KEY}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "meta": {
    "total_count": 1
  },
  "documents": [
    {
      "x": 126.57740680000002,
      "y": 33.453357700000005
    }
  ]
}

키워드로 장소 검색하기

기본 정보
메서드 URL 인증 방식
GET https://dapi.kakao.com/v2/local/search/keyword.${FORMAT} REST API 키
권한 사전 설정 카카오 로그인 동의항목
- - - -

질의어에 매칭된 장소 검색 결과를 지정된 정렬 기준에 따라 제공합니다. 현재 위치 좌표, 반경 제한, 정렬 옵션, 페이징 등의 기능을 통해 원하는 결과를 요청 할 수 있습니다.

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

응답은 JSONXML 형식을 지원합니다. 요청 시 URL의 ${FORMAT} 부분에 원하는 응답 형식을 지정할 수 있습니다. 별도로 포맷을 지정하지 않은 경우 응답은 JSON 형식으로 반환됩니다.

요청 성공 시 응답의 장소 정보는 이름, 주소, 좌표, 카테고리 등의 기본 정보와 다양한 부가정보, 카카오 맵의 장소 상세 페이지로 연결되는 URL을 제공합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
쿼리 파라미터
이름 타입 설명 필수
query String 검색을 원하는 질의어 O
category_group_code CategoryGroupCode 카테고리 그룹 코드, 카테고리로 결과 필터링을 원하는 경우 사용 X
x String 중심 좌표의 X 혹은 경도(longitude) 값
특정 지역을 중심으로 검색할 경우 radius와 함께 사용 가능
X
y String 중심 좌표의 Y 혹은 위도(latitude) 값
특정 지역을 중심으로 검색할 경우 radius와 함께 사용 가능
X
radius Integer 중심 좌표부터의 반경거리. 특정 지역을 중심으로 검색하려고 할 경우 중심좌표로 쓰일 x,y와 함께 사용
(단위: 미터(m), 최소: 0, 최대: 20000)
X
rect String 사각형의 지정 범위 내 제한 검색을 위한 좌표
지도 화면 내 검색 등 제한 검색에서 사용 가능
좌측 X 좌표, 좌측 Y 좌표, 우측 X 좌표, 우측 Y 좌표 형식
X
page Integer 결과 페이지 번호
(최소: 1, 최대: 45, 기본값: 1)
X
size Integer 한 페이지에 보여질 문서의 개수
(최소: 1, 최대: 15, 기본값: 15)
X
sort String 결과 정렬 순서
distance 정렬을 원할 때는 기준 좌표로 쓰일 x, y와 함께 사용
distance 또는 accuracy(기본값: accuracy)
X
CategoryGroupCode
이름 설명
MT1 대형마트
CS2 편의점
PS3 어린이집, 유치원
SC4 학교
AC5 학원
PK6 주차장
OL7 주유소, 충전소
SW8 지하철역
BK9 은행
CT1 문화시설
AG2 중개업소
PO3 공공기관
AT4 관광명소
AD5 숙박
FD6 음식점
CE7 카페
HP8 병원
PM9 약국

응답

헤더
이름 설명 필수
Content-type 응답 데이터 타입
content-type: application/json;charset=UTF-8 또는
content-type: text/xml;charset=UTF-8
O
본문
이름 타입 설명
meta Meta 응답 관련 정보
documents Document[] 응답 결과
Meta
이름 타입 설명
total_count Integer 검색어에 검색된 문서 수
pageable_count Integer total_count 중 노출 가능 문서 수 (최대: 45)
is_end Boolean 현재 페이지가 마지막 페이지인지 여부
값이 false면 다음 요청 시 page 값을 증가시켜 다음 페이지 요청 가능
same_name SameName 질의어의 지역 및 키워드 분석 정보
SameName
이름 타입 설명
region String[] 질의어에서 인식된 지역의 리스트
예: '중앙로 맛집' 에서 중앙로에 해당하는 지역 리스트
keyword String 질의어에서 지역 정보를 제외한 키워드
예: '중앙로 맛집' 에서 '맛집'
selected_region String 인식된 지역 리스트 중, 현재 검색에 사용된 지역 정보
Document
이름 타입 설명
id String 장소 ID
place_name String 장소명, 업체명
category_name String 카테고리 이름
category_group_code String 중요 카테고리만 그룹핑한 카테고리 그룹 코드
category_group_name String 중요 카테고리만 그룹핑한 카테고리 그룹명
phone String 전화번호
address_name String 전체 지번 주소
road_address_name String 전체 도로명 주소
x String X 좌표값, 경위도인 경우 longitude (경도)
y String Y 좌표값, 경위도인 경우 latitude(위도)
place_url String 장소 상세페이지 URL
distance String 중심좌표까지의 거리 (단, x,y 파라미터를 준 경우에만 존재)
단위 meter

예제

요청: 서울 강남구 삼성동 20km 반경에서 카카오프렌즈 매장 검색
curl -v -G GET "https://dapi.kakao.com/v2/local/search/keyword.json?y=37.514322572335935&x=127.06283102249932&radius=20000" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "query=카카오프렌즈" 
응답
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"
    },
    ...
  ]
}

카테고리로 장소 검색하기

기본 정보
메서드 URL 인증 방식
GET https://dapi.kakao.com/v2/local/search/category.${FORMAT} REST API 키
권한 사전 설정 카카오 로그인 동의항목
- - - -

미리 정의된 카테고리 코드에 해당하는 장소 검색 결과를 지정된 정렬 기준에 따라 제공합니다.

앱 REST API 키를 헤더에 담아 GET으로 요청합니다. 카테고리 코드와 함께 위치 좌표, 반경 제한, 결과 정렬 순서, 페이징 등의 파라미터를 선택적으로 사용할 수 있습니다.

응답은 JSONXML 형식을 지원합니다. 요청 시 URL의 ${FORMAT} 부분에 원하는 응답 형식을 지정할 수 있습니다. 별도로 포맷을 지정하지 않은 경우 응답은 JSON 형식으로 반환됩니다.

각 장소 정보는 이름, 주소, 좌표, 카테고리 등의 기본 정보와 다양한 부가정보, 카카오맵의 장소 상세 페이지로 연결되는 URL을 제공합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
경로 변수
이름 타입 설명 필수
FORMAT String 응답 형식(기본값: JSON) X
쿼리 파라미터
이름 타입 설명 필수
category_group_code CategoryGroupCode 카테고리 코드 O
x String 중심 좌표의 X값 혹은 longitude
특정 지역을 중심으로 검색하려고 할 경우 radius와 함께 사용 가능.
(x,y,radius) 또는 rect 필수
y String 중심 좌표의 Y값 혹은 latitude
특정 지역을 중심으로 검색하려고 할 경우 radius와 함께 사용 가능.
(x,y,radius) 또는 rect 필수
radius Integer 중심 좌표부터의 반경거리. 특정 지역을 중심으로 검색하려고 할 경우 중심좌표로 쓰일 x,y와 함께 사용. 단위 meter, 0~20000 사이의 값 (x,y,radius) 또는 rect 필수
rect String 사각형 범위내에서 제한 검색을 위한 좌표
지도 화면 내 검색시 등 제한 검색에서 사용 가능
좌측 X 좌표, 좌측 Y 좌표, 우측 X 좌표, 우측 Y 좌표 형식
x, y, radius 또는 rect 필수
X
page Integer 결과 페이지 번호
1~45 사이의 값 (기본값: 1)
X
size Integer 한 페이지에 보여질 문서의 개수
1~15 사이의 값 (기본값: 15)
X
sort String 결과 정렬 순서, distance 정렬을 원할 때는 기준좌표로 쓰일 x, y 파라미터 필요
distance 또는 accuracy (기본값: accuracy)
X
CategoryGroupCode
이름 설명
MT1 대형마트
CS2 편의점
PS3 어린이집, 유치원
SC4 학교
AC5 학원
PK6 주차장
OL7 주유소, 충전소
SW8 지하철역
BK9 은행
CT1 문화시설
AG2 중개업소
PO3 공공기관
AT4 관광명소
AD5 숙박
FD6 음식점
CE7 카페
HP8 병원
PM9 약국

응답

헤더
이름 설명 필수
Content-type 응답 데이터 타입
content-type: application/json;charset=UTF-8 또는
content-type: text/xml;charset=UTF-8
O
본문
이름 타입 설명
meta Meta 응답 관련 정보
documents Document[] 응답 결과
Meta
이름 타입 설명
total_count Integer 검색된 문서 수
pageable_count Integer total_count 중 노출 가능 문서 수 (최대값: 45)
is_end Boolean 현재 페이지가 마지막 페이지인지 여부
값이 false면 다음 요청 시 page 값을 증가시켜 다음 페이지 요청 가능
same_name SameName 질의어의 지역 및 키워드 분석 정보
SameName
이름 타입 설명
region String[] 질의어에서 인식된 지역의 리스트
(예: '중앙로 맛집' 에서 '중앙로'에 해당하는 지역 리스트)
keyword String 질의어에서 지역 정보를 제외한 키워드
(예: '중앙로 맛집' 에서 '맛집')
selected_region String 인식된 지역 리스트 중 현재 검색에 사용된 지역 정보
Document
이름 타입 설명
id String 장소 ID
place_name String 장소명, 업체명
category_name String 카테고리 이름
category_group_code String 중요 카테고리만 그룹핑한 카테고리 그룹 코드
category_group_name String 중요 카테고리만 그룹핑한 카테고리 그룹명
phone String 전화번호
address_name String 전체 지번 주소
road_address_name String 전체 도로명 주소
x String X 좌표 혹은 경도(longitude)
y String Y 좌표 혹은 위도(latitude)
place_url String 장소 상세 페이지 URL
distance String 중심좌표까지의 거리 (단, x,y 파라미터를 준 경우에만 존재)
(단위: 미터(m))

예제

요청: 서울 강남구 삼성동 20km 반경에서 약국 검색
curl -v -G GET "https://dapi.kakao.com/v2/local/search/category.json?category\_group\_code=PM9&radius=20000" \
  -H "Authorization: KakaoAK ${REST_API_KEY}"
응답
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"
    },
    ...
  ]
}

더 보기