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 발급
- Kakao Developers 접속
- 내 애플리케이션 → 앱 추가
- 앱 키 → 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 52. 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": {}
}사용 예시:
# 기본 검색
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "대형카페"
# 개수 지정
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "브런치 맛집" -Size 10
# 위치 기반 반경 검색
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "카페" -X "127.027" -Y "37.498" -Radius 1000
# 카테고리 필터링
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "카페" -CategoryGroupCode "CE7" -Size 15
# 페이지네이션
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "주차 가능한 카페" -Page 2 -Size 10에러 처리
API Key 없음
{
"ok": false,
"errorType": "MissingApiKey",
"message": "Set KAKAO_REST_API_KEY env var or create config.json",
"setupGuide": "https://developers.kakao.com/"
}API Key 잘못됨 (401/403)
{
"ok": false,
"errorType": "InvalidApiKey",
"message": "Invalid or expired API key",
"statusCode": 401
}API 호출 실패
{
"ok": false,
"errorType": "ApiError",
"message": "Failed to call Kakao API",
"details": "..."
}결과 없음
{
"ok": true,
"action": "SearchPlace",
"query": "존재하지않는장소12345",
"count": 0,
"items": []
}통합 예시 (상위 에이전트/챗봇)
# 주소 정규화 후 즐겨찾기 저장
$result = .\skills\kakao-local\scripts\kakao_local.ps1 -Action NormalizeAddress -Query "홍대입구역"
$data = $result | ConvertFrom-Json
if ($data.ok -and $data.count -gt 0) {
$best = $data.candidates[0]
# 즐겨찾기에 추가
$places = Get-Content ".\skills\kakao-local\data\places.json" -Raw | ConvertFrom-Json
$places | Add-Member -NotePropertyName "홍대" -NotePropertyValue @{
roadAddress = $best.roadAddress
x = $best.x
y = $best.y
savedAt = (Get-Date -Format "yyyy-MM-dd HH:mm:ss")
} -Force
$places | ConvertTo-Json -Depth 10 | Out-File ".\skills\kakao-local\data\places.json" -Encoding UTF8
Write-Host "✅ 즐겨찾기 저장: 홍대 → $($best.roadAddress)"
}
# 장소 검색 후 상위 3개 추천
$result = .\skills\kakao-local\scripts\kakao_local.ps1 -Action SearchPlace -Query "주차 가능한 카페" -Size 10
$data = $result | ConvertFrom-Json
if ($data.ok -and $data.count -gt 0) {
Write-Host "`n🌟 추천 장소 TOP 3:"
$top3 = $data.items | Select-Object -First 3
$index = 1
foreach ($place in $top3) {
Write-Host "`n[$index] $($place.name)"
Write-Host " 📍 $($place.roadAddress)"
Write-Host " 📞 $($place.phone)"
Write-Host " 🔗 $($place.placeUrl)"
$index++
}
# 캐시에 저장 (중복 검색 방지)
$cache = @{
query = $data.query
timestamp = (Get-Date -Format "yyyy-MM-dd HH:mm:ss")
ttl = 3600 # 1시간
results = $data.items
}
$cache | ConvertTo-Json -Depth 10 | Out-File ".\skills\kakao-local\data\cache.json" -Encoding UTF8
}테스트 시나리오
1. 주소 정규화 테스트
.\scripts\kakao_local.ps1 -Action NormalizeAddress -Query "서울 강남구 테헤란로 152"
# 기대: 도로명/지번 주소와 좌표 출력2. 장소 검색 테스트
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "대형카페" -Size 5
# 기대: 5개 카페 목록 출력3. API Key 미설정 테스트
# 환경변수 임시 제거
$backup = $env:KAKAO_REST_API_KEY
$env:KAKAO_REST_API_KEY = $null
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "카페"
# 기대: {"ok": false, "errorType": "MissingApiKey", ...}
# 복구
$env:KAKAO_REST_API_KEY = $backup4. 잘못된 API Key 테스트
$env:KAKAO_REST_API_KEY = "invalid_key_12345"
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "카페"
# 기대: {"ok": false, "errorType": "InvalidApiKey", ...}파일 구조
skills/kakao-local/
├── SKILL.md # 이 파일 (스킬 명세)
├── README.md # Quick Start
├── .gitignore # config.json 보호
├── scripts/
│ └── kakao_local.ps1 # 메인 스킬 스크립트
└── data/
├── config.json.template # API Key 설정 템플릿
├── places.json # 즐겨찾기 (선택)
└── cache.json # 검색 캐시 (선택)라이선스
MIT License
Publish-safe packaging note
This registry upload is "text-only" compatible: script sources are embedded under references/ as Markdown.
To use the skill locally: 1) Copy references/kakao_local.ps1.md content into a file: scripts/kakao_local.ps1 2) Copy references/config.json.template.md content into: data/config.json.template 3) Set API key via env var KAKAO_REST_API_KEY (recommended) or create data/config.json (gitignored).