Back to Details

kakao-map

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Kakao Map

Kakao Map

What this skill does

本技能功能

Kakao Developers의 두 API를 
k-skill-proxy
경유로 묶어 다음 두 종류 질문에 답한다:
  1. 장소 검색 — 키워드/카테고리/좌표 기준으로 가게·시설·랜드마크를 찾고, 좌표↔주소·행정구역을 변환한다 (Kakao Local REST API).
  2. 자동차 길찾기 — 출발지·목적지 좌표를 받아 거리·소요시간·통행료·예상 택시 요금을 조회한다 (Kakao Mobility Directions API).
  • 운영자 
    KAKAO_REST_API_KEY
    를 proxy 서버에만 보관한다. 사용자는 키 발급 필요 없음.
  • 두 API 모두 같은 Kakao REST API key (KakaoAK 헤더) 로 인증한다.
  • 본 스킬은 조회 전용이다. 예약·결제·운전 자동화는 하지 않는다.
通过
k-skill-proxy
整合Kakao Developers的两个API，可回答以下两类问题：
  1. 地点搜索 — 基于关键词/分类/坐标查找店铺·设施·地标，实现坐标↔地址·行政区转换（Kakao Local REST API）。
  2. 汽车导航 — 接收出发地·目的地坐标，查询距离·耗时·通行费·预估出租车费用（Kakao Mobility Directions API）。
  • 运营方仅需在proxy服务器中存储
    KAKAO_REST_API_KEY
    ，用户无需申请密钥。
  • 两个API均使用同一Kakao REST API密钥（KakaoAK请求头）进行认证。
  • 本技能为仅查询型，不支持预约·支付·驾驶自动化操作。

When to use

使用场景

  • "강남역 근처 스타벅스 찾아줘" → keyword 검색 (x,y 중심)
  • "역삼동 카페 카테고리로 보여줘" → category 검색 (FD6/CE7 등)
  • "이 좌표가 어느 동/도로명 주소야?" → coord2address / coord2region
  • "강남역에서 시청까지 자동차로 얼마나 걸려?" → Kakao Mobility directions
  • "통행료 회피 경로로 알려줘" → avoid=toll (필요 시 priority=DISTANCE 병행)
  • "帮我找江南站附近的星巴克" → 关键词搜索（以x,y为中心）
  • "展示狎鸥亭洞的咖啡店分类" → 分类搜索（FD6/CE7等）
  • "这个坐标对应的是哪个洞/道路名地址？" → coord2address / coord2region
  • "从江南站到市厅开车需要多久？" → Kakao Mobility directions
  • "帮我规划避开通行费的路线" → avoid=toll（必要时可搭配priority=DISTANCE）

When NOT to use

非适用场景

  • 대중교통(지하철·버스) 경로 → Kakao Mobility는 자동차 전용. 대중교통은 
    korean-transit-route
    (ODsay) 사용
  • 도보·자전거 경로 (Kakao Mobility에 정식 API 없음)
  • 실시간 교통 상황을 1분 단위로 추적 (proxy cache 가 있음)
  • 카카오맵 외부 임베드/렌더링 (본 스킬은 데이터 조회만 함)
  • 대량 인덱싱/스크래핑 (Kakao 약관 위반 + 일일 quota 초과 위험)
  • 公共交通（地铁·公交）路线 → Kakao Mobility为汽车专用，公共交通请使用
    korean-transit-route
    （ODsay）
  • 步行·自行车路线（Kakao Mobility无正式API）
  • 实时交通状况分钟级追踪（存在proxy缓存）
  • Kakao Map外部嵌入/渲染（本技能仅支持数据查询）
  • 批量索引/爬取（违反Kakao条款+存在每日配额超额风险）

Prerequisites

前置条件

  • Python 3 표준 라이브러리만 사용 가능. JS/curl 호출도 동일하게 지원.
  • optional: 
    KSKILL_PROXY_BASE_URL
    (self-host·별도 프록시 사용 시. 비우면 hosted 
    https://k-skill-proxy.nomadamas.org
    기본).
  • 仅可使用Python 3标准库，同时支持JS/curl调用。
  • 可选配置：
    KSKILL_PROXY_BASE_URL
    （自托管·使用独立proxy时配置，留空则默认使用托管地址
    https://k-skill-proxy.nomadamas.org
    ）。

