AGENT SKILL

kakao-map

Kakao Local (장소 검색·주소-좌표 변환) + Kakao Mobility (자동차 길찾기) 를 k-skill-proxy 경유로 조회한다. 사용자 키 불필요.

License 许可
MIT
最近更新
2026-07-18
Stars
★ 0
Forks
1

01 前言 Front Matter

name
kakao-map
license
MIT
metadata
{ "phase": "v1", "locale": "ko-KR", "category": "transit" }
description
Kakao Local (장소 검색·주소-좌표 변환) + Kakao Mobility (자동차 길찾기) 를 k-skill-proxy 경유로 조회한다. 사용자 키 불필요.

02 资源文件 1

03 SKILL.md 正文

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 헤더) 로 인증한다.
  • 본 스킬은 조회 전용이다. 예약·결제·운전 자동화는 하지 않는다.

When to use

  • "강남역 근처 스타벅스 찾아줘" → keyword 검색 (x,y 중심)
  • "역삼동 카페 카테고리로 보여줘" → category 검색 (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 초과 위험)

Prerequisites

  • Python 3 표준 라이브러리만 사용 가능. JS/curl 호출도 동일하게 지원.
  • optional: KSKILL_PROXY_BASE_URL (self-host·별도 프록시 사용 시. 비우면 hosted 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 routes

endpoint 용도 주요 입력
GET /v1/kakao-map/search/keyword 키워드 장소 검색 q, optional x,y(중심좌표), radius(0~20000m), category_group_code, sort(accuracy|distance), page(1~45), 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 약국

Workflow

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 '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. 카테고리 검색

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. 좌표 → 주소

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. 좌표 → 행정구역

curl -fsS --get "${BASE}/v1/kakao-map/coord2region" \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979'

응답에 region_type(B=법정동, H=행정동) 별 결과가 들어있다.

5. 자동차 길찾기

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 등 회피 옵션 적용

6. 출력 포맷

장소 검색:

강남역 근처 스타벅스 5곳 (반경 500m, 가까운 순)
1) 스타벅스 강남R점 — 강남구 테헤란로 ... (120m, 02-...)
2) ...

자동차 길찾기:

자동차 경로: (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

Done when

  • 사용자 질문에 맞는 endpoint 1~2개를 선택해 호출했고, 응답을 사람-읽기 좋게 정리했다.
  • 좌표나 주소는 출처 endpoint를 함께 명시한다 (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 계열을 명시적으로 노출한다.

04 同仓库更多 Skills

om-scogo
om-scogo/skillsh-scraper

arxiv-search

Search arXiv physics, math, and computer science preprints using natural language queries. Powered by Valyu semantic search.

★ 0
om-scogo
om-scogo/skillsh-scraper

arxiv-search

Search arXiv physics, math, and computer science preprints using natural language queries. Powered by Valyu semantic search.

★ 0
om-scogo
om-scogo/skillsh-scraper

working-with-legacy-code

Safely change and test untested codebases using Feathers' "Working Effectively with Legacy Code". Use when the user mentions "legacy code", "no tests", "untested codebase", "how do I test this", "seams", "characterization tests", "golden master", "sprout method", "afraid to change this code", "monster method", "dependency breaking", or "inherited a messy codebase". Also trigger when changing code without tests safely, getting a class under test when constructors, statics, or singletons block it, adding features to tangled modules, or planning incremental test coverage for an old codebase. Covers the legacy-code change algorithm, seams, characterization tests, sprout/wrap, and dependency-breaking techniques. For refactoring code that already has tests, see refactoring-patterns. For day-to-day code quality, see clean-code.

★ 0
om-scogo
om-scogo/skillsh-scraper

working-with-legacy-code

Safely change and test untested codebases using Feathers' "Working Effectively with Legacy Code". Use when the user mentions "legacy code", "no tests", "untested codebase", "how do I test this", "seams", "characterization tests", "golden master", "sprout method", "afraid to change this code", "monster method", "dependency breaking", or "inherited a messy codebase". Also trigger when changing code without tests safely, getting a class under test when constructors, statics, or singletons block it, adding features to tangled modules, or planning incremental test coverage for an old codebase. Covers the legacy-code change algorithm, seams, characterization tests, sprout/wrap, and dependency-breaking techniques. For refactoring code that already has tests, see refactoring-patterns. For day-to-day code quality, see clean-code.

★ 0
om-scogo
om-scogo/skillsh-scraper

web-typography

Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", "typographic scale", or "the text is hard to read". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.

★ 0
om-scogo
om-scogo/skillsh-scraper

web-typography

Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", "typographic scale", or "the text is hard to read". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.

★ 0