페이지 이동경로
  • Docs>
  • Local>
  • REST API

Local

REST API

This document describes how to integrate the Local API into your service with a REST API.

You can test the features described in this document in [Tools] > [REST API Test].

Address search

Basic information
Method URL Authorization
GET https://dapi.kakao.com/v2/local/search/address.${FORMAT} REST API key
Permission Prerequisite Kakao Login User consent
- - - -

This API provides the coordinates of the requested address with the land-lot number address, road name address, coordinates, zip code, building name, etc., to display the address precisely on the map.

Add your REST API key to the request header, and send a GET request. You can optionally add the parameters to set the result format to your request along with the search query. This API supports both the land-lot number address and road name address systems, and the response supports both XML and JSON formats.

New parameter: analyze_type

As of January 25, 2021, new optional parameter, analyze_type, is added to improve search results. Refer to DevTalk for more details.

Request

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API key as a type of user authentication.		 O
Path variable
Name Type Description Required
FORMAT String The data type of the response.
Either json or xml.(Default: json)		 X
Query parameter
Name Type Description Required
query String Search query you want to search. O
analyze_type String Type of search results.
similar: provides the search results similar to the entered address pattern for a wide range of search results.
exact: provides the search results exactly matched with the entered address pattern when you enter the exact building name as a search query.
If you do not specify this parameter, similar is applied as a default.		 X
page Integer Result page number.
A value between 1 and 45.
(Default: 1)		 X
size Integer Number of documents to be displayed on a single page.
A value between 1 and 30.
(Default: 10)		 X

Response

Header
Name Description Required
content-type The data type of the response.
content-type: application/json;charset=UTF-8
or content-type: text/xml;charset=UTF-8		 O
Body
Name Type Description
meta Meta Search results such as the number of documents found.
documents Document[] Detailed search results, including each document.
Meta
Name Type Description
total_count Integer Number of documents found by search query.
pageable_count Integer Number of documents to be displayed out of all documents (total_count).
(Maximum: 45)
is_end Boolean Whether the current page is the last page.
If false, you can request the next page by incrementing the value of page.
Document
Name Type Description
address_name String Full land-lot number address or full road name address.
Determined as you enter an address.
address_type String Type of the address_name value.
One of REGION, ROAD, REGION_ADDR, ROAD_ADDR.
REGION: Location name.
ROAD: Road name.
REGION_ADDR: Land address.
ROAD_ADDR: Road name address.
x String X coordinate (longitude).
y String Y coordinate (latitude).
address Address Detailed information of Land-lot address.
road_address RoadAddress Detailed information of Road name address.
Address
Name Type Description
address_name String Full land-lot number address.
region_1depth_name String Region 1 Depth. -si(city) unit.
region_2depth_name String Region 2 Depth. -gu unit.
region_3depth_name String Region 3 Depth. -dong unit.
region_3depth_h_name String Region 3 Depth. Name of administrative area.
h_code String Administration code.
b_code String Court code.
mountain_yn String Whether the area is a mountain.
Y or N.
main_address_no String Main land-lot number.
sub_address_no String Additional land-lot number. If none, empty string ("") is returned.
zip_code String Deprecated 6-digit zip code.
Refer to Notice.
x String X coordinate (longitude).
y String Y coordinate (latitude).
RoadAddress
Name Type Description
address_name String Full road name address.
region_1depth_name String Region 1 Depth.
region_2depth_name String Region 2 Depth.
region_3depth_name String Region 3 Depth.
road_name String Road name.
underground_yn String Whether the area is underground.
Y or N.
main_building_no String Building number.
sub_building_no String Additional building number.
If none, empty string ("") is returned.
building_name String Building name.
zone_no String 5-digit zip code.
x String X coordinate (longitude).
y String Y coordinate (latitude).

Sample

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

Convert coordinates to administrative information

Basic information
Method URL Authorization
GET https://dapi.kakao.com/v2/local/geo/coord2regioncode.${FORMAT} REST API key
Permission Prerequisite Kakao Login User consent
- - - -

This API converts the coordinates in the selected coordinate system into the administrative and legal-status area information. You can leverage this API that offers approximate location information to introduce additional information such as restaurants or weather in that location by linking other services.

Add your REST API key to the request header, and send a GET request. You can optionally add the parameters to set the desired coordinate system to your request along with the X and Y coordinates.

The response supports both XML and JSON formats.

Request

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API key as a type of user authentication.		 O
Path variable
Name Type Description Required
FORMAT String The data type of the response.
Either json or xml.(Default: json)		 X
Query parameter
Name Type Description Required
x String X coordinate (longitude). O
y String Y coordinate (latitude). O
input_coord String Coordinate system of the requested x and y.
Supported coordinate systems: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM.
(Default: WGS84)		 X
output_coord String Used to designate the type of coordinate system to be displayed in the response.
Supported coordinate systems: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM.
(Default: WGS84)		 X

