Kakao Map

REST API

This document describes how to integrate Kakao Map APIs into your service with a REST API.

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

Address / Coordinate conversion

Convert address to coordinates

Basic information

Method	URL	Authorization
`GET`	`https://dapi.kakao.com/v2/local/search/address.${FORMAT}`	REST API key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key	-	-

Returns the coordinates and details of the requested address string.

Exclude detailed addresses from the search query

Exclude detailed addresses such as building names under the land-lot number, road name number, and other from the query. Detailed address formats vary widely, so accurate search results cannot be guaranteed.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Path variable

Name	Type	Description	Required
FORMAT	`String`	Response format, one of the following. `JSON` (Default) `XML`	X

Query parameter

Name	Type	Description	Required
query	`String`	Query to search for. Both land-lot number addresses and road name addresses are supported.	O
analyze_type	`String`	Search result type, one of the following. `similar`: Provides extended search results even when only part of the entered building name matches. (Default). `exact`: Provides search results that exactly match the entered building name only when the address pattern includes the exact building name. Reference: Address-to-coordinate conversion API update to improve quality	X
page	`Integer`	Result page number (Minimum: `1`, Maximum: `45`, Default: `1`).	X
size	`Integer`	Number of results to display on a page (Minimum: `1`, Maximum: `30`, Default: `10`).	X

Response

Header

Name	Description	Required
Content-Type	Response data type, one of the following. `content-type: application/json;charset=UTF-8` `content-type: text/xml;charset=UTF-8`	O

Body

Name	Type	Description
meta	`Meta`	Metadata for the result.
documents	`Document[]`	List of address search results.

Meta

Name	Type	Description
total_count	`Integer`	Number of results found for the search `query`.
pageable_count	`Integer`	Number of results available for display out of `total_count`.
is_end	`Boolean`	Whether the current page is the last page. If `false`, you can request the next page by incrementing `page`.

Document

Name	Type	Description
address_name	`String`	Full land-lot number address or full road name address, determined by the input.
address_type	`String`	Type of `address_name`, one of the following. `REGION`: Region name. `ROAD`: Road name. `REGION_ADDR`: Land-lot number address. `ROAD_ADDR`: Road name address.
x	`String`	X coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is longitude.
y	`String`	Y coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is latitude.
address	`Address`	Detailed land-lot number address information.
road_address	`RoadAddress`	Detailed road name address information.

Address

Name	Type	Description
address_name	`String`	Full land-lot number address.
region_1depth_name	`String`	Region 1 Depth, city or province level.
region_2depth_name	`String`	Region 2 Depth, district level.
region_3depth_name	`String`	Region 3 Depth, dong level.
region_3depth_h_name	`String`	Region 3 Depth, administrative area name.
h_code	`String`	Administrative code.
b_code	`String`	Legal-status code.
mountain_yn	`String`	Whether the address is a mountain address, one of the following. `Y`: Mountain. `N`: Not a mountain.
main_address_no	`String`	Main land-lot number.
sub_address_no	`String`	Sub land-lot number. If none, an empty string (`""`) is returned.
x	`String`	X coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is longitude.
y	`String`	Y coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is latitude.

* zip_code: Deprecated, 6-digit zip code (String). See Notice.

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 address is underground, one of the following. `Y`: Underground. `N`: Ground level.
main_building_no	`String`	Main building number.
sub_building_no	`String`	Sub building number. If none, an empty string (`""`) is returned.
building_name	`String`	Building name.
zone_no	`String`	5-digit zip code.
x	`String`	X coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is longitude.
y	`String`	Y coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is 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/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"
      }
    }
    // ...
  ]
}

Convert coordinates to region code

Basic information

Method	URL	Authorization
`GET`	`https://dapi.kakao.com/v2/local/geo/coord2regioncode.${FORMAT}`	REST API key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key	-	-

Returns the administrative and legal-status area information for the specified coordinates.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Path variable

Name	Type	Description	Required
FORMAT	`String`	Response format, one of the following. `JSON` (Default) `XML`	X

Query parameter

