행정안전부 도로명주소 API 기반 팝업 없는 한국 주소 검색 컴포넌트 (자동완성 지원) - Korean address search with autocomplete using official road address API
npm install slick-address-kr행정안전부 도로명주소 API 기반 팝업 없는 한국 주소 검색 라이브러리
Korean address search library using official road address API - No popup required


- ✨ 팝업 없는 인라인 UI: 다음 주소 API처럼 새 창이 열리지 않습니다
- 🚀 가벼운 용량: 외부 의존성 없이 순수 TypeScript로 작성
- 📱 반응형 디자인: 모바일부터 데스크톱까지 완벽 지원
- 🎨 커스터마이징 가능: CSS로 쉽게 스타일 변경 가능
- ⚡ 자동완성 모드: 타이핑하는 즉시 검색 결과 표시
- ⌨️ 키보드 네비게이션: 화살표 키로 결과 선택, 엔터로 적용 - 마우스 없이 빠른 입력!
- 🔒 TypeScript 지원: 완전한 타입 정의 제공
- 🌐 프레임워크 무관: Vanilla JS, React, Vue 등 어디서나 사용 가능
- 📦 모든 패키지 매니저 지원: npm, yarn, pnpm, bun, deno 모두 호환
bash
npm install slick-address-kr
`$3
`bash
yarn add slick-address-kr
`$3
`bash
pnpm add slick-address-kr
`$3
`bash
bun add slick-address-kr
`$3
`typescript
import { KoreanAddressFinder } from "npm:slick-address-kr@1.0.2";
`빠른 시작
$3
간단한 방법:
1. 프로젝트 폴더의
examples/index.html 파일을 참조하세요
2. 로컬 서버 실행:
`bash
python -m http.server 8000
`
3. 브라우저에서 열기:
`
http://localhost:8000/examples/
`코드 예제: examples/index.html
`html
주소 검색
`$3
`jsx
import React, { useEffect, useRef } from 'react';
import { KoreanAddressFinder } from 'korean-address-finder';
import 'korean-address-finder/dist/styles.css';function AddressInput() {
const containerRef = useRef(null);
const finderRef = useRef(null);
useEffect(() => {
if (containerRef.current && !finderRef.current) {
finderRef.current = new KoreanAddressFinder({
onSelect: (address) => {
console.log('선택된 주소:', address);
}
});
finderRef.current.init(containerRef.current);
}
return () => {
if (finderRef.current) {
finderRef.current.destroy();
}
};
}, []);
return
;
}
`$3
`vue
`API 문서
$3
`typescript
interface AddressFinderOptions {
/* 행정안전부 API 키 (선택사항) /
apiKey?: string; /* 한 페이지에 표시할 결과 수 (기본값: 10) /
countPerPage?: number;
/* 현재 페이지 번호 (기본값: 1) /
currentPage?: number;
/* 검색 결과를 표시할 컨테이너 ID /
containerId?: string;
/* 주소 선택 시 콜백 함수 /
onSelect?: (address: AddressResult) => void;
/* 상세주소 입력 필드 표시 여부 (기본값: true) /
showDetailInput?: boolean;
/* 커스텀 스타일 클래스 /
customClass?: string;
/* 자동완성 모드 사용 여부 (기본값: false) /
autocompleteMode?: boolean;
}
`$3
`typescript
interface AddressResult {
/* 도로명 주소 /
roadAddress: string; /* 지번 주소 /
jibunAddress: string;
/* 우편번호 /
zipCode: string;
/* 건물명 /
buildingName?: string;
/* 상세 주소 /
detailAddress?: string;
/* 참고 항목 /
extraAddress?: string;
/* 시도명 /
sido?: string;
/* 시군구명 /
sigungu?: string;
/* 읍면동명 /
bname?: string;
}
`$3
####
init(targetElement?: HTMLElement): void주소 검색 UI를 초기화합니다.
`javascript
const finder = new KoreanAddressFinder(options);
finder.init(); // containerId 사용
// 또는
finder.init(document.getElementById('my-container')); // 직접 엘리먼트 전달
`####
destroy(): void컴포넌트를 제거하고 이벤트 리스너를 정리합니다.
`javascript
finder.destroy();
`####
getSelectedAddress(): Object | null현재 선택된 주소 정보를 반환합니다.
`javascript
const selected = finder.getSelectedAddress();
console.log(selected); // { roadAddress, zipCode, detailAddress }
`사용 예제
$3
입력하는 즉시 검색 결과를 표시합니다.
`javascript
const finder = new KoreanAddressFinder({
autocompleteMode: true,
onSelect: (address) => {
console.log(address);
}
});finder.init();
`$3
마우스 없이 키보드만으로 주소를 빠르게 입력할 수 있습니다!
사용 방법:
- ⬇️ 화살표 아래: 다음 검색 결과로 이동
- ⬆️ 화살표 위: 이전 검색 결과로 이동
- Enter: 선택된 주소를 폼에 적용
- ESC: 검색 결과 닫기
`javascript
// 자동완성 모드에서 키보드 네비게이션이 자동으로 활성화됩니다
const finder = new KoreanAddressFinder({
autocompleteMode: true, // 타이핑 시 자동 검색
onSelect: (address) => {
console.log('선택된 주소:', address);
// 폼에 자동으로 입력됩니다
}
});finder.init();
`데모:
examples/proxy-test.html에서 키보드 네비게이션을 체험할 수 있습니다.$3
`javascript
const finder = new KoreanAddressFinder({
showDetailInput: false,
onSelect: (address) => {
console.log(address);
}
});finder.init();
`$3
`javascript
const finder = new KoreanAddressFinder({
customClass: 'my-custom-class',
onSelect: (address) => {
console.log(address);
}
});finder.init();
``css
.my-custom-class .kaf-search-btn {
background-color: #ff6b6b;
}.my-custom-class .kaf-search-input:focus {
border-color: #ff6b6b;
}
`API 키 발급 및 관리
이 라이브러리는 행정안전부 주소기반산업지원서비스 API를 사용합니다.
$3
1. 주소기반산업지원서비스 접속
2. 승인키 신청
3. ⚠️ 중요: "검색 API" 선택 (팝업 API가 아님!)
4. 사용할 도메인 등록 (선택사항)
$3
⚠️ 중요: API 키를 코드에 직접 넣으면 누구나 볼 수 있습니다!
프로젝트 규모에 맞는 방법을 선택하세요:
#### 방법 A: 설정 파일 사용 (간단한 프로젝트)
`javascript
// config.js (Git에 올리지 않음)
export const config = {
jusoApiKey: 'your_actual_api_key_here'
};// main.js
import { config } from './config.js';
const finder = new KoreanAddressFinder({
apiKey: config.jusoApiKey,
onSelect: (address) => console.log(address)
});
`#### 방법 B: 환경 변수 사용 (React, Vue 등)
`bash
.env
REACT_APP_JUSO_API_KEY=your_key_here
``javascript
const finder = new KoreanAddressFinder({
apiKey: process.env.REACT_APP_JUSO_API_KEY,
onSelect: (address) => console.log(address)
});
`#### 방법 C: 백엔드 프록시 서버 (상용 서비스 ⭐ 추천)
API 키를 서버에만 저장하고 클라이언트는 자체 서버를 통해 API 호출:
`javascript
// 클라이언트에서는 apiKey 불필요
const finder = new KoreanAddressFinder({
// 자체 서버 URL 설정 (api-client.ts 수정 필요)
onSelect: (address) => console.log(address)
});
`자세한 내용은
API-KEY-GUIDE.md 및 examples/backend-proxy/ 참조다음 주소 API와의 비교
| 기능 | Slick Address KR | 다음 주소 API |
|------|------------------|--------------|
| 팝업 | ❌ 없음 | ✅ 있음 (새 창) |
| 인라인 UI | ✅ 지원 | ❌ 미지원 |
| 커스터마이징 | ✅ 자유롭게 가능 | ⚠️ 제한적 |
| 자동완성 | ✅ 지원 | ✅ 지원 |
| 데이터 소스 | 행정안전부 공공 API | 다음 자체 DB |
| 의존성 | ✅ 독립적 | ⚠️ 다음 의존 |
| 모바일 최적화 | ✅ 완벽 지원 | ✅ 지원 |
브라우저 지원
- Chrome (최신 2개 버전)
- Firefox (최신 2개 버전)
- Safari (최신 2개 버전)
- Edge (최신 2개 버전)
- iOS Safari (12+)
- Android Chrome (최신)
라이선스
MIT License - 자유롭게 사용하세요!
기여하기
이슈와 PR은 언제나 환영합니다!
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)행정안전부 API는 CORS를 지원합니다. 만약 에러가 발생한다면:
1. API 키가 올바른지 확인
2. ⚠️ 중요: API 발급 시 "검색 API"로 발급받았는지 확인 (팝업 API가 아님!)
3. 도메인이 승인된 도메인인지 확인
4. HTTPS 사용 권장
1. 인터넷 연결 확인
2. API 키가 올바른지 확인
3. ⚠️ API 발급 시 "검색 API"로 선택했는지 확인
4. 콘솔에서 에러 메시지 확인
- 이슈: GitHub Issues
- GitHub: @Devguru-J
---
Project tango down by Devguru-J