Response

Header
Name Description Required
content-type The data type of the response.
content-type: application/json;charset=UTF-8
or content-type: text/xml;charset=UTF-8		 O
Body
Name Type Description
meta Meta Search results such as the number of documents found.
documents Document[] Detailed search results, including each document.
Meta
Name Type Description
total_count Integer Number of documents found by search query.
Document
Name Type Description
region_type String H (administrative) or B (legal-status).
address_name String All region names in address.
region_1depth_name String Region 1 Depth. -si(city) unit (Sea areas are not included).
region_2depth_name String Region 2 Depth. -gu unit (Sea areas are not included).
region_3depth_name String Region 3 Depth. -dong unit (Sea areas are not included).
region_4depth_name String Region 4 Depth.
Only returned if region_type is set to B (legal-status area) and the area is included as -ri unit.
code String Region code.
x Double X coordinate (longitude).
y Double Y coordinate (latitude).

Sample

Request
curl -v -G GET "https://dapi.kakao.com/v2/local/geo/coord2regioncode.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "x=127.1086228" \
  --data-urlencode "y=37.4012191"
Response
HTTP/2 200 
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
    }
  ]
}

Convert coordinates to address

Basic information
Method URL Authorization
GET https://dapi.kakao.com/v2/local/geo/coord2address.${FORMAT} REST API key
Permission Prerequisite Kakao Login User consent
- - - -

This API converts the X and Y coordinates of a location to the land-lot number address and road name address. Some coordinates may not be converted to a road name address.

Add your REST API key to the request header, and send a GET request. You can optionally add the parameter to set the type of the coordinate system to your request along with the X and Y coordinates.

The response supports both XML and JSON formats. If the request is successful, address (land-lot number address) or road_address (road name address) is returned inside documents.

Request

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API key as a type of user authentication.		 O
Path variable
Name Type Description Required
FORMAT String The data type of the response.
Either json or xml.(Default: json)		 X
Query parameter
Name Type Description Required
x String X coordinate (longitude). O
y String Y coordinate (latitude). O
input_coord String Coordinate system of the requested x and y.
Supported coordinate systems: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM.
(Default: WGS84)		 X

Response

Header
Name Description Required
content-type The data type of the response.
content-type: application/json;charset=UTF-8
or content-type: text/xml;charset=UTF-8		 O
Body
Name Type Description
meta Meta Search results such as the number of documents found.
documents Document[] Detailed search results, including each document.
Meta
Name Type Description
total_count Integer Number of converted land-lot number addresses and road name addresses.
0 or 1.
Document
Name Type Description
address Address Detailed information of land-lot number address.
road_address RoadAddress Detailed information of road name address.
Address
Name Type Description
address_name String Full land-lot number address.
region_1depth_name String Region 1 Depth. -si(city) unit.
region_2depth_name String Region 2 Depth. -gu unit.
region_3depth_name String Region 3 Depth. -dong unit.
mountain_yn String Whether the area is a mountain.
Y or N.
main_address_no String Main land-lot number.
sub_address_no String Additional land-lot number.
If none, empty string ("") is returned.
zip_code String Deprecated 6-digit zip code.
Refer to Notice.
RoadAddress
Name Type Description
address_name String Full road name address.
region_1depth_name String Region 1 Depth. -si(city) unit.
region_2depth_name String Region 2 Depth. -gu unit.
region_3depth_name String Region 3 Depth. -myeon unit.
road_name String Road name.
underground_yn String Whether the area is underground.
Y or N.
main_building_no String Building number.
sub_building_no String Additional building number.
If none, empty string("") is returned.
building_name String Building name.
zone_no String 5-digit zip code.

Sample

Request
curl -v -G GET "https://dapi.kakao.com/v2/local/geo/coord2address.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  -d "x=127.423084873712" \
  -d "y=37.0789561558879" \
  -d "input_coord=WGS84"
Response
HTTP/2 200 
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",
      }
    }
  ]
}

Convert coordinate system

Basic information
Method URL Authorization
GET https://dapi.kakao.com/v2/local/geo/transcoord.${FORMAT} REST API key
Permission Prerequisite Kakao Login User consent
- - - -

This API converts the specified X and Y coordinates ​​in a coordinate system to another X and Y coordinates in the designated coordinate system, which allows compatibility with other coordinate systems.

Add your REST API key to the request header, and send a GET request. You can designate the desired coordinate system to convert to along with the X and Y coordinates.

The response supports both XML and JSON formats.