Name	Type	Description	Required
x	`Double`	X coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is longitude.	O
y	`Double`	Y coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is latitude.	O
input_coord	`String`	Coordinate system to apply to the coordinate values (`x`, `y`), one of the following. `WGS84` (Default) `WCONGNAMUL` `CONGNAMUL` `WTM` `TM`	X
output_coord	`String`	Coordinate system to apply to the response, one of the following. `WGS84` (Default) `WCONGNAMUL` `CONGNAMUL` `WTM` `TM`	X

Response

Header

Name	Description	Required
Content-Type	Response data type, one of the following. `content-type: application/json;charset=UTF-8` `content-type: text/xml;charset=UTF-8`	O

Body

Name	Type	Description
meta	`Meta`	Metadata for the result.
documents	`Document[]`	List of administrative region information for the coordinates.

Meta

Name	Type	Description
total_count	`Integer`	Number of administrative regions found.

Document

Name	Type	Description
region_type	`String`	Administrative or legal-status area, one of the following. `H`: Administrative. `B`: Legal-status.
address_name	`String`	Full region name.
region_1depth_name	`String`	Region 1 Depth, city or province level. Not included for sea areas.
region_2depth_name	`String`	Region 2 Depth, district level. Not included for sea areas.
region_3depth_name	`String`	Region 3 Depth, dong level. Not included for sea areas.
region_4depth_name	`String`	Region 4 Depth. Important: Exists only when `region_type` is `B` and the area is a -ri unit.
code	`String`	Administrative or legal-status area code.
x	`Double`	X coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is longitude.
y	`Double`	Y coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is latitude.

Sample

Request

curl -v -G GET "https://dapi.kakao.com/v2/local/geo/coord2regioncode.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  -d "x=127.1086228" \
  -d "y=37.4012191"

Response

// 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
    }
  ]
}

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
-	REST API key	-	-

Returns the land-lot number address and road name address information for the specified coordinates.

Road name address response

A road name address may not be returned depending on the specified coordinates.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Path variable

Name	Type	Description	Required
FORMAT	`String`	Response format, one of the following. `JSON` (Default) `XML`	X

Query parameter

Name	Type	Description	Required
x	`Double`	X coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is longitude.	O
y	`Double`	Y coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is latitude.	O
input_coord	`String`	Coordinate system to apply to the coordinate values (`x`, `y`), one of the following. `WGS84` (Default) `WCONGNAMUL` `CONGNAMUL` `WTM` `TM`	X

Response

Header

Name	Description	Required
Content-Type	Response data type, one of the following. `content-type: application/json;charset=UTF-8` `content-type: text/xml;charset=UTF-8`	O

Body

Name	Type	Description
meta	`Meta`	Metadata for the result.
documents	`Document[]`	List of address information for the coordinates.

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 land-lot number address information.
road_address	`RoadAddress`	Detailed road name address information.

Address

Name	Type	Description
address_name	`String`	Full land-lot number address.
region_1depth_name	`String`	Region 1 Depth, city or province level.
region_2depth_name	`String`	Region 2 Depth, district level.
region_3depth_name	`String`	Region 3 Depth, dong level.
mountain_yn	`String`	Whether the address is a mountain address, one of the following. `Y`: Mountain. `N`: Not a mountain.
main_address_no	`String`	Main land-lot number.
sub_address_no	`String`	Sub land-lot number. If none, an empty string (`""`) is returned.

* zip_code: Deprecated, 6-digit zip code (String). See Notice.

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 address is underground, one of the following. `Y`: Underground. `N`: Ground level.
main_building_no	`String`	Main building number.
sub_building_no	`String`	Sub building number. If none, an 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/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"
      }
    }
  ]
}

Transform coordinates

Basic information

Method	URL	Authorization
`GET`	`https://dapi.kakao.com/v2/local/geo/transcoord.${FORMAT}`	REST API key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key	-	-

Returns coordinate values in a specified coordinate system from coordinate values in another coordinate system.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Path variable

Name	Type	Description	Required
FORMAT	`String`	Response format, one of the following. `JSON` (Default) `XML`	X