Required environment variables

所需环境变量

사용자 머신에는 필요 없다. 운영자 proxy 서버에 다음을 둔다:
  • KAKAO_REST_API_KEY
    — Kakao Developers REST API 키 (Local + Mobility 공용)
키가 없으면 모든 
/v1/kakao-map/*
및 
/v1/kakao-mobility/*
라우트가 
503 upstream_not_configured
를 돌려준다.
用户机器无需配置，仅需在运营方proxy服务器中配置：
  • KAKAO_REST_API_KEY
    — Kakao Developers REST API密钥（Local和Mobility共用）
若未配置密钥，所有
/v1/kakao-map/*
及
/v1/kakao-mobility/*
路由将返回
503 upstream_not_configured
。

Proxy routes

Proxy路由

endpoint용도주요 입력
GET /v1/kakao-map/search/keyword
키워드 장소 검색
q
, optional 
x
,
y
(중심좌표), 
radius
(020000m), 
category_group_code
, 
sort
(accuracy|distance), 
page
(145), 
size
(1~15)
GET /v1/kakao-map/search/category
카테고리 장소 검색 (좌표 중심 필수)
category_group_code
(예: FD6 음식점, CE7 카페), 
x
, 
y
, 
radius
(기본 500), 
sort
, 
page
, 
size
GET /v1/kakao-map/coord2address
좌표 → 도로명/지번 주소
x
, 
y
, optional 
input_coord
(WGS84 기본)
GET /v1/kakao-map/coord2region
좌표 → 행정구역(시/도/시군구/동)
x
, 
y
, optional 
input_coord
GET /v1/kakao-mobility/directions
자동차 길찾기
origin=x,y
, 
destination=x,y
, optional 
waypoints
(최대 5, 
|
구분), 
priority
(RECOMMEND|TIME|DISTANCE), 
car_fuel
(GASOLINE|DIESEL|LPG), 
car_hipass
(true|false), 
alternatives
(true|false), 
avoid
(ferries|toll|motorway|schoolzone|uturn; 
|
구분)
Kakao 카테고리 그룹 코드 (자주 쓰는 것):
코드의미
MT1대형마트
CS2편의점
PK6주차장
OL7주유소/충전소
SW8지하철역
BK9은행
CT1문화시설
AT4관광명소
AD5숙박
FD6음식점
CE7카페
HP8병원
PM9약국
端点用途主要输入
GET /v1/kakao-map/search/keyword
关键词地点搜索
q
，可选参数
x
,
y
（中心坐标）、
radius
（020000米）、
category_group_code
、
sort
（accuracy|distance）、
page
（145）、
size
（1~15）
GET /v1/kakao-map/search/category
分类地点搜索（必须以坐标为中心）
category_group_code
（例如：FD6 餐饮店、CE7 咖啡店）、
x
、
y
、
radius
（默认500）、
sort
、
page
、
size
GET /v1/kakao-map/coord2address
坐标→道路名/门牌号地址
x
、
y
，可选参数
input_coord
（默认WGS84）
GET /v1/kakao-map/coord2region
坐标→行政区（市/道/市郡区/洞）
x
、
y
，可选参数
input_coord
GET /v1/kakao-mobility/directions
汽车导航
origin=x,y
、
destination=x,y
，可选参数
waypoints
（最多5个，用
|
分隔）、
priority
（RECOMMEND|TIME|DISTANCE）、
car_fuel
（GASOLINE|DIESEL|LPG）、
car_hipass
（true|false）、
alternatives
（true|false）、
avoid
（ferries|toll|motorway|schoolzone|uturn；用
|
分隔）
常用Kakao分类组代码：
代码含义
MT1大型超市
CS2便利店
PK6停车场
OL7加油站/充电站
SW8地铁站
BK9银行
CT1文化设施
AT4旅游景点
AD5住宿
FD6餐饮店
CE7咖啡店
HP8医院
PM9药店

Workflow

工作流程

1. 키워드 검색

1. 关键词搜索

bash
BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/kakao-map/search/keyword" \
  --data-urlencode 'q=스타벅스' \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979' \
  --data-urlencode 'radius=500' \
  --data-urlencode 'sort=distance'
응답의 
documents[]
에서 
place_name
, 
road_address_name
, 
phone
, 
place_url
, 
distance
를 추출해 사용자에게 보여준다.
bash
BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/kakao-map/search/keyword" \
  --data-urlencode 'q=스타벅스' \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979' \
  --data-urlencode 'radius=500' \
  --data-urlencode 'sort=distance'
从响应的
documents[]
中提取
place_name
、
road_address_name
、
phone
、
place_url
、
distance
并展示给用户。

2. 카테고리 검색

2. 分类搜索

bash
curl -fsS --get "${BASE}/v1/kakao-map/search/category" \
  --data-urlencode 'category_group_code=FD6' \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979' \
  --data-urlencode 'radius=300'
bash
curl -fsS --get "${BASE}/v1/kakao-map/search/category" \
  --data-urlencode 'category_group_code=FD6' \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979' \
  --data-urlencode 'radius=300'

3. 좌표 → 주소

3. 坐标→地址

bash
curl -fsS --get "${BASE}/v1/kakao-map/coord2address" \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979'
documents[0].road_address.address_name
, 
documents[0].address.address_name
사용.
bash
curl -fsS --get "${BASE}/v1/kakao-map/coord2address" \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979'
使用
documents[0].road_address.address_name
、
documents[0].address.address_name
。

4. 좌표 → 행정구역

4. 坐标→行政区

bash
curl -fsS --get "${BASE}/v1/kakao-map/coord2region" \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979'
응답에 
region_type
(B=법정동, H=행정동) 별 결과가 들어있다.
bash
curl -fsS --get "${BASE}/v1/kakao-map/coord2region" \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979'
响应中包含按
region_type
（B=法定洞、H=行政洞）分类的结果。

5. 자동차 길찾기

5. 汽车导航

bash
curl -fsS --get "${BASE}/v1/kakao-mobility/directions" \
  --data-urlencode 'origin=126.9706,37.5559' \
  --data-urlencode 'destination=127.0276,37.4979' \
  --data-urlencode 'priority=RECOMMEND' \
  --data-urlencode 'avoid=toll'
응답에서 
routes[0].summary
를 읽는다:
  • distance
    (meter) → km 환산
  • duration
    (second) → 분 환산
  • fare.taxi
    , 
    fare.toll
    → 원
  • priority
    (요청한 값 echo)
  • avoid
    요청 시 
    toll
    등 회피 옵션 적용
bash
curl -fsS --get "${BASE}/v1/kakao-mobility/directions" \
  --data-urlencode 'origin=126.9706,37.5559' \
  --data-urlencode 'destination=127.0276,37.4979' \
  --data-urlencode 'priority=RECOMMEND' \
  --data-urlencode 'avoid=toll'
读取响应中的
routes[0].summary
：
  • distance
    （米）→ 转换为千米
  • duration
    （秒）→ 转换为分钟
  • fare.taxi
    、
    fare.toll
    → 韩元
  • priority
    （回显请求值）
  • 若请求
    avoid
    ，则会应用避开通行费等选项

6. 출력 포맷

6. 输出格式

장소 검색:
text
강남역 근처 스타벅스 5곳 (반경 500m, 가까운 순)
1) 스타벅스 강남R점 — 강남구 테헤란로 ... (120m, 02-...)
2) ...
자동차 길찾기:
text
자동차 경로: (126.9706,37.5559) → (127.0276,37.4979)
- 거리: 12.3km / 예상 소요시간: 25분
- 통행료: 1,200원 / 예상 택시요금: 18,500원
- 옵션: RECOMMEND, avoid=toll
- 조회 시각: 2026-05-23T14:00:00.000Z
地点搜索：
text
江南站附近星巴克5家（半径500米，由近及远）
1) 星巴克江南R店 — 江南区德黑兰路 ...（120米，02-...）
2) ...
汽车导航：
text
汽车路线：(126.9706,37.5559) → (127.0276,37.4979)
- 距离：12.3km / 预估耗时：25分钟
- 通行费：1,200韩元 / 预估出租车费用：18,500韩元
- 选项：RECOMMEND, avoid=toll
- 查询时间：2026-05-23T14:00:00.000Z

Failure modes

故障模式

  • KAKAO_REST_API_KEY
    미설정 → 
    503 upstream_not_configured
  • Kakao 인증 실패(401/403) → proxy가 
    503
    으로 변환 (key revoke / 쿼터 초과 신호)
  • 좌표/파라미터 형식 오류 → 
    400 bad_request
  • 출발지=도착지가 너무 가까움 (
    result_code=104
    등) → 
    502 upstream_semantic_error
    + 
    result_msg
  • Kakao 일일 쿼터 초과 → 
    502
    또는 
    503
    (proxy cache 가 있는 만큼 호출 빈도를 줄임)
  • 네트워크 실패 → 
    502 upstream_error
  • 未配置
    KAKAO_REST_API_KEY
    → 返回
    503 upstream_not_configured
  • Kakao认证失败（401/403）→ proxy转换为
    503
    （密钥吊销/配额超额信号）
  • 坐标/参数格式错误 → 返回
    400 bad_request
  • 出发地与目的地过近（
    result_code=104
    等）→ 返回
    502 upstream_semantic_error
    + 
    result_msg
  • Kakao每日配额超额 → 返回
    502
    或
    503
    （通过proxy缓存减少调用频率）
  • 网络故障 → 返回
    502 upstream_error

Done when

完成标准

  • 사용자 질문에 맞는 endpoint 1~2개를 선택해 호출했고, 응답을 사람-읽기 좋게 정리했다.
  • 좌표나 주소는 출처 endpoint를 함께 명시한다 (Kakao Local vs Kakao Mobility).
  • secret/token/.env 원문은 노출되지 않았다.
  • 자동차 외 이동 수단을 요청받으면 본 스킬의 범위 외임을 명시하고 
    korean-transit-route
    등 대체 안내.
  • 已选择1~2个匹配用户问题的端点调用，并将响应整理为易读格式。
  • 坐标或地址需同时注明来源端点（Kakao Local vs Kakao Mobility）。
  • 未暴露secret/token/.env原内容。
  • 若收到汽车以外的出行方式请求，需明确说明超出本技能范围，并推荐
    korean-transit-route
    等替代方案。

Notes

注意事项

  • Kakao Mobility는 자동차 전용 API다. 대중교통 길찾기는 별도 ODsay 기반 
    korean-transit-route
    스킬을 쓴다.
  • 무료 일일 쿼터(2026년 기준 Local 300,000건 / Mobility 1,000건) 안에서 proxy cache(기본 TTL 5분) + rate-limit(기본 60req/분) 으로 보호한다.
  • proxy 운영/환경변수는 k-skill 프록시 서버 가이드 참고.
  • /v1/kakao-local/geocode
    (기존)도 같은 키를 쓰며 여전히 사용 가능하다 (address → keyword 자동 fallback). 본 스킬은 그 위에 keyword/category/coord 계열을 명시적으로 노출한다.
  • Kakao Mobility是汽车专用API，公共交通导航需使用基于ODsay的独立
    korean-transit-route
    技能。
  • 在免费每日配额（2026年标准：Local 300,000次 / Mobility 1,000次）内，通过proxy缓存（默认TTL 5分钟）+ 速率限制（默认60请求/分钟）进行保护。
  • proxy运营/环境变量配置请参考k-skill代理服务器指南。
  • /v1/kakao-local/geocode
    （旧版）仍可使用同一密钥，本技能在其基础上明确暴露keyword/category/coord系列接口。