Request

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API key as a type of user authentication.		 O
Path variable
Name Type Description Required
FORMAT String The data type of the response.
Either json or xml.(Default: json)		 X
Query parameter
Name Type Description Required
x Double X coordinate (longitude). O
y Double Y coordinate (latitude). O
input_coord String Coordinate system of the requested x and y.
Supported coordinate systems: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM, KTM, UTM, BESSEL, WKTM, WUTM.
(Default: WGS84)		 X
output_coord String Type of coordinate system to be converted from the input coordinate system.
Supported coordinate systems: WGS84, WCONGNAMUL, CONGNAMUL, WTM, TM, KTM, UTM, BESSEL, WKTM, WUTM.
(Default: WGS84)		 O

Response

Header
Name Description Required
content-type The data type of the response.
content-type: application/json;charset=UTF-8
or content-type: text/xml;charset=UTF-8		 O
Body
Name Type Description
meta Meta Search results such as the number of documents found.
documents Document[] Detailed search results, including each document.
Meta
Name Type Description
total_count Integer Number of matched documents.
Document
Name Type Description
x String X coordinate (longitude).
y String Y coordinate (latitude).

Sample

Request
curl -v -G GET "https://dapi.kakao.com/v2/local/geo/transcoord.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "x=160710.37729270622" \
  --data-urlencode "y=-4388.879299157299" \
  --data-urlencode "input_coord=WTM" \
  --data-urlencode "output_coord=WGS84"
Response
HTTP/2 200 
content-type: application/json;charset=UTF-8
{
  "meta": {
    "total_count": 1
  },
  "documents": [
    {
      "x": 126.57740680000002,
      "y": 33.453357700000005
    }
  ]
}

Place search by keyword

Basic information
Method URL Authorization
GET https://dapi.kakao.com/v2/local/search/keyword.${FORMAT} REST API key
Permission Prerequisite Kakao Login User consent
- - - -

This API provides the search results for places that match the search query in the specified sorting order. You can request the desired result with extended features such as current position coordinates, radius limit, sort options, paging, and more.

Add your REST API key to the request header, and send a GET request. You can optionally add the parameters to set the result format to your request along with the search query.

The response supports both XML and JSON formats. If the request is successful, it returns place information such as name, address, coordinates, category, and a URL redirecting to the detail page of the place on the Kakao Map.

Request

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API key as a type of user authentication.		 O
Path variable
Name Type Description Required
FORMAT String The data type of the response.
Either json or xml.(Default: json)		 X
Query parameter
Name Type Description Required
query String Search query you want to search. O
category_group_code String Category group code of the places to search for.
Major places are classified as a category group.
Used when you want to filter the results by category.		 X
x String X coordinate (longitude) of the center.
Used to search places around a specific area along with radius.		 X
y String Y coordinate (latitude) of the center.
Used to search places around a specific area along with radius.		 X
radius Integer The distance from the center coordinates to an axis of rotation in meters.
Used to search places around a specific area along with x and y (center coordinates).
A value between 0 and 20000.		 X
rect String Coordinates of a rectangle that is used to limit search area, such as when searching places within the map screen.
In the coordinates of left X, left Y, right X, and right Y format.		 X
page Integer Result page number.
A value between 1 and 45.
(Default: 1)		 X
size Integer Number of documents to be displayed on a single page.
A value between 1 and 15.
(Default: 15)		 X
sort String Sorting method of the document results.
accuracy or distance (Default: accuracy).
In the case of distance, x and y values are required as a reference coordinates.		 X
Category group code
Name Description
MT1 Supermarket
CS2 Convenience store
PS3 Daycare center, kindergarten
SC4 School
AC5 Hagwon such as cram school, private learning institute
PK6 Parking lot
OL7 Gas station, LPG station
SW8 Subway station
BK9 Bank
CT1 Cultural facility
AG2 Real estate agency
PO3 Public institutions
AT4 Attractions
AD5 Accommodation
FD6 Restaurant
CE7 Cafe
HP8 Hospital
PM9 Pharmacy

Response

Header
Name Description Required
content-type The data type of the response.
content-type: application/json;charset=UTF-8
or content-type: text/xml;charset=UTF-8		 O
Body
Name Type Description
meta Meta Search results such as the number of documents found.
documents Document[] Detailed search results, including each document.
Meta
Name Type Description
total_count Integer Number of documents found by search query.
pageable_count Integer Number of documents to be displayed out of all documents (total_count).
(Maximum: 45)
is_end Boolean Whether the current page is the last page.
If false, you can request the next page by incrementing the value of page.
same_name RegionInfo Location and keyword analyzed out of the search query.
RegionInfo
Name Type Description
region String[] List of places found according to the region in a search query.
Example: List of places in 'Jungang-ro' (region name) out of 'Jungang-ro Restaurants'
keyword String Keyword excluding region information in the search query.
Example: 'Restaurant' in'Jungang-ro Restaurant'
selected_region String The region information used to search for places in the list of found places.
Document
Name Type Description
id String Place ID.
place_name String Place name, company name.
category_name String Category name.
category_group_code String Code of the requested category group.
category_group_name String Name of category groups that are grouped for only major categories.
phone String Phone number.
address_name String Full land-lot number address.
road_address_name String Full road name address.
x String X coordinate (longitude).
y String Y coordinate (latitude).
place_url String URL of the detailed page on the place.
distance String Distance to the coordinates of the center in meters.
Only returned if x and y are specified.

