Kakao Local API Skill

OpenClaw Skill for Kakao Local (Places & Address) API

개요

카카오 로컬 API를 호출하여 주소 정규화 및 장소 검색을 수행하는 OpenClaw Skill입니다.

요구사항

• Windows
• PowerShell 5.0+
• curl.exe (Windows 10+ 기본 포함)
• Kakao Developers REST API Key

API Key 설정

중요: API Key는 스킬 파라미터로 전달하지 않습니다 (로그 노출 방지).

방법 1: 환경변수 (권장)

# 사용자 환경변수로 영구 설정
[Environment]::SetEnvironmentVariable("KAKAO_REST_API_KEY", "your_rest_api_key_here", "User")

# 또는 현재 세션에만 임시 설정
$env:KAKAO_REST_API_KEY = "your_rest_api_key_here"

방법 2: Config 파일

skills/kakao-local/data/config.json (create this file) 생성:

{
  "api_key": "your_rest_api_key_here"
}

⚠️ 주의: config.json은 .gitignore에 추가하여 커밋 금지

API Key 발급

1. Kakao Developers 접속
2. 내 애플리케이션 → 앱 추가
3. 앱 키 → REST API 키 복사

스킬 함수

1. NormalizeAddress (주소 정규화)

사용자가 입력한 주소를 정규화하여 도로명/지번 주소와 좌표로 변환합니다.

API 엔드포인트: GET https://dapi.kakao.com/v2/local/search/address.json

입력 파라미터:

• -Action "NormalizeAddress" (필수)
• -Query "주소 문자열" (필수)
• -Size 3 (선택, 기본값: 3)

출력 형식:

{
  "ok": true,
  "action": "NormalizeAddress",
  "query": "서울 강남구 테헤란로 152",
  "count": 2,
  "candidates": [
    {
      "roadAddress": "서울 강남구 테헤란로 152",
      "jibunAddress": "서울 강남구 역삼동 737",
      "x": "127.036557561809",
      "y": "37.4985995780801",
      "region": {
        "region1": "서울",
        "region2": "강남구",
        "region3": "역삼동"
      },
      "buildingName": "강남파이낸스센터",
      "zoneNo": "06236"
    }
  ],
  "raw": {}
}

사용 예시:

.\scripts\kakao_local.ps1 -Action NormalizeAddress -Query "판교역로 235"
.\scripts\kakao_local.ps1 -Action NormalizeAddress -Query "서울 강남구" -Size 5

2. SearchPlace (키워드 장소 검색)

키워드로 장소를 검색합니다. 위치 기반 반경 검색과 카테고리 필터링을 지원합니다.

API 엔드포인트: GET https://dapi.kakao.com/v2/local/search/keyword.json

입력 파라미터:

• -Action "SearchPlace" (필수)
• -Query "검색 키워드" (필수)
• -Size 5 (선택, 기본값: 5, 최대: 15)
• -Page 1 (선택, 기본값: 1, 최대: 45)
• -X "127.027" (선택, 중심 경도)
• -Y "37.498" (선택, 중심 위도)
• -Radius 1000 (선택, 검색 반경(m), 최대: 20000)
• -CategoryGroupCode "CE7" (선택, 카테고리 그룹 코드)

카테고리 그룹 코드:

• MT1: 대형마트
• CS2: 편의점
• PS3: 어린이집, 유치원
• SC4: 학교
• AC5: 학원
• PK6: 주차장
• OL7: 주유소, 충전소
• SW8: 지하철역
• BK9: 은행
• CT1: 문화시설
• AG2: 중개업소
• PO3: 공공기관
• AT4: 관광명소
• AD5: 숙박
• FD6: 음식점
• CE7: 카페
• HP8: 병원
• PM9: 약국

출력 형식:

{
  "ok": true,
  "action": "SearchPlace",
  "query": "대형카페",
  "count": 5,
  "totalCount": 128,
  "isEnd": false,
  "items": [
    {
      "id": "8739036",
      "name": "스타벅스 강남점",
      "roadAddress": "서울 강남구 테헤란로 152",
      "jibunAddress": "서울 강남구 역삼동 737",
      "x": "127.036557561809",
      "y": "37.4985995780801",
      "phone": "02-1234-5678",
      "categoryName": "음식점 > 카페",
      "placeUrl": "http://place.map.kakao.com/8739036",
      "distance": "245"
    }
  ],
  "raw": {}
}