175 lines
4.0 KiB
Markdown
175 lines
4.0 KiB
Markdown
|
|
||
|
|
# 🔌 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 연동 준비 완료
|
||
|
|
|