# 기상청 날씨 API 연동 가이드 > **작성일**: 2026-02-22 > **상태**: 운영 중 > **관련 코드**: `mng/app/Services/WeatherService.php` --- ## 1. 개요 ### 1.1 목적 SAM 대시보드의 주간 날씨 위젯에서 사용하는 기상청 공공데이터 API의 동작 특성과 구현 시 주의사항을 기록한다. ### 1.2 사용 API | API | 엔드포인트 | 용도 | |-----|----------|------| | 단기예보 | `VilageFcstInfoService_2.0/getVilageFcst` | 오늘 ~ D+3 날씨 | | 중기기온 | `MidFcstInfoService/getMidTa` | D+4 ~ D+10 최저/최고기온 | | 중기육상예보 | `MidFcstInfoService/getMidLandFcst` | D+4 ~ D+10 날씨/강수확률 | ### 1.3 서비스 키 설정 ```php // config/services.php 'kma' => [ 'service_key' => env('KMA_SERVICE_KEY'), ], ``` --- ## 2. 핵심 주의사항 (발표시각별 데이터 범위) > **경고: 기상청 중기예보 API는 발표시각에 따라 제공하는 날짜 범위가 다르다!** ### 2.1 발표시각별 데이터 커버리지 ``` 시간대 │ 단기예보(0200) │ 중기예보(0600) │ 중기예보(1800) ─────────────┼────────────────┼────────────────┼──────────────── D+0 (오늘) │ ✅ TMN/TMX/SKY │ │ D+1 (내일) │ ✅ TMN/TMX/SKY │ │ D+2 (모레) │ ✅ TMN/TMX/SKY │ │ D+3 │ ⚠️ SKY만 │ ❌ 없음 │ ❌ 없음 D+4 │ ❌ 없음 │ ✅ 있음 │ ❌ 없음 D+5 │ ❌ 없음 │ ✅ 있음 │ ✅ 있음 D+6 │ ❌ 없음 │ ✅ 있음 │ ✅ 있음 D+7 ~ D+10 │ ❌ 없음 │ ✅ 있음 │ ✅ 있음 ``` ### 2.2 핵심 문제: D+3 ~ D+4 사각지대 ``` ┌─────────────────────────────────────────────────────────┐ │ 데이터 커버리지 갭 │ │ │ │ 단기(0200): ████████████████░░░░░░░░░░░░░░░░░░░░░░░░ │ │ D+0 D+1 D+2 D+3 │ │ ↑ SKY만, TMN/TMX 없음 │ │ │ │ 중기(0600): ░░░░░░░░░░░░░░░░░░░░████████████████████ │ │ D+4 D+5 D+6 ... │ │ ↑ │ │ D+3 = 사각지대! │ │ │ │ 중기(1800): ░░░░░░░░░░░░░░░░░░░░░░░░░████████████████ │ │ D+5 D+6 ... │ │ ↑ ↑ │ │ D+3, D+4 = 사각지대! │ └─────────────────────────────────────────────────────────┘ ``` ### 2.3 해결 방법: 다중 발표 데이터 병합 18시 이후에는 18시 발표에 D+4 데이터가 없으므로, **여러 발표시각의 데이터를 병합**해야 한다. ``` 병합 전략 (최신 우선): 1. 18시 발표 데이터 적용 (D+5 ~ D+10) 2. 06시 발표 데이터로 빈 필드 보충 (D+4) 3. 전일 18시 발표로 추가 보충 (필요 시) ``` --- ## 3. 단기예보 API 특성 ### 3.1 발표시각 | base_time | 설명 | |-----------|------| | `0200` | 새벽 2시 발표 (현재 사용 중) | | `0500`, `0800`, `1100`, `1400`, `1700`, `2000`, `2300` | 3시간 간격 발표 | ### 3.2 카테고리 | 카테고리 | 설명 | 비고 | |---------|------|------| | `TMN` | 일 최저기온 | D+0 ~ D+2만 제공 | | `TMX` | 일 최고기온 | D+0 ~ D+2만 제공 | | `SKY` | 하늘상태 | 1=맑음, 3=구름많음, 4=흐림 | | `PTY` | 강수형태 | 0=없음, 1=비, 2=비/눈, 3=눈, 4=소나기 | | `POP` | 강수확률 | 0~100% | ### 3.3 주의: D+3 부분 데이터 단기예보 `base_time=0200`은 D+3 날짜의 SKY/PTY/POP 데이터를 포함할 수 있지만, **TMN/TMX는 없다**. 코드에서 D+3 단기예보 데이터를 사용할 때 기온이 없을 수 있음에 주의한다. ```php // ⚠️ D+3 단기예보: tmn=null, tmx=null, sky=있음, pty=있음 $grouped[$fcstDate] = [ 'tmn' => null, // TMN 카테고리가 D+3에 없음 'tmx' => null, // TMX 카테고리가 D+3에 없음 'sky' => 1, // SKY는 D+3에도 있음 'pty' => 0, // PTY는 D+3에도 있음 ]; ``` --- ## 4. 중기예보 API 특성 ### 4.1 발표시각 - **06시**: 매일 06:00 발표 → D+4 ~ D+10 제공 - **18시**: 매일 18:00 발표 → D+5 ~ D+10 제공 > **경고: 18시 발표는 D+3, D+4 데이터를 제공하지 않는다!** ### 4.2 응답 필드 구조 **중기기온 (`getMidTa`)** ``` taMin3, taMax3 ← D+3 (06시 발표에서도 없을 수 있음) taMin4, taMax4 ← D+4 (06시 발표에 있음, 18시 발표에 없음) taMin5, taMax5 ← D+5 ... taMin10, taMax10 ← D+10 ``` **중기육상예보 (`getMidLandFcst`)** ``` wf3Am, wf3Pm, rnSt3Am, rnSt3Pm ← D+3 (없을 수 있음) wf4Am, wf4Pm, rnSt4Am, rnSt4Pm ← D+4 (06시에만) wf5Am, wf5Pm, rnSt5Am, rnSt5Pm ← D+5 wf6Am, wf6Pm, rnSt6Am, rnSt6Pm ← D+6 wf7, rnSt7 ← D+7 (AM/PM 구분 없음) wf8, rnSt8 ← D+8 wf9, rnSt9 ← D+9 wf10, rnSt10 ← D+10 ``` ### 4.3 실측 데이터 (2026-02-22 기준) ``` 06시 발표 18시 발표 Day+3 (수): taMin=없음 taMin=없음 Day+4 (목): taMin=2, taMax=14 taMin=없음, taMax=없음 Day+5 (금): taMin=4, taMax=13 taMin=4, taMax=13 Day+6 (토): taMin=4, taMax=13 taMin=3, taMax=14 ``` --- ## 5. 데이터 흐름 아키텍처 ### 5.1 전체 흐름 ``` HTMX 요청 │ └→ GET /dashboard/weather │ └→ DashboardWeatherController::weather() │ └→ WeatherService::getWeeklyForecast() │ ├→ 캐시 확인 (weather_forecast_7days) │ ├ 완전한 데이터: 3시간 TTL │ └ 불완전 데이터: 10분 TTL │ └→ buildForecast() │ ├→ fetchShortForecast() ← D+0 ~ D+3(부분) ├→ fetchMidTemperature() ← D+4 ~ D+10 (병합) └→ fetchMidLandForecast() ← D+4 ~ D+10 (병합) │ └→ 7일 데이터 조합 ├ 단기 TMN/TMX 있으면 → 단기예보 우선 └ 단기 TMN/TMX 없으면 → 중기예보 우선 ``` ### 5.2 관련 파일 | 파일 | 역할 | |------|------| | `app/Services/WeatherService.php` | API 호출, 데이터 병합, 캐싱 | | `app/Http/Controllers/DashboardWeatherController.php` | HTMX 요청 처리 | | `resources/views/dashboard/partials/weather.blade.php` | 7일 날씨 카드 렌더링 | | `resources/views/dashboard/partials/weather-icon.blade.php` | 날씨 SVG 아이콘 | --- ## 6. 구현 규칙 ### R1. 중기예보는 반드시 다중 발표 병합 단일 발표시각만 사용하면 D+4 데이터가 빠질 수 있다. 반드시 여러 발표시각의 응답을 병합한다. ```php // ✅ 올바른 방식: 최신 발표 우선, 이전 발표로 빈 필드 보충 private function fetchMidMerged(string $baseUrl, string $regId): array { $merged = []; foreach ($this->getMidBaseTmFcCandidates() as $tmFc) { $items = $this->callApi($baseUrl, [...]); foreach ($items[0] as $key => $value) { if ($value !== null && $value !== '' && !isset($merged[$key])) { $merged[$key] = $value; // 최신 데이터 우선 } } } return $merged; } ``` ```php // ❌ 잘못된 방식: 첫 번째 비어있지 않은 응답만 사용 foreach ($tmFcList as $tmFc) { $items = $this->callApi(...); if (!empty($items)) return $items[0]; // D+4 데이터 누락! } ``` ### R2. 단기예보 데이터 완전성 검증 단기예보가 D+3/D+4에 SKY/PTY만 반환하고 TMN/TMX가 없는 경우, 해당 날의 icon/pop은 신뢰할 수 없다. TMN/TMX 유무로 "완전한 단기예보"인지 판단한다. ```php // ✅ 단기예보 TMN/TMX가 있으면 신뢰 가능한 데이터 $shortComplete = $shortData && ($shortData['tmn'] !== null || $shortData['tmx'] !== null); if ($shortComplete) { // 단기예보 icon, pop 사용 } else { // 중기예보 icon, pop 우선 사용 } ``` ### R3. 불완전 데이터는 짧은 캐시 7일 중 기온 데이터가 없는 날이 있으면 10분만 캐시하여 빠른 재시도를 유도한다. ```php $hasIncomplete = collect($forecasts)->contains( fn ($fc) => $fc['tmn'] === null && $fc['tmx'] === null && $fc['icon'] === null ); Cache::put('weather_forecast_7days', $forecasts, $hasIncomplete ? 600 : 10800); ``` ### R4. 날씨 문자열 → 아이콘 매핑 | 중기예보 문자열 | 아이콘 | 비고 | |---------------|-------|------| | `맑음` | `sun` | | | `구름많음`, `구름` | `cloud-sun` | | | `흐림` | `cloud` | | | `비`, `소나기` | `rain` | | | `눈` | `snow` | | | `비/눈` (눈+비 포함) | `sleet` | `str_contains` 순서 주의 | --- ## 7. 트러블슈팅 ### 7.1 특정 요일만 "준비 중" 표시 **원인**: 18시 이후 중기예보가 해당 요일 데이터를 미제공 **해결**: 06시 발표 데이터 병합 확인, 캐시 클리어 (`php artisan cache:clear`) ### 7.2 전체 날씨 미표시 ("날씨 정보를 불러올 수 없습니다") **원인**: `KMA_SERVICE_KEY` 미설정 또는 API 호출 실패 **해결**: `.env`의 `KMA_SERVICE_KEY` 확인, 기상청 API 상태 점검 ### 7.3 기온 데이터 갱신 안 됨 **원인**: 3시간 캐시 (`weather_forecast_7days`) **해결**: `docker exec sam-mng-1 php artisan cache:clear` ### 7.4 디버깅 명령어 ```bash # 현재 날씨 데이터 확인 docker exec sam-mng-1 php artisan tinker --execute=" \$ws = app(App\Services\WeatherService::class); \$forecasts = \$ws->getWeeklyForecast(); foreach (\$forecasts as \$i => \$fc) { \$dt = \Carbon\Carbon::createFromFormat('Ymd', \$fc['date']); \$day = ['일','월','화','수','목','금','토'][\$dt->dayOfWeek]; echo \"[\$i] \$day (\$fc[date]) tmn=\" . (\$fc['tmn'] ?? 'NULL') . \" tmx=\" . (\$fc['tmx'] ?? 'NULL') . \" icon=\" . (\$fc['icon'] ?? 'NULL') . \" pop=\" . (\$fc['pop'] ?? 0) . \"\n\"; } " # 캐시 강제 클리어 후 재조회 docker exec sam-mng-1 php artisan cache:clear ``` --- ## 8. 변경 이력 | 날짜 | 내용 | |------|------| | 2026-02-22 | 최초 작성. 중기예보 발표시각별 데이터 범위 차이 발견 및 병합 로직 구현 | --- ## 관련 문서 - 기상청 공공데이터 포털: https://www.data.go.kr - 단기예보 API: `VilageFcstInfoService_2.0` - 중기예보 API: `MidFcstInfoService` --- **최종 업데이트**: 2026-02-22