Query parameter

Name	Type	Description	Required
x	`Double`	X coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is longitude.	O
y	`Double`	Y coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is latitude.	O
input_coord	`String`	Coordinate system to apply to the coordinate values (`x`, `y`), one of the following. `WGS84` (Default) `WCONGNAMUL` `CONGNAMUL` `WTM` `TM` `KTM` `UTM` `BESSEL` `WKTM` `WUTM`	X
output_coord	`String`	Coordinate system to apply to the response, one of the following. `WGS84` `WCONGNAMUL` `CONGNAMUL` `WTM` `TM` `KTM` `UTM` `BESSEL` `WKTM` `WUTM`	O

Response

Header

Name	Description	Required
Content-Type	Response data type, one of the following. `content-type: application/json;charset=UTF-8` `content-type: text/xml;charset=UTF-8`	O

Body

Name	Type	Description
meta	`Meta`	Metadata for the result.
documents	`Document[]`	List of converted coordinate information.

Meta

Name	Type	Description
total_count	`Integer`	Number of converted coordinates.

Document

Name	Type	Description
x	`Double`	X coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is longitude.
y	`Double`	Y coordinate. If the coordinate system is latitude and longitude (`WGS84`), this is latitude.

Sample

Request

curl -v -G GET "https://dapi.kakao.com/v2/local/geo/transcoord.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  -d "x=160710.37729270622" \
  -d "y=-4388.879299157299" \
  -d "input_coord=WTM" \
  -d "output_coord=WGS84"

Response

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

Place search

Search place 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
-	REST API key	-	-

Returns place search results that match the requested keyword in the specified sort order.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Path variable

Name	Type	Description	Required
FORMAT	`String`	Response format, one of the following. `JSON` (Default) `XML`	X

Query parameter

Name	Type	Description	Required
query	`String`	Query to search for.	O
category_group_code	`CategoryGroupCode`	Category group code. Used to filter results by category.	X
x	`String`	X value of the center coordinate to search, longitude. Reference: Use with `radius` to search by center coordinate and radius.	X
y	`String`	Y value of the center coordinate to search, latitude. Reference: Use with `radius` to search by center coordinate and radius.	X
radius	`Integer`	Search radius from the center coordinate (Minimum: `0`, Maximum: `20000`, Unit: meter (m)). Important: Center coordinate values (`x`, `y`) are required.	X
rect	`String`	Coordinates that specify the rectangular search area. Used when the search area must be limited, such as searching within the map screen. (Format: `left X coordinate, left Y coordinate, right X coordinate, right Y coordinate`).	X
page	`Integer`	Result page number (Minimum: `1`, Maximum: `45`, Default: `1`).	X
size	`Integer`	Number of places to display on a page (Minimum: `1`, Maximum: `15`, Default: `15`).	X
sort	`String`	Result sort order, one of the following. `distance`: Distance from the center coordinate. `accuracy`: Accuracy (Default). Important: Center coordinate values (`x`, `y`) are required when using `distance` sort.	X

* You can specify the search area by including set of the center with radius (x, y, radius) parameters, or the rectangular (rect) paramter.

CategoryGroupCode

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, charging 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	Response data type, one of the following. `content-type: application/json;charset=UTF-8` `content-type: text/xml;charset=UTF-8`	O

Body

Name	Type	Description
meta	`Meta`	Metadata for the result.
documents	`Document[]`	List of places from keyword search results.

Meta

Name	Type	Description
total_count	`Integer`	Number of places found.
pageable_count	`Integer`	Number of places available for display out of `total_count`.
is_end	`Boolean`	Whether the current page is the last page. If `false`, you can request the next page by incrementing `page`.
same_name	`SameName`	Region and keyword analysis information for the search `query`.

SameName

Name	Type	Description
region	`String[]`	List of regions recognized from the search `query` (For example: list of regions corresponding to `Jungang-ro` in `Jungang-ro restaurants`).
keyword	`String`	Keyword from the search `query` excluding region information (For example: `restaurants` in `Jungang-ro restaurants`).
selected_region	`String`	Region information used for the current search from the list of recognized regions.

