# 엑셀 주소 → 우편번호 자동 변환 앱

엑셀 파일에서 "주소" 컬럼의 주소를 읽어 네이버 지도 API를 통해 우편번호를 조회하고, "우편번호" 컬럼에 자동으로 매칭하여 저장하는 Python 애플리케이션입니다.

## 주요 기능

- 📋 엑셀 파일의 "주소" 컬럼 자동 인식
- 🌐 네이버 지도 API를 사용한 정확한 우편번호 조회
- 📝 "우편번호" 컬럼 자동 생성 및 데이터 추가
- ✅ 처리 결과 통계 표시
- 🔄 배치 처리 지원

## 설치 방법

### 1. 필수 요구사항
- Python 3.7 이상
- pip (Python 패키지 관리자)

### 2. 라이브러리 설치
```bash
pip install -r requirements.txt
```

### 3. 네이버 API 등록

1. [네이버 클라우드 콘솔](https://console.ncloud.com/)에 접속
2. 회원가입 또는 로그인
3. "Services" → "AI · Application Service" → "Naver API" 선택
4. "Application" 메뉴에서 새 애플리케이션 등록
5. Maps 서비스에서 "Geocoding API" 권한 추가
6. API 인증 정보 확인:
   - Client ID
   - Client Secret

### 4. 환경 변수 설정

`.env.example` 파일을 참고하여 `.env` 파일을 생성합니다:

```bash
# .env 파일
NAVER_CLIENT_ID=your_client_id_here
NAVER_CLIENT_SECRET=your_client_secret_here
```

## 사용 방법

### 기본 사용법

```bash
python main.py 파일경로.xlsx
```

또는 대화형 모드:

```bash
python main.py
# 그러면 파일 경로를 입력하도록 요청합니다
```

### 예시

```bash
python main.py customers.xlsx
```

## 엑셀 파일 형식

### 필수 요구사항
- 첫 번째 행은 헤더 행
- **"주소"** 라는 이름의 컬럼 필수 존재

### 입력 예시

| 이름 | 주소 |
|------|------|
| 홍길동 | 서울시 강남구 테헤란로 123 |
| 김철수 | 부산시 중구 중앙대로 456 |

### 출력 예시

| 이름 | 주소 | 우편번호 |
|------|------|---------|
| 홍길동 | 서울시 강남구 테헤란로 123 | 06234 |
| 김철수 | 부산시 중구 중앙대로 456 | 48058 |

## 주소 입력 형식

네이버 API는 다양한 주소 형식을 지원합니다:

### 도로명 주소 (권장)
```
서울시 강남구 테헤란로 123
경기도 성남시 분당구 정자동 100-1
```

### 지번 주소
```
서울시 강남구 역삼동 123
부산시 중구 중앙동 456-7
```

## 트러블슈팅

### "네이버 API 인증 정보가 없습니다" 오류

**.env 파일이 제대로 설정되었는지 확인하세요:**

```bash
# .env 파일이 존재하는지 확인
ls -la .env

# 파일 내용 확인 (값이 비어있지 않은지 확인)
cat .env
```

### "주소 검색 결과 없음" 경고

- 주소 형식이 정확한지 확인하세요
- 존재하지 않는 주소일 수 있습니다
- 도로명 주소 또는 정확한 주소로 다시 시도해보세요

### API 요청 타임아웃

네이버 API 응답이 느린 경우입니다:
- 잠시 후 다시 시도하세요
- 인터넷 연결 상태를 확인하세요

### "X-NCP-APIGW-API-KEY-ID" 관련 오류

API 인증 정보가 잘못되었을 가능성이 있습니다:
1. 네이버 클라우드 콘솔에서 클라이언트 ID/Secret 재확인
2. `.env` 파일에 정확히 입력했는지 확인
3. 파일을 저장한 후 다시 실행

## 처리 시간

주소 개수에 따라 처리 시간이 달라집니다:
- 100개 주소: ~1-2분
- 1,000개 주소: ~10-20분
- 10,000개 주소: ~100-200분

## API 사용 제한

네이버 API는 무료로 일정량의 요청을 제공합니다:
- 월 25,000건의 무료 쿼터 제공
- 초과 시 추가 요금 발생 가능

자세한 내용은 [네이버 Geocoding API 문서](https://api.ncloud-docs.com/docs/ai-geocoding-geocode)를 참고하세요.

## 파일 구조

```
excelpostchanger/
├── main.py                 # 메인 애플리케이션
├── address_handler.py      # 우편번호 조회 로직
├── excel_handler.py        # 엑셀 파일 처리 로직
├── config.py              # 설정 파일
├── .env.example           # 환경 변수 예시
├── .env                   # 환경 변수 (실제 사용)
├── requirements.txt       # Python 의존성
└── README.md             # 이 파일
```

## 라이선스

MIT License

## 지원

문제가 발생하거나 기능 요청이 있으면 이슈를 등록해주세요.