Initial commit: Excel Address to Postal Code Converter
This commit is contained in:
170
README.md
Normal file
170
README.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 엑셀 주소 → 우편번호 자동 변환 앱
|
||||
|
||||
엑셀 파일에서 "주소" 컬럼의 주소를 읽어 네이버 지도 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
|
||||
|
||||
## 지원
|
||||
|
||||
문제가 발생하거나 기능 요청이 있으면 이슈를 등록해주세요.
|
||||
Reference in New Issue
Block a user