apple_map_snapshotter 1.0.0

Generate static Apple Maps snapshots on iOS using MapKit's MKMapSnapshotter. Perfect for displaying map previews without loading a full interactive map.

Apple Map Snapshotter

Generate static Apple Maps snapshots on iOS using MapKit's MKMapSnapshotter. Perfect for displaying map previews without loading a full interactive map.

Features

• Static map images - Generate map snapshots without interactive map overhead
• Theme support - Light, dark, or auto (follows system appearance)
• Customizable dimensions - Specify exact width and height in logical pixels
• Zoom control - Adjust zoom level from 0 (world) to 20 (building)
• High performance - Uses native MKMapSnapshotter for efficient rendering
• Retina ready - Automatically scales for high-DPI displays

Platform Support

Platform	Supported
iOS	✅
Android	❌
Web	❌
macOS	❌
Windows	❌
Linux	❌

Note: This plugin is iOS-only. Calling methods on other platforms will throw an UnsupportedError.

Installation

Add apple_map_snapshotter to your pubspec.yaml:

dependencies:
  apple_map_snapshotter: ^1.0.0

Then run:

flutter pub get

Usage

Basic Usage

import 'package:apple_map_snapshotter/apple_map_snapshotter.dart';

final bytes = await AppleMapSnapshotter.getSnapshot(
  latitude: 37.7749,
  longitude: -122.4194,
);

if (bytes != null) {
  // Display the snapshot
  Image.memory(bytes);
}

Custom Dimensions and Zoom

final bytes = await AppleMapSnapshotter.getSnapshot(
  latitude: 48.8566,
  longitude: 2.3522,
  width: 400,
  height: 300,
  zoomLevel: 14, // More zoomed in
);

With Theme

final bytes = await AppleMapSnapshotter.getSnapshot(
  latitude: 51.5074,
  longitude: -0.1278,
  theme: AppleMapSnapshotTheme.dark, // Force dark mode
);

Platform-Safe Usage

import 'dart:io';

Future<void> loadMapSnapshot() async {
  if (!Platform.isIOS) {
    // Handle non-iOS platforms
    print('Map snapshots only available on iOS');
    return;
  }

  try {
    final bytes = await AppleMapSnapshotter.getSnapshot(
      latitude: 37.7749,
      longitude: -122.4194,
    );
    // Use the snapshot...
  } on UnsupportedError catch (e) {
    print('Platform not supported: $e');
  } on ArgumentError catch (e) {
    print('Invalid parameters: $e');
  }
}

API Reference

AppleMapSnapshotter.getSnapshot()

Parameter	Type	Default	Description
latitude	double	required	Latitude coordinate (-90 to 90)
longitude	double	required	Longitude coordinate (-180 to 180)
width	double	300	Width in logical pixels
height	double	200	Height in logical pixels
zoomLevel	double	10	Zoom level (0 = world, 20 = building)
theme	AppleMapSnapshotTheme	auto	Map appearance mode

Returns: Future<Uint8List?> - PNG image bytes or null if generation fails.

AppleMapSnapshotTheme

Value	Description
light	Light mode map appearance
dark	Dark mode map appearance
auto	Matches system appearance

Zoom Level Reference

Level	View
0-3	World/continent
4-6	Country
7-9	State/region
10-12	City
13-15	Neighborhood
16-18	Street
19-20	Building

Error Handling

The plugin throws specific exceptions for different error cases:

try {
  final bytes = await AppleMapSnapshotter.getSnapshot(
    latitude: 37.7749,
    longitude: -122.4194,
  );
} on UnsupportedError catch (e) {
  // Called on non-iOS platform
  print('Not supported: $e');
} on ArgumentError catch (e) {
  // Invalid parameters (coordinates, dimensions, zoom)
  print('Invalid argument: $e');
} on PlatformException catch (e) {
  // Native error during snapshot generation
  print('Platform error: $e');
}

Performance Tips

• Cache snapshots when possible to avoid regenerating the same map
• Use appropriate dimensions - larger sizes take longer to generate
• Consider lazy loading - generate snapshots only when needed
• Reuse snapshots - store generated images rather than regenerating

Requirements

• iOS 12.0 or later
• Flutter 3.10.0 or later

Example

Check out the example directory for a complete sample app demonstrating all features.

License

MIT License - see the LICENSE file for details.

Author

Created by Luca Kramberger