TykanN/kpostal

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

• 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.

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET"/>

<!-- 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/>

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

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

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