Package selection guidance compiled from public package information, community data, and project usage.
The kpostal package enables Flutter applications to search for Korean postal addresses by integrating with the Kakao Postcode service. It provides a simple, native-like interface for users to select addresses from a searchable list, improving the accuracy and efficiency of address input in apps targeting South Korea. The package supports both Android and iOS platforms, ensuring consistent behavior across devices. It is ideal for forms requiring precise location data, such as delivery or registration systems.
Use cases
Korean address selection in mobile apps
Delivery and shipping form inputs
User profile registration with location
Location-based services in South Korea
Address autocomplete in e-commerce apps
Key features
Integration with Kakao Postcode API
Support for Android and iOS
Simple, intuitive UI for address search
Real-time address filtering
Lightweight and easy to implement
Suitable for
Developers building apps for South Korea
Apps requiring accurate Korean postal codes
E-commerce and logistics platforms
Forms needing reliable address input
Considerations
Requires internet connection for postcode lookup
Limited to Korean addresses only
May need additional localization for non-Korean users
Depends on Kakao's service availability
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
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.
🔎 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.awaitNavigator.push(context, MaterialPageRoute(
builder: (_) => KpostalView(
callback: (Kpostal result) {
print(result.address);
print(result.latitude);
},
),
));
// Or receive the result as a return value.Kpostal result = awaitNavigator.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.
<!-- 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: