kakao_maps_flutter

Note: Korean documentation is available at README_KO.md.

A Flutter plugin for integrating Kakao Maps SDK v2, providing a native map experience for both Android and iOS platforms.

📱 Platform Support

Feature	Android	iOS	Documentation
Camera Controls	✅	✅	✅
Camera Move End Events	✅	✅	✅
Label Click Events	✅	✅	✅
InfoWindow Click Events	✅	✅	✅
Marker Management	✅	✅	✅
MarkerStyle Registration	✅	✅	✅
LOD Marker Layer	✅	✅	✅
InfoWindow Management	✅	✅	✅
InfoWindow Layer Visibility	✅	✅	✅
Custom GUI Components	✅	✅	✅
POI Controls	✅	✅	✅
Compass Controls	✅	✅	✅
ScaleBar Controls	✅	✅	✅
Logo Position	✅	✅	✅
Logo Visibility	❌	✅	✅
Coordinate Conversion	✅	❌	✅
Map Information	✅	✅	✅

Getting Started

Prerequisites

Get API key from Kakao Developers Console
Configure platform-specific SDK setup

References

Android Getting Started: https://apis.map.kakao.com/android_v2/docs/getting-started/
iOS Getting Started: https://apis.map.kakao.com/ios_v2/docs/getting-started/gettingstarted/

Terms and usage notes

Separate agreement to Kakao Maps SDK Terms of Use required
Kakao developer site: https://developers.kakao.com/console/app
Quota limits may apply for commercial use

Installation

Add to pubspec.yaml

dependencies:
  kakao_maps_flutter: ^latest_version

SDK initialization

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await KakaoMapsFlutter.init('YOUR_API_KEY');
  runApp(const MyApp());
}

Add map widget

class MapScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: KakaoMap(
        onMapCreated: (controller) {},
        initialPosition: LatLng(latitude: 37.5665, longitude: 126.9780),
        initialLevel: 15,
      ),
    );
  }
}

Usage

Camera movement

await controller.moveCamera(
  cameraUpdate: CameraUpdate.fromLatLng(
    LatLng(latitude: 37.5665, longitude: 126.9780),
  ),
  animation: const CameraAnimation(
    duration: 1000,
    autoElevation: true,
    isConsecutive: false,
  ),
);

Add/Remove marker

await controller.addMarker(
  markerOption: const MarkerOption(
    id: 'marker_id',
    latLng: LatLng(latitude: 37.5665, longitude: 126.9780),
  ),
);

await controller.removeMarker(id: 'marker_id');

Toggle POI visibility

await controller.setPoiVisible(isVisible: true); // or false

Camera move end events

final cameraMoveEndSub = controller.onCameraMoveEndStream.listen((event) {
  debugPrint('moved: ${event.latitude}, ${event.longitude}');
});

Label click events

final labelClickSub = controller.onLabelClickedStream.listen((event) {
  debugPrint('label clicked: ${event.labelId}');
});

Add/Remove InfoWindow

await controller.addInfoWindow(
  infoWindowOption: const InfoWindowOption(
    id: 'info_1',
    latLng: LatLng(latitude: 37.5665, longitude: 126.9780),
    title: 'Seoul Station',
    snippet: 'Main railway station in Seoul',
    offset: InfoWindowOffset(x: 0, y: -20),
  ),
);

await controller.removeInfoWindow(id: 'info_1');

Add/Use MarkerStyle

// import 'dart:convert'; // for base64Decode

// 1) Define Styles
final styles = [
  MarkerStyle(
    styleId: 'default_marker_style_001',
    perLevels: [
      MarkerPerLevelStyle.fromBytes(
        bytes: base64Decode('BASE64_IMAGE_2X'),
        textStyle: const MarkerTextStyle(
          fontSize: 24,
          fontColorArgb: 0xFF000000,
        ),
        level: 6,
      ),
      MarkerPerLevelStyle.fromBytes(
        bytes: base64Decode('BASE64_IMAGE_4X'),
        textStyle: const MarkerTextStyle(
          fontSize: 20,
          fontColorArgb: 0xFF000000,
        ),
        level: 21,
      ),
    ],
  ),
];

// 2) Register
await controller.registerMarkerStyles(styles: styles);

// 3) Use
await controller.addMarker(
  markerOption: MarkerOption(
    id: 'marker_with_style',
    latLng: LatLng(latitude: 37.5665, longitude: 126.9780),
    styleId: 'default_marker_style_001',
  ),
);

🔧 Troubleshooting: Kakao Maps Android SDK repository

Add repository on Gradle when error occurs

Could not find com.kakao.maps.open:android:2.12.8.

Add to android/build.gradle

allprojects {
    repositories {
        // ... other repositories ...
        maven { url 'https://devrepo.kakao.com/nexus/repository/kakaomap-releases/' }
    }
}

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

License

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

Acknowledgments

@Kakao for providing the excellent KakaoMapsSDK.

All contributors for helping build this project together 🙏