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

GitHub 저장소TykanN/kpostal

kpostal

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

kpostal 프로젝트 이미지
스타
12
포크
17
최근 푸시(UTC)
2026. 8. 3.
프로젝트 상태
활성

원본 README

아래는 영문 원문 스냅샷입니다. 최신 내용은 GitHub에서 확인하세요.

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

Theo / Taeyoon Kang GitHub avatar
GitHub 작성자

Theo / Taeyoon Kang ↗

@piehealthcare CTO
언어DartHTMLRubySwiftKotlinObjective-C

이 저장소가 배포한 패키지

사용 중인 의존성

의존성 목록 8 개

  • flutter{"sdk":"flutter"}
  • geocoding^5.0.0
  • geocoding_platform_interface^5.0.0
  • web^1.1.0
  • webview_flutter^4.14.1
  • flutter_test개발 의존성{"sdk":"flutter"}
  • flutter_lints개발 의존성—
  • webview_flutter_platform_interface개발 의존성^2.15.1

프로젝트에 맞는 저장소를 선택하려면?

사용 목적에 따라 검색하고 개발 활동을 비교한 뒤 원본 저장소에서 요구 사항을 확인하세요.

  1. 이름, 작성자 또는 설명으로 검색하고 기술 주제로 범위를 좁힙니다.
  2. 스타, 포크, 최근 푸시를 함께 비교하세요. 스타는 관심의 지표이며 품질을 보장하지 않습니다.
  3. 사용하기 전에 GitHub에서 README, 라이선스, Issues를 확인하세요.

출처 및 관리

“A repository is the most basic element of GitHub.”

GitHub Docs — About repositories ↗