Document

Name	Type	Description
id	`String`	Place ID.
place_name	`String`	Place name, company name.
category_name	`String`	Category name.
category_group_code	`String`	Major category group code. If none, an empty string (`""`) is returned.
category_group_name	`String`	Major category group name. If none, an empty string (`""`) is returned.
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`	Place details page URL.
distance	`String`	Distance to the center coordinate. Returned only if center coordinate values (`x`, `y`) are included in the request. (Unit: meter (m)).

Sample

Request: Search for Kakao Friends stores within a 20 km radius of Samsung-dong, Gangnam-gu, Seoul

curl -v -G GET "https://dapi.kakao.com/v2/local/search/keyword.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "query=카카오프렌즈" \
  -d "y=37.514322572335935" \
  -d "x=127.06283102249932" \
  -d "radius=20000"

Response

// 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"
    }
    // ...
  ]
}

Search place 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
-	REST API key	-	-

Returns place search results for the requested category code in the specified sort order.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Path variable

Name	Type	Description	Required
FORMAT	`String`	Response format, one of the following. `JSON` (Default) `XML`	X

Query parameter

Name	Type	Description	Required
category_group_code	`CategoryGroupCode`	Category group code.	O
x	`String`	X value of the center coordinate to search, longitude. Reference: Use with `radius` to search by center coordinate and radius.	X
y	`String`	Y value of the center coordinate to search, latitude. Reference: Use with `radius` to search by center coordinate and radius.	X
radius	`Integer`	Search radius from the center coordinate (Minimum: `0`, Maximum: `20000`, Unit: meter (m)). Important: Center coordinate values (`x`, `y`) are required.	X
rect	`String`	Coordinates that specify the rectangular search area. Used when the search area must be limited, such as searching within the map screen. (Format: `left X coordinate, left Y coordinate, right X coordinate, right Y coordinate`).	X
page	`Integer`	Result page number (Minimum: `1`, Maximum: `45`, Default: `1`).	X
size	`Integer`	Number of places to display on a page (Minimum: `1`, Maximum: `15`, Default: `15`).	X
sort	`String`	Result sort order, one of the following. `distance`: Distance from the center coordinate. `accuracy`: Accuracy (Default). Important: Center coordinate values (`x`, `y`) are required when using `distance` sort.	X

* You can specify the search area by including set of the center with radius (x, y, radius) parameters, or the rectangular (rect) paramter.

Response

Header

Name	Description	Required
Content-Type	Response data type, one of the following. `content-type: application/json;charset=UTF-8` `content-type: text/xml;charset=UTF-8`	O

Body

Name	Type	Description
meta	`Meta`	Metadata for the result.
documents	`Document[]`	List of places from category search results.

Meta

Name	Type	Description
total_count	`Integer`	Number of places found.
pageable_count	`Integer`	Number of places available for display out of `total_count`.
is_end	`Boolean`	Whether the current page is the last page. If `false`, you can request the next page by incrementing `page`.
same_name	`SameName`	Region and keyword analysis information. If none, `null` is returned.

SameName

Name	Type	Description
region	`String[]`	List of recognized regions (For example: list of regions corresponding to `Jungang-ro` in `Jungang-ro restaurants`).
keyword	`String`	Keyword excluding region information (For example: `restaurants` in `Jungang-ro restaurants`).
selected_region	`String`	Region information used for the current search from the list of recognized regions.

Document

Name	Type	Description
id	`String`	Place ID.
place_name	`String`	Place name, company name.
category_name	`String`	Category name.
category_group_code	`String`	Requested category group code.
category_group_name	`String`	Requested category group name.
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`	Place details page URL.
distance	`String`	Distance to the center coordinate. Returned only if center coordinate values (`x`, `y`) are included in the request. (Unit: meter (m)).

Sample

Request: Search for pharmacies within a 20 km radius of Samsung-dong, Gangnam-gu, Seoul

curl -v -G GET "https://dapi.kakao.com/v2/local/search/category.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  -d "category_group_code=PM9" \
  -d "y=37.514322572335935" \
  -d "x=127.06283102249932" \
  -d "radius=20000"

