패키지, 저장소 및 앱 카테고리 검색

kpostal 표지
패키지 상세v2.0.1

kpostal

Kpostal 패키지는 카카오 우편번호 서비스를 사용하여 한국 주소를 검색할 수 있습니다.

AndroidiOS
30일 다운로드
2.7천
좋아요
74
Pub 점수
160

패키지 설치

flutter pub add kpostal

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

kpostal 패키지는 카카오 우편번호 서비스와 통합하여 플러터 앱에서 한국 주소를 검색할 수 있도록 합니다. 사용자가 검색 가능한 목록에서 주소를 선택할 수 있는 간단하고 네이티브 같은 인터페이스를 제공하여, 대한민국을 대상으로 하는 앱에서 주소 입력의 정확성과 효율성을 향상시킵니다. 이 패키지는 안드로이드 및 iOS 플랫폼을 모두 지원하며, 기기 간 일관된 동작을 보장합니다. 배송 또는 등록 시스템과 같은 정밀한 위치 데이터가 필요한 폼에 적합합니다.

사용 사례

  • 모바일 앱에서 한국 주소 선택
  • 배송 및 운송 양식 입력
  • 위치 정보 포함 사용자 프로필 등록
  • 한국의 위치기반 서비스
  • 전자상거래 앱에서 주소 자동 완성

주요 기능

  • 카카오 우편번호 API 연동
  • Android 및 iOS 지원
  • 주소 검색을 위한 간단하고 직관적인 UI
  • 실시간 주소 필터링
  • 경량이며 구현이 간편합니다

적합한 대상

  • 한국용 앱을 개발하는 개발자
  • 정확한 한국 우편번호가 필요한 앱
  • 전자상거래 및 물류 플랫폼
  • 신뢰할 수 있는 주소 입력이 필요한 양식

고려 사항

  • 우편번호 검색을 위해 인터넷 연결이 필요합니다
  • 한국 주소만 가능
  • 한국어가 아닌 사용자를 위해 추가 로컬라이제이션이 필요할 수 있습니다
  • 카카오 서비스 이용 가능 여부에 따라 다릅니다

원본 README

연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.

kpostal — Korean postal address search for Flutter

pub version pub points pub likes downloads test license

English Korean


kpostal is a Korean postal address search widget for Flutter, powered by the Kakao (Daum) postcode service. Push a single widget, get a structured address (postcode, road/jibun address, building info, …) back — with optional latitude/longitude geocoding.

Inspired by the discontinued Kopo package.

Features

  • 🔎 Kakao postcode search as a ready-made KpostalView widget — zero configuration to get started.
  • 🌐 Multi-platform: Android, iOS, macOS, and Web, built on the official webview_flutter (iframe on Web).
  • 📍 Geocoding built in: latitude/longitude via free platform geocoding (Android/iOS/macOS), plus optional Kakao Maps API geocoding.
  • 🏠 Resilient hosting: uses a GitHub-hosted search page by default, with a local-server fallback (useLocalServer) in case of hosting issues.
  • 🎨 Customizable: custom AppBar, loading indicator, and result callback.

Platform Support

Android iOS macOS Web Windows Linux
✅ ✅ ✅ ✅ ❌ ❌
  • Requires Flutter 3.38+ / Dart 3.10+.
  • On Web, useLocalServer is ignored and platform geocoding is unavailable (latitude/longitude are null) — use kakaoKey geocoding instead.
  • Platform geocoding uses the free OS services with their own usage limits — see the Apple, Android, and geocoding docs.
kpostal screenshot

Quick Start

dependencies:
  kpostal:
import 'package:kpostal/kpostal.dart';

// Use callback.
await Navigator.push(context, MaterialPageRoute(
  builder: (_) => KpostalView(
    callback: (Kpostal result) {
      print(result.address);
      print(result.latitude);
    },
  ),
));

// Or receive the result as a return value.
Kpostal result = await Navigator.push(
  context, MaterialPageRoute(builder: (_) => KpostalView()));

Key fields on the Kpostal result: postCode, address, roadAddress, jibunAddress, buildingName, sido, sigungu, latitude/longitude, kakaoLatitude/kakaoLongitude, userSelectedAddress — see the API reference for the full list.

Setup

🧑🏻‍💻 With the default hosted page, Android and iOS need no extra setup.

Android — internet permission (release mode)
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET"/>
macOS — network entitlements
<!-- macos/Runner/DebugProfile.entitlements & Release.entitlements -->
<key>com.apple.security.network.client</key>
<true/>
<!-- only if you use [useLocalServer] -->
<key>com.apple.security.network.server</key>
<true/>
Local server (optional, useLocalServer: true) — allow http traffic

The local server serves the search page over http://localhost, so cleartext traffic must be allowed.

Android — add android:usesCleartextTraffic="true" to <application> in AndroidManifest.xml:

<application
    android:label="[your_app]"
    android:usesCleartextTraffic="true"
    ...>

iOS — add NSAppTransportSecurity to Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
Kakao geocoding (optional, kakaoKey) — get kakaoLatitude/kakaoLongitude
  1. Go to the Kakao Developers site, register, and create an app.
  2. Add a Web platform: App – [Platform] – [Web Platform Registration].
  3. Register the site domain:
    • default hosting: https://tykann.github.io
    • local server: http://localhost:{your port, default 8080}
  4. Use the JavaScript key shown at the top of the page as kakaoKey.
KpostalView(
  kakaoKey: '{your kakao app JS key}',
  callback: (Kpostal result) {
    print(result.kakaoLatitude);
  },
)

Usage

KpostalView(
  useLocalServer: true,        // host the page on localhost (default: false)
  localPort: 8080,             // local server port (default: 8080)
  kakaoKey: '{JS key}',        // enable Kakao geocoding (optional)
  appBar: ...,                 // custom AppBar (optional)
  onLoading: ...,              // custom loading widget (optional)
  callback: (Kpostal result) { ... },
)

Migration from 1.x

Most apps need no code changes — v2 swaps the webview engine from flutter_inappwebview to the official webview_flutter and adds Web/macOS support.

  • Requires Flutter 3.38+ / Dart 3.10+.
  • On Web, latitude/longitude are null — use kakaoKey geocoding if you need coordinates.
  • macOS apps need the network entitlements above.

See the CHANGELOG for details.

Roadmap

  • [x] v2: migrate to official webview_flutter, Web & macOS support
  • [x] v2.0.0 stable release
  • [ ] Custom search page URL — self-host the postcode page on your own domain (also enables full control on Web, where a local server isn't possible)
  • [ ] Embeddable search widget (usable inside bottom sheets/dialogs without a Scaffold)
  • [ ] Windows/Linux support — blocked on webview_flutter desktop support

Have an idea or issue? Open an issue — contributions are welcome!

License

MIT

카테고리

의존성

의존성 목록 4 개

소스 저장소

이 패키지를 사용하는 프로젝트

아직 데이터가 없습니다.