# 🔌 API 연동 가이드

## 📊 현재 상태

### ✅ 작동 중인 API

1. **기상청 특보 API** (완벽 작동!)
   - API 키: `ogdXr2e9T4iHV69nvV-IwA`
   - 상태: ✅ 14건 실시간 특보 수신 중
   - 제공 데이터: 대설/강풍/한파/태풍/폭염 특보

2. **한국은행 환율 API** (완벽 작동!)
   - API 키: `OXIGPQXH68NUKVKL5KT9`
   - 상태: ✅ 환율 위젯 작동 중

### ⚠️ 더미 데이터 사용 중

3. **교통사고 정보**
   - 한국도로공사 API: ❌ 서버 호출 차단
   - 현재 상태: 더미 데이터 (2건)

4. **도로공사 정보**
   - 한국도로공사 API: ❌ 서버 호출 차단
   - 현재 상태: 더미 데이터 (2건)

---

## 🚀 실시간 교통정보 연동하기

### 📌 국토교통부 ITS API (추천!)

#### 1단계: API 신청
1. https://www.data.go.kr/ 접속
2. 검색: **"ITS 돌발정보"** 또는 **"실시간 교통정보"**
3. **활용신청** 클릭
4. **승인 대기 (1~2일)**

#### 2단계: API 키 추가
승인 완료되면 `.env` 파일에 추가:

```env
# 국토교통부 ITS API 키
ITS_API_KEY=발급받은_API_키
```

#### 3단계: 서버 재시작
```bash
docker restart pms-backend-mac
```

#### 4단계: 확인
- 로그에서 `✅ 국토교통부 ITS 교통사고 API 응답 수신 완료` 확인
- 더미 데이터 대신 실제 데이터가 표시됨!

---

## 🔍 한국도로공사 API 문제

### 발급된 키
```
EXWAY_API_KEY=7820214492
```

### 문제 상황
- ❌ 서버/백엔드에서 호출 시: `Request Blocked` (400)
- ❌ curl 명령어: `Request Blocked`
- ❌ 모든 엔드포인트 차단됨

### 가능한 원인
1. **브라우저에서만 접근 허용**
   - Referer 헤더 검증
   - User-Agent 검증

2. **IP 화이트리스트**
   - 특정 IP에서만 접근 가능
   - 서버 IP 등록 필요

3. **API 키 활성화 대기**
   - 발급 후 승인 대기 중
   - 몇 시간~1일 소요

### 해결 방법
1. 한국도로공사 담당자 문의 (054-811-4533)
2. 국토교통부 ITS API 사용 (더 안정적)

---

## 📝 코드 구조

### 다중 API 폴백 시스템
```typescript
// 1순위: 국토교통부 ITS API
if (process.env.ITS_API_KEY) {
  try {
    // ITS API 호출
    return itsData;
  } catch {
    console.log('2순위 API로 전환');
  }
}

// 2순위: 한국도로공사 API
try {
  // 한국도로공사 API 호출
  return exwayData;
} catch {
  console.log('더미 데이터 사용');
}

// 3순위: 더미 데이터
return dummyData;
```

### 파일 위치
- 서비스: `backend-node/src/services/riskAlertService.ts`
- 컨트롤러: `backend-node/src/controllers/riskAlertController.ts`
- 라우트: `backend-node/src/routes/riskAlertRoutes.ts`

---

## 💡 현재 대시보드 위젯 데이터

### 리스크/알림 위젯
```
✅ 날씨특보: 14건 (실제 기상청 데이터)
⚠️ 교통사고: 2건 (더미 데이터)
⚠️ 도로공사: 2건 (더미 데이터)
─────────────────────────
총 18건의 알림
```

### 개선 후 (ITS API 연동 시)
```
✅ 날씨특보: 14건 (실제 기상청 데이터)
✅ 교통사고: N건 (실제 ITS 데이터)
✅ 도로공사: N건 (실제 ITS 데이터)
─────────────────────────
총 N건의 알림 (모두 실시간!)
```

---

## 🎯 다음 단계

### 단기 (지금)
- [x] 기상청 특보 API 연동 완료
- [x] 한국은행 환율 API 연동 완료
- [x] 다중 API 폴백 시스템 구축
- [ ] 국토교통부 ITS API 신청

### 장기 (향후)
- [ ] 서울시 TOPIS API 추가 (서울시 교통정보)
- [ ] 경찰청 교통사고 정보 API (승인 필요)
- [ ] 기상청 단기예보 API 추가

---

## 📞 문의

### 한국도로공사
- 전화: 054-811-4533 (컨텐츠 문의)
- 전화: 070-8656-8771 (시스템 장애)

### 공공데이터포털
- 웹사이트: https://www.data.go.kr/
- 고객센터: 1661-0423

---

**작성일**: 2025-10-14
**작성자**: AI Assistant
**상태**: ✅ 기상청 특보 작동 중, ITS API 연동 준비 완료