Response

// 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"
    }
    // ...
  ]
}

Route retrieval

Get public transit routes

Basic information

Method	URL	Authorization
`GET`	`https://dapi.kakao.com/v2/routing/publictraffic`	REST API key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key	-	-

Returns public transit routes for the specified origin and destination coordinates.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Query parameter

Name	Type	Description	Required
start_x	`String`	Origin X coordinate.	O
start_y	`String`	Origin Y coordinate.	O
s_name	`String`	Origin name (Default: `출발`).	X
end_x	`String`	Destination X coordinate.	O
end_y	`String`	Destination Y coordinate.	O
e_name	`String`	Destination name (Default: `도착`).	X
input_coord	`String`	Input coordinate system, one of the following. `WGS84` (Default) `WTM` `TM` `WCONGNAMUL`	X
output_coord	`String`	Output coordinate system, one of the following. `WGS84` (Default) `WTM` `TM` `WCONGNAMUL`	X

Response

Body

Name	Type	Description
status	`String`	Public transit route search result code, one of the following. `OK`: Success. `STARTNODES_NULL`: No origin node. `ENDNODES_NULL`: No destination node. `EQUAL_POINTS`: Origin and destination are the same. `INVALID_REQUEST`: Invalid request. `NO_RESULTS`: No results.
properties	`Properties`	Public transit route result properties.
routes	`Route[]`	List of public transit routes. Important: Included in the response only when `status` is `OK`.

Properties

Name	Type	Description
total	`Integer`	Total number of routes.
bus	`Integer`	Number of bus routes.
subway	`Integer`	Number of subway routes.
busAndSubway	`Integer`	Number of routes that use both bus and subway.
landingURL	`String`	Landing URL for the Kakao Map directions screen.

Route

Name	Type	Description
properties	`RouteProperties`	Public transit route properties.
steps	`Step[]`	List of public transit route steps.

RouteProperties

Name	Type	Description
type	`String`	Public transit route type, one of the following. `BUS`: Bus. `SUBWAY`: Subway. `BUS_AND_SUBWAY`: Bus and subway.
totalDistance	`Integer`	Public transit route distance (Unit: meter (m)).
totalTime	`Integer`	Public transit route duration (Unit: second (s)).
transfers	`Integer`	Number of transfers for the public transit route.
fare	`Fare`	Public transit route fare information.

Fare

Name	Type	Description
value	`Integer`	Fare (Unit: KRW).
min	`Integer`	Minimum fare.
max	`Integer`	Maximum fare.

Step

Name	Type	Description
properties	`StepProperties`	Public transit route step properties.
path	`Path`	Public transit route step coordinate information.

StepProperties

Name	Type	Description
guidance	`String`	Public transit route step guidance text.
type	`String`	Bus or subway subtype name, one of the following: `Trunk`, `Branch`, `Metropolitan`, `Circulation`, `Airport`, `Regular`, `Seated`, `Express`, `Village`, `Direct Express`, `Suburban`, `Intercity`, `Rural`, `Hangang Bus`, `Youth`, `Tour`, `Direct`, `ITX-Cheongchun`, `Limited Express` Important: Subtype names may be added, changed, or removed.
distance	`Integer`	Public transit route step distance (Unit: meter (m)).
time	`Integer`	Public transit route step duration (Unit: second (s)).
stops	`Stop[]`	List of stops for the public transit route step.
vehicles	`Vehicle[]`	List of vehicles for the public transit route step.

Stop

Name	Type	Description
name	`String`	Stop name.

Vehicle

Name	Type	Description
type	`String`	Vehicle type, one of the following. `BUS`: Bus. `SUBWAY`: Subway.
name	`String`	Vehicle name.

Path

Name	Type	Description
points	`Double[][]`	List of public transit route step coordinates. Each inner array is a coordinate pair in `[x, y]` format. (Example: `[[127.02700693, 37.49864277], [127.02698289, 37.49863151]]`).

Sample

Request

