osm_maps_engine 0.0.4

A plug-and-play map engine powered by OpenStreetMap and OSRM for Flutter.

OSM Maps Engine

A complete, plug-and-play mapping and routing engine for Flutter, powered entirely by OpenStreetMap (OSM) and Open Source Routing Machine (OSRM).

This package provides a drop-in widget for real-time driver tracking, smooth marker animations, dynamic polyline rendering, and estimated time of arrival (ETA) calculation without relying on proprietary mapping APIs.

Cost Optimization Comparison

This package is built to be a 100% free and open-source alternative to proprietary map services like Google Maps. Because it relies on flutter_map (OpenStreetMap) and the Open Source Routing Machine (OSRM), you do not need to pay per-request for routing or map loads.

Here is a quick comparison of why osm_maps_engine is a highly cost-effective solution for delivery and ride-hailing apps:

Feature	google_maps_flutter (Proprietary)	osm_maps_engine (Open Source)
Map Rendering	Paid after free tier ($7.00 per 1000 loads)	100% Free (using OpenStreetMap via flutter_map)
Routing API	Paid ($5.00 per 1000 requests)	100% Free (using public/self-hosted OSRM)
Live Re-routing	Costs add up exponentially per trip	$0.00 no matter how many times driver strays
Geocoding/Polyline	Proprietary Directions API required	$0.00 built right into the open-source engine

Note: For heavy production usage, it is recommended to host your own OSRM instance. Even then, the cost is a flat server hosting fee rather than an unpredictable per-request API charge.

Key Features

• 100% Free & Open-Source Backend: Uses flutter_map (OpenStreetMap) and public OSRM API for routing. No API keys required for basic usage.
• Plug-and-Play UI Widget: Simply drop OsmMapWidget into your screen to get a fully functional navigation map.
• Gradient Route Polyline: Beautifully renders the route line with a dynamic color gradient that fades smoothly into the destination.
• Real-Time Location Tracking: Automatically tracks the user's GPS location via geolocator.
• Smooth Marker Animation: Interpolates movement between GPS updates for a fluid 60FPS marker motion experience.
• Smart Road Snapping: Ensures the driver's icon stays firmly clamped to the actual road/route polyline regardless of minor GPS jitter or inaccuracy (25m limit).
• Auto-Rerouting: Detects if the driver strays off the path and automatically recalculates the route.
• Modular Architecture: Decoupled state management using BLoC/Cubit pattern.

Installation

Add the package to your pubspec.yaml:

dependencies:
  osm_maps_engine:
    git:
      url: https://github.com/rayhanrwa1/osm_map_engine.git
      ref: main

Basic Usage

The easiest way to use the engine is through the OsmMapWidget. You only need to provide the starting location (origin) and the destination.

import 'package:flutter/material.dart';
import 'package:latlong2/latlong.dart';
import 'package:osm_maps_engine/osm_maps_engine.dart';

class DeliveryScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Live Tracking')),
      body: OsmMapWidget(
        origin: const LatLng(-6.2088, 106.8456), // Example: Jakarta
        destination: const LatLng(-6.2115, 106.8450),
        driverIconWidget: const Icon(Icons.local_shipping, color: Colors.blue, size: 40),
        destinationIconWidget: const Icon(Icons.flag, color: Colors.red, size: 40),
        onLocationUpdated: (position) {
          // Send to your backend (e.g., Firebase) if needed
        },
      ),
    );
  }
}

Core Services Overview

If you need deeper customization, you can directly access the core services:

1. RouteCalculationService: Communicates with the OSRM backend to fetch polyline geometries, distance, and duration.
2. MarkerMotionService: Calculates bearing and interpolates marker movement between location updates.
3. MapCameraService: Controls the flutter_map MapController for centering and bounding.
4. LocationTrackingService: A wrapper around geolocator to handle continuous background/foreground location streaming.

Platform Configuration

Since this package uses geolocator, you must configure your native platforms to allow location access.

iOS (ios/Runner/Info.plist)

Add the following keys to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location for live tracking.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app needs access to location when in the background.</string>

Android (android/app/src/main/AndroidManifest.xml)

Add the following permissions:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Customizing the Routing Server

By default, the engine uses the public OSRM demo server (router.project-osrm.org). For production applications with heavy traffic, it is highly recommended to host your own OSRM server or use a commercial provider like OpenRouteService or Mapbox.

You can modify the endpoint in lib/src/route_calculation_service.dart.

License

This project is licensed under the MIT License.