kakao-map

Original：🇺🇸 English
Translated

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

11installs
Sourcenomadamas/k-skill
Added on

NPX Install

npx skill4agent add nomadamas/k-skill kakao-map

Tags

Translated version includes tags in frontmatter
kakao-map-apik-skill-proxylocation-searchdirections-apigeocoding

SKILL.md Content

View Translation Comparison →

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
(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약국

Workflow

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
를 추출해 사용자에게 보여준다.

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'

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
사용.

4. 좌표 → 행정구역

bash
curl -fsS --get "${BASE}/v1/kakao-map/coord2region" \
  --data-urlencode 'x=127.0276' \
  --data-urlencode 'y=37.4979'
응답에 
region_type
(B=법정동, H=행정동) 별 결과가 들어있다.

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

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

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 계열을 명시적으로 노출한다.