curl -v -G GET "https://dapi.kakao.com/v2/routing/publictraffic" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "start_x=127.11119217" \
  --data-urlencode "start_y=37.39477123" \
  --data-urlencode "end_x=127.12628814" \
  --data-urlencode "end_y=37.41993056"

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "status": "OK",
  "properties": {
    "total": 15,
    "bus": 9,
    "subway": 1,
    "busAndSubway": 5,
    "landingURL": "https://map.kakao.com/link/by/traffic/%EC%B6%9C%EB%B0%9C,37.39477123,127.11119217/%EB%8F%84%EC%B0%A9,37.41993056,127.12628814"
  },
  "routes": [
    {
      "properties": {
        "type": "BUS",
        "totalDistance": 5013,
        "totalTime": 2115,
        "transfers": 0,
        "fare": {
          "value": 1350
        }
      },
      "steps": [
        {
          "properties": {
            "guidance": "마을 76 (판교역동편 > 성남시청전면)",
            "type": "BUS",
            "distance": 4127,
            "time": 1158,
            "stops": [
              { "name": "판교역동편" },
              { "name": "봇들마을7.8단지.롯데마트판교점" }
              // ...
            ],
            "vehicles": [
              { "name": "76", "type": "마을" }
              // ...
            ]
          },
          "path": {
            "points": [
              [127.11316378, 37.3948816],
              [127.11312974, 37.39488161]
              // ...
            ]
          }
        }
        // ...
      ]
    }
    // ...
  ]
}

Get walking routes

Basic information

Method	URL	Authorization
`GET`	`https://dapi.kakao.com/v2/routing/walk`	REST API key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key	-	-

Returns walking routes for the specified origin and destination coordinates.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Query parameter

Name	Type	Description	Required
start_x	`String`	Origin X coordinate.	O
start_y	`String`	Origin Y coordinate.	O
via_x	`String`	Waypoint X coordinates (Up to 5, separated by comma (`,`)).	X
via_y	`String`	Waypoint Y coordinates (Up to 5, separated by comma (`,`)).	X
end_x	`String`	Destination X coordinate.	O
end_y	`String`	Destination Y coordinate.	O
s_name	`String`	Origin name (Default: `출발`).	X
v_name	`String`	Waypoint names (Up to 5, separated by comma (`,`)).	X
e_name	`String`	Destination name (Default: `도착`).	X
input_coord	`String`	Input coordinate system, one of the following. `WGS84` (Default) `WTM` `TM` `WCONGNAMUL`	X
output_coord	`String`	Output coordinate system, one of the following. `WGS84` (Default) `WTM` `TM` `WCONGNAMUL`	X
route_mode	`String`	Search option, one of the following. `BROAD_FIRST`: Wide roads first (Default). `SHORTEST`: Shortest route. `ACCESSIBLE`: Easy route.	X

Response

Body

Name	Type	Description
status	`String`	Route search result status, one of the following. `OK`: Success. `SAME_POINT`: Origin and destination are the same. `START_LINK_NOT_FOUND`: Road around the origin cannot be found. `END_LINK_NOT_FOUND`: Road around the destination cannot be found. `TOO_MANY_SEARCH_LINK`: Too many links were searched. `TOO_FAR_AWAY`: Origin and destination are too far apart. `ROUTE_RESULT_NOT_FOUND`: No results.
route	`Route`	Full route information. Important: Included in the response only when `status` is `OK`.

Route

Name	Type	Description
properties	`RouteProperties`	Full route properties.
legs	`Leg[]`	List of route sections.

RouteProperties

Name	Type	Description
totalDistance	`Integer`	Total route distance (Unit: meter (m)).
totalTime	`Integer`	Total route duration (Unit: second (s)).
landingUrl	`String`	Landing URL for the Kakao Map directions screen.

Leg

Name	Type	Description
properties	`LegProperties`	Route section properties.
steps	`Step[]`	List of route section steps.

LegProperties

Name	Type	Description
distance	`Integer`	Route section distance (Unit: meter (m)).
time	`Integer`	Route section duration (Unit: second (s)).

Step

