flutter_maps_package 0.1.0

A unified Flutter map package supporting Google Maps and OpenStreetMap (OSM) with offline tile caching, region/trail downloads, admin boundary scoping, and customizable widgets.

flutter_maps_package

A unified Flutter map package supporting both Google Maps and OpenStreetMap (OSM) through a single, provider-agnostic API.

Features

• Unified API — switch between Google Maps and OSM without changing your application code.
• Offline-first OSM — disk-backed tile cache with LRU eviction and TTL; pre-download regions and trails for fully offline use.
• Country & admin scoping — restrict map tiles, search, and routing to a country bounding box or an administrative unit.
• Customizable widget — theming, custom marker builders, polyline styles, admin boundary overlays, and a region-selector UI mode.

Installation

Add the package to your pubspec.yaml:

dependencies:
  flutter_maps_package: ^0.1.0

Then run:

flutter pub get

Quick Start

import 'package:flutter_maps_package/flutter_maps_package.dart';

// 1. Initialize once at app startup (e.g. in main())
await FlutterMapsPackage.initialize(
  config: PackageConfig(
    googleMapsApiKey: 'YOUR_GOOGLE_MAPS_API_KEY', // omit if using OSM only
    defaultProvider: MapProvider.osm,
    cacheTtl: const Duration(days: 7),
    cacheMaxSizeBytes: 512 * 1024 * 1024, // 512 MB
  ),
);

// 2. Place the MapWidget in your widget tree
MapWidget(
  showZoomControls: true,
  onMapTap: (coordinates) {
    print('Tapped at: ${coordinates.latitude}, ${coordinates.longitude}');
  },
)

// 3. Switch provider at runtime (e.g. in response to a user action)
final controller = MapController.instance;
await controller.setProvider(MapProvider.google);

// 4. Download an offline region for later use without connectivity
final region = BoundingBox(
  north: 37.8,
  south: 37.7,
  east: -122.4,
  west: -122.5,
);
await controller.downloadRegion(
  region: region,
  minZoom: 10,
  maxZoom: 14,
  onProgress: (progress) {
    print('Download progress: ${(progress * 100).toStringAsFixed(1)}%');
  },
);

API Documentation

Run dart doc to generate full API documentation. All public classes, methods, and properties carry Dart doc comments.

Example App

See the example/ directory for a runnable Flutter application that demonstrates:

• Provider switching (Google Maps ↔ OSM)
• Offline region download with progress tracking
• Trail-based region download
• Custom widget theming

License

See LICENSE.