• 홈
  • Uncategorized

우체국 API를 활용한 한글 주소 → 영문 주소 변환 가이드

가나톡ganaTOK
가나톡ganaTOK

우체국 API를 활용한 한글 주소 → 영문 주소 변환 가이드

한글 주소를 영문 주소로 변환하는 기능은 해외 배송, 국제 우편, 외국인 대상 서비스 등 다양한 분야에서 유용합니다. 우체국에서는 이러한 변환을 지원하는 영문 주소 변환 API를 제공하며, 이를 활용하면 시스템에서 자동으로 변환 작업을 수행할 수 있습니다.

이 글에서는 우체국 API를 이용해 한글 주소를 영문 주소로 변환하는 과정을 단계별로 설명하고, 실제 Python 코드를 통해 API 호출 방법까지 소개하겠습니다. 🚀

1. 우체국 영문 주소 변환 API란?

✅ API 개요

우체국 "영문 주소 변환 API"는 한글 주소(도로명주소 또는 지번주소)를 입력하면 해당 주소의 공식 영문 표기를 반환하는 서비스입니다.

✅ 주요 활용 사례

✔ 해외로 상품을 배송할 때 영문 주소 자동 변환
✔ 외국인을 위한 영문 주소 제공 서비스
✔ 국제 우편을 보낼 때 정확한 주소 변환

2. API 사용을 위한 사전 준비

우체국 API를 사용하려면 공공데이터포털(data.go.kr)에서 API 키를 발급받아야 합니다.

🔹 1. 공공데이터포털 회원가입 및 API 키 발급

1️⃣ 공공데이터포털에 접속하여 회원가입
2️⃣ "우체국 영문주소 변환 API"를 검색
3️⃣ "활용신청" 버튼을 눌러 API 사용 신청
4️⃣ 승인 후 발급된 API 키(Service Key)를 확인

3. API 요청 구성

우체국 API는 RESTful 방식으로 요청하며, 기본적인 요청 URL은 다음과 같습니다.

plaintext
http://openapi.epost.go.kr/postal/retrieveEngAddressService/retrieveEngAddressService/getEngAddr

🔹 API 요청 시 필수 파라미터

파라미터 설명
ServiceKey 발급받은 API 키
searchSe 검색 유형 (road = 도로명주소, jibun = 지번주소)
srchwrd 검색할 주소(한글)

4. 실제 API 호출 예제 (Python 코드 포함)

이제 Python을 이용해 우체국 API를 호출하고 영문 주소를 가져오는 방법을 실습해 보겠습니다.

📌 예제 1: 도로명주소를 영문 주소로 변환하기


import requests
import xml.etree.ElementTree as ET

# 1️⃣ API 요청 URL 설정
api_url = "http://openapi.epost.go.kr/postal/retrieveEngAddressService/retrieveEngAddressService/getEngAddr"

# 2️⃣ 요청 파라미터 설정
params = {
    "ServiceKey": "발급받은API키",  # 실제 발급받은 API 키 입력
    "searchSe": "road",  # 도로명주소 사용
    "srchwrd": "세종대로 110"  # 검색할 한글 주소
}

# 3️⃣ API 요청 보내기
response = requests.get(api_url, params=params)

# 4️⃣ 응답 데이터 확인
if response.status_code == 200:
    root = ET.fromstring(response.content)
    
    # 5️⃣ XML에서 영문 주소 추출
    eng_addr = root.find(".//engAddr")
    if eng_addr is not None:
        print("✔ 변환된 영문 주소:", eng_addr.text)
    else:
        print("❌ 영문 주소를 찾을 수 없습니다.")
else:
    print("❌ API 요청 실패! 상태 코드:", response.status_code)

🔍 코드 설명

✔ requests.get(api_url, params=params) → 우체국 API에 GET 요청
✔ ET.fromstring(response.content) → XML 응답 데이터를 파싱
✔ root.find(".//engAddr") → 영문 주소 추출

📌 실행 결과 (예시)

✔ 변환된 영문 주소: 110, Sejong-daero, Seoul, Republic of Korea

5. API 요청 시 주의할 점

🔹 1. API 키(Service Key) 유효성 확인

  • API 키가 올바르지 않으면 403 Forbidden 오류 발생
  • 공공데이터포털에서 신청한 API 키가 활성화되었는지 확인

🔹 2. 요청한 주소의 정확성

  • 주소 입력이 정확하지 않으면 결과가 나오지 않을 수 있음
  • 공식 도로명주소를 사용해야 정확한 변환 가능

🔹 3. API 요청 횟수 제한

  • API에는 일일 요청 제한이 있을 수 있음
  • 너무 많은 요청을 하면 일시 차단될 가능성이 있음

6. API 데이터를 엑셀에 자동 저장하기 (Python + openpyxl 활용)

우체국 API를 활용해 여러 개의 주소를 한 번에 변환하고 엑셀에 자동 저장하는 코드를 작성해 보겠습니다.

📌 예제 2: 여러 개의 한글 주소를 변환하여 엑셀 저장하기

import requests
import xml.etree.ElementTree as ET
import openpyxl

# 1️⃣ 엑셀 파일 생성
wb = openpyxl.Workbook()
ws = wb.active
ws.title = "영문 주소 변환"

# 2️⃣ 엑셀 헤더 추가
ws.append(["한글 주소", "영문 주소"])

# 3️⃣ 변환할 한글 주소 리스트
addresses = ["세종대로 110", "종로구 청와대로 1", "강남구 테헤란로 123"]

# 4️⃣ API 요청 및 데이터 변환
api_url = "http://openapi.epost.go.kr/postal/retrieveEngAddressService/retrieveEngAddressService/getEngAddr"
api_key = "발급받은API키"

for addr in addresses:
    params = {"ServiceKey": api_key, "searchSe": "road", "srchwrd": addr}
    response = requests.get(api_url, params=params)
    
    if response.status_code == 200:
        root = ET.fromstring(response.content)
        eng_addr = root.find(".//engAddr")
        eng_address = eng_addr.text if eng_addr is not None else "변환 실패"
    else:
        eng_address = "API 오류"

    # 5️⃣ 변환된 주소를 엑셀에 추가
    ws.append([addr, eng_address])

# 6️⃣ 엑셀 파일 저장
wb.save("English_Address.xlsx")
print("✔ 변환된 주소가 엑셀에 저장되었습니다!")

📌 이제 변환된 영문 주소가 English_Address.xlsx 파일에 저장됩니다!

결론: 우체국 API를 활용하면 업무 자동화 가능!

✅ 우체국 영문 주소 변환 API를 활용하면 한글 주소를 자동으로 영문으로 변환할 수 있습니다.
✅ Python을 이용하면 여러 개의 주소를 한 번에 변환 & 엑셀 저장이 가능!
✅ API를 사용하면 업무 자동화 & 실수 방지 & 처리 속도 향상 효과 🎯

🚀 이제 API를 활용하여 자동 변환 시스템을 만들어 보세요!

💬 추가 질문이나 피드백이 있으면 댓글로 남겨 주세요. 😊

댓글 쓰기