Quick Start 🚀

Basic Usage

import 'package:road_distance_calculator/road_distance_calculator.dart';

final calculator = ByRoadDistanceCalculator();
final points = [
  LatLng(37.7749, -122.4194),  // SF
  LatLng(34.0522, -118.2437)   // LA
];

final distance = calculator.calculateDistance(points);
print('Distance: \${distance.toStringAsFixed(2)} km');  // Output: Distance: 559.23 km

API Reference 📚

Core Methods

`calculateDistance(List<LatLng> points) → double`

Calculates total distance for a list of coordinates.

Parameters:

points: Ordered list of LatLng coordinates.

Returns:

Total distance in kilometers.

Polyline Decoding

`static decodePolylineString(String encoded) → List<LatLng>`

Decodes polyline strings (e.g., "yxocFxfgy@...") into coordinates.

final polyline = 'yxocFxfgy@...';
final points = ByRoadDistanceCalculator.decodePolylineString(polyline);

GPS File Parsing

`parseGPX(String gpxContent) → List<LatLng>`

Extracts coordinates from GPX files.

final gpxFile = File('route.gpx').readAsStringSync();
final points = calculator.parseGPX(gpxFile);

`parseKML(String kmlContent) → List<LatLng>`

Extracts coordinates from KML files.

final kmlFile = File('route.kml').readAsStringSync();
final points = calculator.parseKML(kmlFile);

Real-Time Tracking

`addPoint(LatLng point)`

Adds points incrementally for live tracking.

`distanceUpdates → Stream<double>`

Stream of cumulative distance updates.

calculator.distanceUpdates.listen((km) {
  print('Distance updated: \${km.toStringAsFixed(2)} km');
});

// Simulate GPS updates
await Future.delayed(Duration(seconds: 1));
calculator.addPoint(LatLng(37.3354, -122.0097));

Use Cases 💡

1. Fitness Apps 🏃‍♂️

Track running/cycling routes from GPX files:

final gpxPoints = calculator.parseGPX(gpxData);
final distance = calculator.calculateDistance(gpxPoints);

2. Logistics Solutions 🚚

Calculate delivery route distances:

final routePoints = ByRoadDistanceCalculator.decodePolylineString(logisticsPolyline);
print('Total route: \${calculator.calculateDistance(routePoints)} km');

3. Travel Planning ✈️

Estimate road trip distances:

final tripPlan = [start, stop1, stop2, destination];
print('Total trip: \${calculator.calculateDistance(tripPlan)} km');

4. IoT Tracking Devices 📡

Live tracking integration:

void onGpsUpdate(LatLng position) {
  calculator.addPoint(position);
  // Stream updates automatically
}