Name	Type	Description
properties	`StepProperties`	Route step properties.
path	`Path`	Route step coordinate information.

StepProperties

Name	Type	Description
distance	`Integer`	Route step distance (Unit: meter (m)).
guidance	`String`	Route step guidance text.
time	`Integer`	Route step duration (Unit: second (s)).
x	`Double`	X coordinate of the route step start point.
y	`Double`	Y coordinate of the route step start point.

Path

Name	Type	Description
points	`Double[][]`	List of route step coordinates. Each inner array is a coordinate pair in `[x, y]` format. (Example: `[[127.02700693, 37.49864277], [127.02698289, 37.49863151]]`).

Sample

Request

curl -v -G GET "https://dapi.kakao.com/v2/routing/walk" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "start_x=127.11119669891646" \
  --data-urlencode "start_y=37.394776627382875" \
  --data-urlencode "end_x=127.12629039752096" \
  --data-urlencode "end_y=37.4199323570413"

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "route": {
    "properties": {
      "totalDistance": 4025,
      "totalTime": 3914,
      "landingUrl": "https://map.kakao.com/link/by/walk/%EC%B6%9C%EB%B0%9C,37.394776627382875,127.11119669891646/%EB%8F%84%EC%B0%A9,37.4199323570413,127.12629039752096"
    },
    "legs": [
      {
        "properties": {
          "distance": 4025,
          "time": 3914
        },
        "steps": [
          {
            "properties": {
              "distance": 93,
              "guidance": "판교역 1번 출구까지 역사 내 이동",
              "time": 84,
              "x": 127.11119783,
              "y": 37.39477573
            },
            "path": {
              "points": [
                [127.11119783, 37.39477573],
                [127.11119779, 37.39474869],
                [127.1114835, 37.39474572],
                [127.11148211, 37.39533499]
                // ...
              ]
            }
          }
          // ...
        ]
      }
      // ...
    ]
  },
  "status": "OK"
}

Get bicycle routes

Basic information

Method	URL	Authorization
`GET`	`https://dapi.kakao.com/v2/routing/bicycle`	REST API key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key	-	-

Returns bicycle routes for the specified origin and destination coordinates.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Query parameter

Name	Type	Description	Required
start_x	`String`	Origin X coordinate.	O
start_y	`String`	Origin Y coordinate.	O
via_x	`String`	Waypoint X coordinates (Up to 5, separated by comma (`,`)).	X
via_y	`String`	Waypoint Y coordinates (Up to 5, separated by comma (`,`)).	X
end_x	`String`	Destination X coordinate.	O
end_y	`String`	Destination Y coordinate.	O
s_name	`String`	Origin name (Default: `출발`).	X
v_name	`String`	Waypoint names (Up to 5, separated by comma (`,`)).	X
e_name	`String`	Destination name (Default: `도착`).	X
input_coord	`String`	Input coordinate system, one of the following. `WGS84` (Default) `WTM` `TM` `WCONGNAMUL`	X
output_coord	`String`	Output coordinate system, one of the following. `WGS84` (Default) `WTM` `TM` `WCONGNAMUL`	X
route_mode	`String`	Search option, one of the following. `BIKE_ONLY` (Default): Bicycle roads first. `SHORTEST`: Shortest route. `ACCESSIBLE`: Easy route.	X

Response

The response for the Get bicycle routes API is the same as the Get walking routes API response.

Sample

Request

curl -v -G GET "https://dapi.kakao.com/v2/routing/bicycle" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "start_x=127.11119669891646" \
  --data-urlencode "start_y=37.394776627382875" \
  --data-urlencode "end_x=127.12629039752096" \
  --data-urlencode "end_y=37.4199323570413"

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "route": {
    "properties": {
      "totalDistance": 4155,
      "totalTime": 1242,
      "landingUrl": "https://map.kakao.com/link/by/bicycle/%EC%B6%9C%EB%B0%9C,37.394776627382875,127.11119669891646/%EB%8F%84%EC%B0%A9,37.4199323570413,127.12629039752096"
    },
    "legs": [
      {
        "properties": {
          "distance": 4155,
          "time": 1242
        },
        "steps": [
          {
            "properties": {
              "distance": 76,
              "guidance": "76m 이동",
              "time": 12,
              "x": 127.11143401,
              "y": 37.39488363
            },
            "path": {
              "points": [
                [127.11143401, 37.39488363],
                [127.11145558, 37.39495569],
                [127.11145156, 37.39529448],
                [127.11150469, 37.39532596]
                // ...
              ]
            }
          }
          // ...
        ]
      }
      // ...
    ]
  },
  "status": "OK"
}

