🚀 postal_ko #

A cross-platform Flutter package for Korean postal address search using Kakao postcode service.

✨ Features #

• 📱 Cross-platform support: Works seamlessly on mobile (iOS/Android) and web platforms
• 🔍 Korean address search: Powered by Kakao postcode service
• 🌐 Web integration: Native web support with DOM manipulation
• 📍 Geocoding support: Get latitude/longitude coordinates
• 🛡️ Null-safe: Full null safety support
• 🎯 Unified API: Single package for all platforms

🚀 Getting Started #

Add postal_ko to your pubspec.yaml file:

dependencies:
  postal_ko: ^1.0.0

📱 Platform Support #

⚙️ Setup #

🤖 Android #

Add internet permission to your AndroidManifest.xml:

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

🍎 iOS #

No additional setup required for basic usage.

🌐 Web #

No additional setup required. The package automatically handles web integration.

🔧 Local Server (Optional) #

If you want to use local server hosting:

Android

Add android:usesClearextTraffic="true" to your AndroidManifest.xml:

<application
    android:label="[your_app]"
    android:icon="@mipmap/ic_launcher"
    android:usesCleartextTraffic="true">
    ...
</application>

iOS

Add NSAppTransportSecurity to your info.plist:

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

🗺️ Kakao Geocoding (Optional) #

1. Go to Kakao Developer Site
2. Register developer and create app
3. Add Web Platform and register domain:
   • Default: https://tykann.github.io
   • Local server: http://localhost:8080
4. Use the JavaScript key as kakaoKey

📖 Usage #

Basic Usage #

import 'package:postal_ko/postal_ko.dart';

// Using callback
TextButton(
  onPressed: () async {
    await Navigator.push(
      context,
      MaterialPageRoute(
        builder: (_) => KpostalView(
          callback: (Kpostal result) {
            print('Address: ${result.address}');
            print('Postal Code: ${result.postCode}');
            print('Coordinates: ${result.latitude}, ${result.longitude}');
          },
        ),
      ),
    );
  },
  child: Text('Search Address'),
)

// Using return value
TextButton(
  onPressed: () async {
    Kpostal? result = await Navigator.push(
      context,
      MaterialPageRoute(builder: (_) => KpostalView()),
    );
    if (result != null) {
      print('Selected address: ${result.address}');
    }
  },
  child: Text('Search Address'),
)

Advanced Usage #

KpostalView(
  useLocalServer: true, // Use local server (default: false)
  localPort: 8080, // Local server port (default: 8080)
  kakaoKey: 'your_kakao_js_key', // Optional Kakao geocoding
  callback: (Kpostal result) {
    // Handle result
    print('Address: ${result.address}');
    print('Building name: ${result.buildingName}');
    print('Zone code: ${result.zonecode}');
    print('Coordinates: ${result.latitude}, ${result.longitude}');
  },
)

📊 Kpostal Model #

class Kpostal {
  String postCode;        // Postal code
  String address;         // Full address
  String jibunAddress;    // Jibun address
  String roadAddress;     // Road address
  String buildingName;    // Building name
  String zonecode;        // Zone code
  double? latitude;       // Latitude (from geocoding)
  double? longitude;      // Longitude (from geocoding)
  // ... and more fields
}

🌐 Web Support #

The package automatically detects the platform and provides appropriate implementation:

• Mobile: Uses InAppWebView for embedded web content
• Web: Uses native DOM manipulation and JavaScript interop

No additional configuration needed - it just works! 🎉

🔧 Migration from kpostal #

If you're migrating from the original kpostal package:

1. Update your pubspec.yaml:

   dependencies:
     postal_ko: ^1.0.0 # Replace kpostal
   

2. Update imports:

   // Old
   import 'package:kpostal/kpostal.dart';
   
   // New
   import 'package:postal_ko/postal_ko.dart';
   

3. The API remains the same - no code changes needed! ✨

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

• Inspired by the original kpostal package
• Built with Kakao Postcode Service
• Thanks to all contributors and users! 🎉