gps_history 0.0.9

Represents histories of GPS points. Handles millions of points quickly and using relatively little memory. Can import Google location history JSON files.

GPS History for Dart

Module intended to represent recorded histories of GPS points recorded at a frequency >= 1 second. Features:

• Three types of GPS point: a lean one with just the bare minimums and one with more meta information such as heading, speed, etc. that's useful for GPX files for example. Additionally a point that represents a longer stay at a location, which can be used to reduce duplicate entries in a database.
• Different in-memory storage systems for GPS points: either simply list-based, or efficient binary representation of just 14 to 22 bytes per point (at the cost of small loss of accuracy that's below what GPS sensors provide anyway).
• Extremely low-memory and fast parser for Google location history JSON export. As a reference, a straighforward parser using the Dart JSON library on a ~500 MB history file takes about 2 GB of memory and on an Intel Core i7-8565U can produce about 140k points/s, while the custom parser takes almost no memory on top of the base memory use of the application and outputs points about 2.5x-3.5x faster. Parse Google location history on mobile devices without any worries about running out of RAM.
• Modular and extensible architecture: add your own points definitions, containers or persistence mechanisms.
• Many unit tests, examples, benchmarks and lots of documentation.
• Utility functions for dealing with time and distance.
• Null safety.
• Dependencies on third party libraries are limited to superficial functionality, and then only very mainstream well supported ones.

Example

Reading a JSON file containing location history exported from Google:

import 'dart:io';
import 'package:gps_history/gps_history.dart';
import 'package:gps_history/gps_history_convert.dart';

void main() async {
  final filename = 'data/g_history_sample.json';

  final file = File(filename);
  final gpsStays = GpcCompactGpsStay();

  final fileStream = file.openRead();

  final points = fileStream.transform(GoogleJsonHistoryDecoder(
      minSecondsBetweenDatapoints: 1, accuracyThreshold: 500));

  final stays = points.transform(
      PointsToStaysDecoder(maxTimeGapSeconds: 10, maxDistanceGapMeters: 10));

  await for (final s in stays) {
    gpsStays.add(s);
  }

  print('Read ${gpsStays.length} points');

  // Calculate with what frequency the points have been recorded.
  final intervals = <int>[];
  final durations = <int>[];
  final distances = <double>[];
  GpsStay? prevPoint;

  for (final s in gpsStays) {
    durations.add(s.endTime.difference(s.startTime));
    if (prevPoint != null) {
      final diff = s.time.difference(prevPoint.endTime);
      intervals.add(diff);

      final dist = distance(prevPoint, s);
      distances.add(dist);
    }
    prevPoint = s;
  }

  intervals.sort();
  durations.sort();
  distances.sort();

  if (intervals.isNotEmpty) {
    print('Intervals:');
    print('  min    = ${intervals[0]} s');
    print('  median = ${intervals[intervals.length ~/ 2]} s');
    print('  max    = ${intervals[intervals.length - 1]} s');
  }
  if (durations.isNotEmpty) {
    print('Durations:');
    print('  min    = ${durations[0]} s');
    print('  median = ${durations[durations.length ~/ 2]} s');
    print('  max    = ${durations[durations.length - 1]} s');
  }
  if (distances.isNotEmpty) {
    print('Distances:');
    print('  min    = ${distances[0]} m');
    print('  median = ${distances[distances.length ~/ 2]} m');
    print('  max    = ${distances[distances.length - 1]} m');
  }
}

Automatic master branch test state