Get static maps

Basic information

Method	URL	Authorization
`GET`	`https://dapi.kakao.com/v2/maps/staticmap`	REST API key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key	-	-

Returns a static map image reflecting the specified coordinates and options.

Kakao CI logo

The response image includes the Kakao CI logo. You can adjust its position with the logo_pos parameter, but you cannot remove it.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${REST_API_KEY}` REST API key as an authorization method.	O

Query parameter

Name	Type	Description	Required
center	`String`	Map center coordinate in `X,Y` format, separated by comma (`,`) (Example: `127.1105,37.3955`). Important: Either `center` or `markers` is required. If both parameters are omitted, an error is returned because the map center cannot be determined.	X
markers	`String`	Marker information. For how to configure `markers`, see `markers` inner parameters. Important: Either `center` or `markers` is required. If both parameters are omitted, an error is returned because the map center cannot be determined.	X
size	`String`	Image size in `{WIDTH}x{HEIGHT}` format (Maximum: `2048x1024`).	O
format	`String`	Response image format, one of the following. `png` (Default) `jpg`	X
logo_pos	`String`	Kakao CI logo position, one of the following. `BOTTOM_LEFT` (Default) `BOTTOM_RIGHT` `TOP_LEFT` `TOP_RIGHT`	X
scale	`Integer`	Image scale, one of the following. `1` `2` (Default) Reference: If `scale` is `2`, the response image size is twice the `size`.	X
lv	`Integer`	Map zoom level (Minimum: `1`, Maximum: `15`, Default: `3`).	X
coord	`String`	Coordinate system to apply to the request, one of the following. `WGS84` (Default) `WCONGNAMUL` `WTM` `TM`	X

`markers`inner parameters

The markers value separates keys and values with a colon (:) and connects parameters with a pipe (|). Multiple markers are connected with an ampersand (&), and you can connect up to 5 markers. See the parameter table and example below.

Name	Type	Description	Required
location	`String`	Marker coordinate in `X,Y` format, separated by comma (`,`). (Example: `127.1105,37.3955`).	O
option	`Boolean`	Whether to exclude the marker when automatically calculating the map area (`center`, `lv`). `true`: Exclude from area calculation. `false`: Include in area calculation (Default).	X

markers=location:127.1105,37.3955|option:false&markers=location:127.1120,37.3970|option:false

Response

Body

Static map image binary data

Sample

Request

curl -v -G GET "https://dapi.kakao.com/v2/maps/staticmap" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "center=127.1105,37.3955" \
  --data-urlencode "size=640x480" \
  --data-urlencode "markers=location:127.1105,37.3955|option:false"

Response

// HTTP/1.1 200 OK
// Content-Type: image/png (image/jpeg if the requested image format is jpg)

<binary image data>

See more

Reference for REST API

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

REST API

Address / Coordinate conversion

Convert address to coordinates

Basic information

Request

Header

Path variable

Query parameter

Response

Header

Body

Meta

Document

Address

RoadAddress

Sample

Request

Response

Convert coordinates to region code

Basic information

Request

Header

Path variable

Query parameter

Response

Header

Body

Meta

Document

Sample

Request

Response

Convert coordinates to address

Basic information

Request

Header

Path variable

Query parameter

Response

Header

Body

Meta

Document

Address

RoadAddress

Sample

Request

Response

Transform coordinates

Basic information

Request

Header

Path variable

Query parameter

Response

Header

Body

Meta

Document

Sample

Request

Response

Place search

Search place by keyword

Basic information

Request

Header

Path variable

Query parameter