5.7 KiB
5.7 KiB
기상청 Open API 키 발급 가이드 🇰🇷
📌 개요
날씨 위젯은 공공데이터포털 기상청 API를 사용합니다.
- 🌐 플랫폼: https://www.data.go.kr
- ✅ 완전 무료
- ✅ 일일 트래픽 제한 없음
- ✅ 실시간 한국 날씨 정보
참고: 기상청 API Hub (apihub.kma.go.kr)는 현재 접근 제한이 있어,
공공데이터포털의 기상청 API를 사용합니다.
🔑 API 키 발급 (5분 소요)
1️⃣ 공공데이터포털 회원가입
👉 https://www.data.go.kr
- 우측 상단 회원가입 클릭
- 이메일 입력 및 인증
- 약관 동의 후 가입 완료
2️⃣ API 활용신청
👉 https://www.data.go.kr/data/15084084/openapi.do
"기상청_단기예보 ((구)_동네예보) 조회서비스" 페이지에서:
- 활용신청 버튼 클릭
- 활용 목적:
기타 - 상세 기능 설명:
대시보드 날씨 위젯 - 신청 완료
⚠️ 승인까지 약 2-3시간 소요 (즉시 승인되는 경우도 있음)
3️⃣ 인증키 확인
👉 https://www.data.go.kr/mypage/myPageOpenAPI.do
마이페이지 > 오픈API > 인증키에서:
- 일반 인증키(Encoding) 복사
- 긴 문자열 전체를 복사하세요!
예시:
aBc1234dEf5678gHi9012jKl3456mNo7890pQr1234sTu5678vWx9012yZa3456bCd7890==
⚙️ 환경 변수 설정
방법 1: .env 파일 생성 (추천)
# 1. .env 파일 생성
cd /Users/leeheejin/ERP-node/backend-node
nano .env
2. 다음 내용 입력:
# Node 환경
NODE_ENV=development
# 서버 포트
PORT=8080
# 기상청 API 키 (발급받은 인증키를 여기에 붙여넣기)
KMA_API_KEY=여기에_발급받은_인증키를_붙여넣으세요
3. 저장 및 종료
Ctrl + O(저장)Enter(확인)Ctrl + X(종료)
방법 2: 명령어로 추가
cd /Users/leeheejin/ERP-node/backend-node
echo "KMA_API_KEY=여기에_발급받은_인증키_붙여넣기" >> .env
🔄 백엔드 재시작
docker restart pms-backend-mac
또는
cd /Users/leeheejin/ERP-node/backend-node
npm run dev
✅ 테스트
1. 브라우저에서 대시보드 접속
http://localhost:9771/admin/dashboard
2. 날씨 위젯 드래그 앤 드롭
- 오른쪽 사이드바에서 ☁️ 날씨 위젯 드래그
- 캔버스에 드롭
- 실시간 한국 날씨 표시 확인! 🎉
3. API 직접 테스트
curl "http://localhost:9771/api/open-api/weather?city=서울" \
-H "Authorization: Bearer YOUR_TOKEN"
응답 예시:
{
"success": true,
"data": {
"city": "서울",
"country": "KR",
"temperature": 18,
"feelsLike": 16,
"humidity": 65,
"pressure": 1013,
"weatherMain": "Clear",
"weatherDescription": "맑음",
"weatherIcon": "01d",
"windSpeed": 3.5,
"clouds": 10,
"timestamp": "2025-10-13T07:30:00.000Z"
}
}
🌍 지원 지역
한국 주요 도시
- 서울 (Seoul)
- 부산 (Busan)
- 인천 (Incheon)
- 대구 (Daegu)
- 광주 (Gwangju)
- 대전 (Daejeon)
- 울산 (Ulsan)
- 세종 (Sejong)
- 수원 (Suwon)
- 춘천 (Chuncheon)
- 제주 (Jeju)
영문/한글 모두 지원!
🔧 트러블슈팅
1. "기상청 API 키가 설정되지 않았습니다" 오류
원인: .env 파일에 API 키가 없음
해결방법:
# .env 파일 확인
cat /Users/leeheejin/ERP-node/backend-node/.env
# KMA_API_KEY가 있는지 확인
# 없으면 위 "환경 변수 설정" 참고하여 추가
2. "기상청 API 오류: SERVICE_KEY_IS_NOT_REGISTERED_ERROR" 오류
원인: API 키가 아직 승인되지 않았거나 잘못된 키
해결방법:
- 공공데이터포털에서 승인 상태 확인
- 일반 인증키(Encoding) 복사했는지 확인 (Decoding 아님!)
- 키 앞뒤에 공백 없는지 확인
- 백엔드 재시작
3. "지원하지 않는 지역입니다" 오류
원인: 등록되지 않은 도시명
해결방법:
- 위 "지원 지역" 목록 참고
- 영문 또는 한글 정확히 입력
- 예:
서울,Seoul,부산,Busan
4. API 키 재발급
공공데이터포털에서:
- 마이페이지 > 오픈API
- 해당 API 찾기
- 상세보기 > 인증키 재발급
📊 API 사용 현황 확인
👉 https://www.data.go.kr/mypage/myPageOpenAPIStatView.do
- 일일 트래픽: 무제한 ✅
- 서비스 상태: 정상
- 응답 속도: 평균 1초 이내
🎨 위젯 커스터마이징
기본 도시 변경
// DashboardDesigner.tsx
case 'weather': return '부산'; // 원하는 도시로 변경
새로고침 주기 변경
// WeatherWidget.tsx
<WeatherWidget
city="서울"
refreshInterval={300000} // 5분 (밀리초)
/>
📝 참고 링크
- 공공데이터포털: https://www.data.go.kr
- 기상청 API 신청: https://www.data.go.kr/data/15084084/openapi.do
- 마이페이지(인증키): https://www.data.go.kr/mypage/myPageOpenAPI.do
- 기상청 공식 사이트: https://www.weather.go.kr
💡 FAQ
Q: 승인이 언제 되나요? A: 보통 2-3시간, 빠르면 즉시 승인됩니다.
Q: 유료인가요? A: 완전 무료입니다! 트래픽 제한도 없어요.
Q: 해외 도시도 되나요? A: 아니요, 기상청 API는 한국 지역만 지원합니다.
Q: 실시간인가요? A: 실시간 관측 데이터를 제공합니다 (매시간 업데이트).
✅ 설정 완료 후 대시보드에서 실시간 한국 날씨를 확인하세요! 🌤️