Sample

Request: Search for Kakao Friends store within a radius of 20 KM from Samsung-dong, Gangnam-gu in Seoul
curl -v -G GET "https://dapi.kakao.com/v2/local/search/keyword.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "query=카카오프렌즈" \
  --data-urlencode "x=127.06283102249932" \
  --data-urlencode "y=37.514322572335935" \
  --data-urlencode "radius=20000"
Response
HTTP/2 200 
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"
    },
    ...
  ]
}

Place search by category

Basic information
Method URL Authorization
GET https://dapi.kakao.com/v2/local/search/category.${FORMAT} REST API key
Permission Prerequisite Kakao Login User consent
- - - -

This API provides the search results for places by predefined group code in the specified order. You can request the desired result with extended features such as current position coordinates, radius limit, sort options, paging, and more.

Add your REST API key to the request header, and send a GET request. You can optionally add the parameters to set the result format to your request along with the search query.

The response supports both XML and JSON formats. If the request is successful, it returns place information such as name, address, coordinates, category, and a URL redirecting to the detail page of the place on the Kakao Map.

Request

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API key as a type of user authentication.		 O
Path variable
Name Type Description Required
FORMAT String The data type of the response.
Either json or xml.(Default: json)		 X
Query parameter
Name Type Description Required
category_group_code String Category group code of the places to search for.
Major places are classified as a category group.		 O
x String X coordinate (longitude) of the center.
Used to search places around a specific area along with radius.		 Either (x,y, radius) or rect is required.
y String Y coordinate (latitude) of the center.
Used to search places around a specific area along with radius.		 Either (x,y, radius) or rect is required.
radius Integer The distance from the center coordinates to an axis of rotation in meters.
Used to search places around a specific area along with x and y (center coordinates).
A value between 0 and 20000.		 Either (x,y, radius) or rect is required.
rect String Coordinates of a rectangle that is used to limit search area, such as when searching places within the map screen.
In the coordinates of left X, left Y, right X, and right Y format.
Either (x,y, radius) or rect is required.		 X
page Integer Result page number.
A value between 1 and 45.
(Default: 1)		 X
size Integer Number of documents to be displayed on a single page.
A value between 1 and 15.
(Default: 15)		 X
sort String Sorting method of the document results.
accuracy or distance (Default: accuracy).
In the case of distance, x and y values are required as a reference coordinates.		 X

Response

Header
Name Description Required
content-type The data type of the response.
content-type: application/json;charset=UTF-8
or content-type: text/xml;charset=UTF-8		 O
Body
Name Type Description
meta Meta Search results such as the number of documents found.
documents Document[] Detailed search results, including each document.
Meta
Name Type Description
total_count Integer Number of documents found by search query.
pageable_count Integer Number of documents to be displayed out of all documents (total_count).
(Maximum: 45)
is_end Boolean Whether the current page is the last page.
If false, you can request the next page by incrementing the value of page.
same_name RegionInfo Location and keyword analyzed out of the search query.
RegionInfo
Name Type Description
region String[] List of places found according to the region in a search query.
Example: List of places in Jungang-ro(region name) out of 'Jungang-ro Restaurants'
keyword String Keyword excluding region information in the search query.
Example: 'Restaurant' in'Jungang-ro Restaurant'
selected_region String The region information used to search for places in the list of the found places.
Document
Name Type Description
id String Place ID.
place_name String Place name, company name.
category_name String Category name.
category_group_code String Code of the requested category group.
Only returned if category_group_code is specified.
category_group_name String Name of the requested category group.
Only returned if category_group_code is specified.
phone String Phone number.
address_name String Full land-lot number address.
road_address_name String Full road name address.
x String X coordinate (longitude).
y String Y coordinate (latitude).
place_url String URL of the detailed page on the place.
distance String Distance to the coordinates of the center in meters.
Only returned if x and y are specified.

Sample

Request: Search for pharmacies within a radius of 20 KM from Samsung-dong, Gangnam-gu in Seoul
curl -v -G GET "https://dapi.kakao.com/v2/local/search/category.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "category_group_code=PM9" \
  --data-urlencode "radius=20000"
Response
HTTP/2 200 
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"
    },
    ...
  ]
}

See more

Local> REST API