kakao-map

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

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. 키워드 검색

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