kpostal 2.0.0-beta.2

Kpostal package can search for Korean postal addresses using Kakao postcode service.

---

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.

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

• ✅ v2: migrate to official webview_flutter, Web & macOS support
• ❌ 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