Search packages, repositories and app categories

GitHub repositoryTykanN/kpostal

kpostal

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

kpostal project cover
Stars
12
Forks
17
Last push (UTC)
Aug 3, 2026
Project status
Active

Original README

English project snapshot. Visit GitHub for the latest content.

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 author

Theo / Taeyoon Kang ↗

@piehealthcare CTO
LanguagesDartHTMLRubySwiftKotlinObjective-C

Packages published by this repository

Dependencies used

Dependency list 8 items

  • flutter{"sdk":"flutter"}
  • geocoding^5.0.0
  • geocoding_platform_interface^5.0.0
  • web^1.1.0
  • webview_flutter^4.14.1
  • flutter_testDevelopment{"sdk":"flutter"}
  • flutter_lintsDevelopment—
  • webview_flutter_platform_interfaceDevelopment^2.15.1

How do I choose a repository?

Start with your use case, compare repository activity, and check the original project before adopting it.

  1. Search by repository name, owner or description, then narrow the results by topic.
  2. Compare stars, forks and recent pushes. Stars show community interest, not a guarantee of quality.
  3. Read the README, license and issues on GitHub before using a project.

Sources and maintenance

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

GitHub Docs — About repositories ↗