基于 k-skill 与 k-skill-proxy 的 Kakao Map 技能实战：Kakao Local 场所搜索与 Kakao Mobility 汽车导航查询指南

基于 k-skill 与 k-skill-proxy 的 Kakao Map 技能实战Kakao Local 场所搜索与 Kakao Mobility 汽车导航查询指南【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本指南围绕 k-skill 技能集k-skill-cli中的kakao-map技能展开讲解如何通过k-skill-proxy网关统一封装 Kakao Developers 的 Local场所搜索、坐标↔地址/行政区域转换与 Mobility汽车路径规划两套 REST API使 LLM Agent 无需自行申请密钥即可完成「找店」「坐标转地址」「汽车导航查询」三类任务。读完本文你将掌握该技能的全部 5 个 Proxy 端点、参数取值边界、六步实战调用流程、输出格式规范以及底层代理的密钥注入、缓存与限流实现原理。技能定位一条技能两大 Kakao API零密钥使用门槛kakao-map是 k-skill 面向韩国用户场景的「地图与出行」类技能metadata.category: transit其核心设计思想是把密钥保管与上游调用全部下沉到代理服务器。用户与 Agent 机器上不需要任何 Kakao 密钥只需向k-skill-proxy发起 HTTP 请求代理会在服务端注入Authorization: KakaoAK key头后转发至 Kakao 官方 API见 kakao-map/skill.json 中的profiles: [proxy, vault, action:booking]与技能描述。该技能回答两类问题场所搜索——基于关键词 / 分类 / 坐标查找店铺、设施、地标并完成坐标 ↔ 地址·行政区域的双向转换Kakao Local REST API。汽车导航——给定出发地与目的地坐标查询距离、预计耗时、通行费与预估出租车费Kakao Mobility Directions API。需要强调的边界本技能是只读查询조회 전용不执行任何预订、支付或驾驶自动化Kakao Mobility 仅支持汽车公共交通路径请使用独立的korean-transit-route技能基于 ODsay。使用场景与禁用场景适用场景When to use用户请求示例对应能力강남역 근처 스타벅스 찾아줘找江南站附近星巴克keyword 关键词搜索以 x,y 为中心역삼동 카페 카테고리로 보여줘按分类看驿三洞咖啡馆category 分类搜索FD6/CE7 等이 좌표가 어느 동/도로명 주소야?这个坐标是哪个洞/道路名地址coord2address / coord2region강남역에서 시청까지 자동차로 얼마나 걸려?开车从江南站到市厅多久Kakao Mobility directions통행료 회피 경로로 알려줘避开收费路线的路径avoidtoll必要时可叠加priorityDISTANCE禁用场景When NOT to use公共交通地铁/巴士路径Kakao Mobility 是汽车专用API公共交通应使用基于 ODsay 的korean-transit-route技能步行/自行车路径Kakao Mobility 无对应正式 API按分钟级追踪实时路况代理层存在缓存不适合高频实时追踪Kakao Map 外部嵌入/渲染本技能只做数据查询不提供地图渲染批量索引/爬取违反 Kakao 服务条款且易触发每日配额超限。前置条件与环境变量客户端Agent 侧无需密钥技能运行只需 Python 3 标准库即可发起请求JS/curl 调用方式完全等同代理是纯 HTTP 接口。可选环境变量KSKILL_PROXY_BASE_URL——自托管或使用独立代理时的基地址留空时默认使用托管地址https://k-skill-proxy.nomadamas.org。代理服务器运营者侧必需变量变量说明KAKAO_REST_API_KEYKakao Developers 的 REST API 密钥Local 与 Mobility 两个上游共用见 packages/k-skill-proxy/README.md 第 91 行的环境变量清单若代理服务器未配置该密钥则所有/v1/kakao-map/*与/v1/kakao-mobility/*路由统一返回503 upstream_not_configured。这一行为在源码中有直接对应fetchKakaoLocalEndpoint与fetchKakaoMobilityDirections在apiKey为空时抛出upstream_not_configured错误并映射为 503见 packages/k-skill-proxy/src/kakao-map.js 与 packages/k-skill-proxy/src/kakao-map.js。Proxy 路由与参数总览技能面向客户端暴露 5 个 GET 端点托管路径前缀为https://k-skill-proxy.nomadamas.orgendpoint用途主要输入GET /v1/kakao-map/search/keyword关键词场所搜索q可选x,y中心坐标、radius0~20000m、category_group_code、sortaccuracy|distance、page1~45、size1~15GET /v1/kakao-map/search/category分类场所搜索坐标中心必填category_group_code如 FD6 餐厅、CE7 咖啡、x、y、radius默认 500、sort、page、sizeGET /v1/kakao-map/coord2address坐标 → 道路名/地番地址x、y可选input_coord默认 WGS84GET /v1/kakao-map/coord2region坐标 → 行政区域市/道/市郡区/洞x、y可选input_coordGET /v1/kakao-mobility/directions汽车路径规划originx,y、destinationx,y可选waypoints最多 5 个\|分隔、priorityRECOMMEND|TIME|DISTANCE、car_fuelGASOLINE|DIESEL|LPG、car_hipasstrue|false、alternativestrue|false、avoidferries|toll|motorway|schoolzone|uturn\|分隔从源码看这些端点在 packages/k-skill-proxy/src/server.js 处逐一注册且各端点有独立的参数归一化函数normalizeKakaoKeywordSearchQuery、normalizeKakaoCategorySearchQuery、normalizeKakaoCoordToAddressQuery、normalizeKakaoMobilityDirectionsQuery统一把lng/longitude、lat/latitude、query、limit、categoryGroupCode、carFuel、carHipass等别名规整为 Kakao 上游认可的字段名方便客户端以多种命名风格传参。Kakao 分类组代码常用代码含义代码含义MT1大型超市FD6餐厅CS2便利店CE7咖啡PK6停车场HP8医院OL7加油站/充电站PM9药店SW8地铁站CT1文化设施BK9银行AT4旅游景点AD5住宿代理源码 packages/k-skill-proxy/src/kakao-map.js 中维护了完整的 18 个官方分类代码集合KAKAO_CATEGORY_GROUP_CODES除上表外还包括 PS3幼儿园/托儿所、SC4学校、AC5补习班、AG2中介机构、PO3公共机构。传入集合外的代码会被参数校验直接拒绝400bad_request这正是 packages/k-skill-proxy/test/server.test.js 中category_group_codeXX9用例被断言为 400 的原因。六步实战调用流程以下所有命令均以KSKILL_PROXY_BASE_URL或默认托管地址为基址。注意curl -fsS --get配合--data-urlencode可自动完成 URL 编码避免韩文关键词与坐标符号的转义问题。1. 关键词搜索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 x127.0276 \ --data-urlencode y37.4979 \ --data-urlencode radius500 \ --data-urlencode sortdistance从响应documents[]中提取place_name、road_address_name、phone、place_url、distance呈现给用户。源码中normalizeKakaoKeywordSearchQuery对参数做了三类约束值得留意q为必填x/y必须成对出现且为合法经纬度经度 ±180、纬度 ±90否则抛错radius取值范围 0~20000 米且依赖坐标sortdistance也强制要求坐标packages/k-skill-proxy/src/kakao-map.js。测试用例 packages/k-skill-proxy/test/server.test.js 覆盖了「只给 x」「非法 sort」「radius 越界」「radius 无坐标」等 400 场景。2. 分类搜索curl -fsS --get ${BASE}/v1/kakao-map/search/category \ --data-urlencode category_group_codeFD6 \ --data-urlencode x127.0276 \ --data-urlencode y37.4979 \ --data-urlencode radius300与关键词搜索不同分类搜索的x/y为必填且radius有默认值 500源码parseBoundedPositiveInteger的defaultValue: 500。测试用例 packages/k-skill-proxy/test/server.test.js 验证了「缺分类」「缺坐标」等失败分支。3. 坐标 → 地址curl -fsS --get ${BASE}/v1/kakao-map/coord2address \ --data-urlencode x127.0276 \ --data-urlencode y37.4979使用documents[0].road_address.address_name道路名地址与documents[0].address.address_name地番地址。可选参数input_coord决定输入坐标的坐标系源码校验只接受WGS84、WCONGNAMUL、CONGNAMUL、WTM、TM五种packages/k-skill-proxy/src/kakao-map.js。4. 坐标 → 行政区域curl -fsS --get ${BASE}/v1/kakao-map/coord2region \ --data-urlencode x127.0276 \ --data-urlencode y37.4979响应按region_type分组B表示法政洞법정동H表示行政洞행정동两者用途不同——法政洞对应不动产登记行政洞对应居民生活服务口径。5. 汽车路径规划curl -fsS --get ${BASE}/v1/kakao-mobility/directions \ --data-urlencode origin126.9706,37.5559 \ --data-urlencode destination127.0276,37.4979 \ --data-urlencode priorityRECOMMEND \ --data-urlencode avoidtoll读取响应中routes[0].summary的以下字段distance米→ 换算为公里duration秒→ 换算为分钟fare.taxi、fare.toll韩元priority回显请求值请求avoid时确认toll等回避选项生效源码对origin/destination按x,y格式解析逗号分隔、两项、数值、坐标范围四重校验waypoints最多 5 个且同样逐项校验avoid的合法值枚举在KAKAO_MOBILITY_AVOID集合中ferries/toll/motorway/schoolzone/uturnpriority、car_fuel、car_hipass、alternatives也都有对应枚举白名单packages/k-skill-proxy/src/kakao-map.js 与 packages/k-skill-proxy/src/kakao-map.js。测试 packages/k-skill-proxy/test/server.test.js 覆盖了priorityCHEAP、avoidunpaved、空 waypoints、越界 waypoints 等非法输入。6. 输出格式场所搜索结果강남역 근처 스타벅스 5곳 (반경 500m, 가까운 순) 1) 스타벅스 강남R점 — 강남구 테헤란로 ... (120m, 02-...) 2) ...汽车路径结果자동차 경로: (126.9706,37.5559) → (127.0276,37.4979) - 거리: 12.3km / 예상 소요시간: 25분 - 통행료: 1,200원 / 예상 택시요금: 18,500원 - 옵션: RECOMMEND, avoidtoll - 조회 시각: 2026-05-23T14:00:00.000Z格式要点列出数量与排序口径、单条结果的名称—地址—距离—电话路径结果应包含距离/耗时/费用折算与选项回显并附查询时间戳。失败模式对照失败场景返回说明代理未配置KAKAO_REST_API_KEY503 upstream_not_configured所有/v1/kakao-map/*、/v1/kakao-mobility/*路由统一响应Kakao 认证失败401/403转为503源码中response.status 401 \|\| 403 ? 503 : 502是 key 被吊销或配额超限的信号坐标/参数格式错误400 bad_request由各normalize*函数的参数校验抛出出发地目的地过近result_code104等502 upstream_semantic_errorresult_msgKakao Mobility 在 HTTP 200 内部返回routes[].result_code ! 0代理检测后转语义错误packages/k-skill-proxy/src/kakao-map.jsKakao 每日配额超限502或503依赖代理缓存降低调用频率网络/上游异常502 upstream_errorfetch 异常或非 2xx 上游响应附带upstream.status_code与响应片段前 200 字符kakao-map上游调用统一设置 20 秒超时AbortSignal.timeout(20000)代理会以k-skill-proxy/kakao-map或k-skill-proxy/kakao-mobility的 User-Agent 标识自身便于上游排查packages/k-skill-proxy/src/kakao-map.js。完成标准Done when根据用户问题选择 1~2 个合适端点完成调用并将响应整理为易读文本坐标或地址类结果需注明来源端点Kakao Local vs Kakao Mobility未泄露任何 secret/token/.env 原文——密钥仅由代理在服务端注入客户端响应中不出现用户请求汽车以外的交通方式时明确说明超出本技能范围并引导至korean-transit-route等替代技能。底层机制纵深缓存、限流与密钥安全代理侧缓存handleKakaoLocalEndpointRoute与 directions 路由均先以makeCacheKey({ route, ...normalized })生成缓存键命中后直接返回缓存体并标记proxy.cache.hit true见 packages/k-skill-proxy/src/server.js 与 packages/k-skill-proxy/src/server.js。默认 TTL 为 5 分钟响应体中附带proxy元信息name、cache.hit、cache.ttl_ms、requested_at便于 Agent 判断结果时效性。配额保护以 2026 年 Kakao 免费日配额为参考Local 约 30 万件/日Mobility 约 1,000 件/日。由于 Mobility 配额远小于 Local代理在缓存之外还施加默认 60 请求/分钟的 rate-limit 保护详见 docs/features/kakao-map.md 与 docs/features/k-skill-proxy.md。Agent 侧应复用相近查询、避免对同一origin/destination反复请求。兼容旧端点代理同时保留旧版GET /v1/kakao-local/geocode地址 → 坐标它使用同一把KAKAO_REST_API_KEY且在地址解析失败时会自动回退为关键词搜索。kakao-map技能则在此基础上显式暴露 keyword/category/coord 系列端点职责更清晰、参数更可预期。运营者部署指引自托管代理时在服务器环境设置KAKAO_REST_API_KEY后启动k-skill-proxy并在客户端通过KSKILL_PROXY_BASE_URL指向自建地址若使用托管服务则无需任何配置。代理的完整部署、缓存 TTL、rate-limit 等运维细节请参考 k-skill 代理服务器指南配套代理实现见 packages/k-skill-proxy/README.md。技能的法务边界商标声明与自动化收集限制见 kakao-map/references/DISCLAIMER.md 与 kakao-map/references/TRADEMARK-LEGAL-STATEMENT.md。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考