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

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

주요 기능

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

설치 방법

1. 필수 요구사항

• Python 3.7 이상
• pip (Python 패키지 관리자)

2. 라이브러리 설치

pip install -r requirements.txt

3. 네이버 API 등록

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

4. 환경 변수 설정

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

# .env 파일
NAVER_CLIENT_ID=your_client_id_here
NAVER_CLIENT_SECRET=your_client_secret_here

사용 방법

기본 사용법

python main.py 파일경로.xlsx

또는 대화형 모드:

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

예시

python main.py customers.xlsx

엑셀 파일 형식

필수 요구사항

• 첫 번째 행은 헤더 행
• "주소" 라는 이름의 컬럼 필수 존재

입력 예시

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

출력 예시

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

주소 입력 형식

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

도로명 주소 (권장)

서울시 강남구 테헤란로 123
경기도 성남시 분당구 정자동 100-1

지번 주소

서울시 강남구 역삼동 123
부산시 중구 중앙동 456-7

트러블슈팅

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

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

# .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 문서를 참고하세요.

파일 구조

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

라이선스

MIT License

지원

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