이 사이트는 행정안전부가 제공하는 도로명주소 영문 API를 사용합니다. 같은 API로 직접 개발하려는 분들을 위해 신청 방법과 호출 예제를 정리했습니다.
1. API 키 신청 (무료)
- business.juso.go.kr 회원가입
- API 신청 → 검색 API → 영문주소 선택
- 개발용 키(90일)는 즉시 발급, 운영용 키는 도메인 등록 후 발급
2. 요청 파라미터
| 파라미터 | 설명 | 필수 |
|---|---|---|
| confmKey | 발급받은 승인키 | O |
| keyword | 검색할 한글 주소 | O |
| currentPage | 페이지 번호 (기본 1) | O |
| countPerPage | 페이지당 결과 수 | O |
| resultType | json 또는 xml | - |
3. 호출 예제 (JSONP)
juso.go.kr 영문 API는 CORS를 지원하지 않으므로 브라우저에서는 JSONP 엔드포인트(addrEngApiJsonp.do)를 사용해요.
4. 주요 응답 필드
| 필드 | 설명 |
|---|---|
| roadAddr | 영문 도로명주소 |
| jibunAddr | 영문 지번주소 |
| zipNo | 우편번호(5자리) |
| korAddr | 한글 도로명주소 |
| totalCount | 검색 결과 총 개수 |
더 간단하게 쓰고 싶다면
직접 API를 다루지 않고 변환 기능만 넣고 싶다면 위젯 임베드(블로그에 붙여넣기)로 iframe 한 줄만 붙이면 됩니다.
위젯은 승인키 발급도 필요 없습니다. iframe 한 줄만 붙이면 변환기가 그대로 들어갑니다. 블로그나 쇼핑몰 안내 페이지에 넣기 좋습니다.
반대로 결과를 직접 가공해야 한다면 API를 쓰세요. 응답 필드를 골라 쓰거나 자체 DB에 저장하는 건 위젯으로는 안 됩니다.
이 사이트는 정부 기관이 아닌 독립 서비스입니다. 표기는 행정안전부가 고시한 공식 영문 표기행안부를 그대로 보여주지만, 운영 주체는 정부와 무관합니다. 비자·유학처럼 제출처가 양식을 지정하는 경우에는 해당 기관의 기준을 따르세요.
다른 도구
요청이 실패할 때 — 에러별 대응
브라우저 콘솔에 찍히는 에러는 대부분 세 갈래입니다. 인증 오류는 승인키가 틀렸거나 신청한 도메인과 호출한 도메인이 다를 때 납니다. 키를 발급받은 사이트 주소와 실제 서비스 주소(www 유무 포함)가 정확히 일치하는지 먼저 확인하세요. 결과 0건은 에러가 아니라 검색어 문제인 경우가 많습니다 — 동 이름만 넣거나 오타가 있으면 공공 API는 빈 배열을 돌려줍니다. 도로명+건물번호나 건물명으로 다시 시도해 보세요. 호출 한도 초과는 일 단위로 초기화되므로, 개발 중 반복 호출이 많다면 응답을 로컬에 캐시해 두는 편이 안전합니다.
운영 전 점검 목록
- 키 노출 — 브라우저 직접 호출 구조에서는 승인키가 소스에 보입니다. 공공 주소 API 키는 결제 정보가 아니라 위험도가 낮지만, 도메인 제한을 걸어두면 다른 사이트에서의 무단 사용을 막을 수 있습니다.
- 응답 지연 대비 — 공공 시스템 점검 시간에는 응답이 늦거나 실패할 수 있습니다. 로딩 표시와 "잠시 후 다시 시도" 안내를 넣어두면 사용자 이탈이 줄어듭니다.
- 영문 필드 확인 — 응답의 roadAddr는 한글, engAddr가 영문 표기입니다. 영문주소가 목적이라면 engAddr 필드를 쓰고, 상세주소(동·호수)는 응답에 없으므로 별도 입력으로 받아 조합해야 합니다.
- 표기 검증 — 조합한 최종 주소는 표기 검사기 로직처럼 우편번호 5자리·국가명 포함 여부를 한 번 걸러 주면 반송률이 내려갑니다.
이 사이트가 쓰는 방식과 같습니다
위 안내는 이론이 아니라 이 변환기가 실제로 동작하는 방식 그대로입니다. 서버 없이 브라우저에서 공공 API를 직접 호출하고, 영문 필드를 골라 쇼핑몰 칸에 맞게 나누는 구조입니다. 같은 구조로 만들면 서버 비용 없이 주소 검색 기능을 붙일 수 있고, 대량 처리가 필요하면 대량 변환의 CSV 방식을 참고하세요. 구현 중 막히는 부분은 API 연동 가이드에 코드 예시와 함께 정리해 두었습니다.