rugreefer/README.md

Rugreefer

Rugreefer is a Dart library for retrieving metadata about geographic coordinates from a dopecarpet server. It converts coordinates into a geohash, fetches a gzipped GeoJSON file from the API, and extracts relevant spatial data such as polygons and lines. The library also supports caching with optional expiration to improve performance.

Features

• Converts latitude/longitude to geohash (precision: 4 characters)
• Fetches GeoJSON files from a remote API
• Extracts relevant metadata from polygons and lines
• Supports caching for performance optimization
• Optional cache expiration (default: 14 days)
• Works in Flutter (mobile, desktop, web)

Installation

Add rugreefer to your pubspec.yaml:

dependencies:
  rugreefer:
    git:
      url: https://github.com/randogoth/rugreefer.git

Then, run:

flutter pub get

Usage

Basic Example

To create an instance of RugReefer, provide the required parameters:

import 'package:rugreefer/rugreefer.dart';

void main() async {
  final rugReefer = RugReefer(
  apiUrl: 'https://example.com/api', // API endpoint for geospatial data
  categoryMap: 'assets/categories.json', // Path to the JSON asset for category mapping
  enableCacheExpiration: true, // Optional: Enable cache expiration (default: false)
  cacheExpirationDuration: Duration(days: 14), // Optional: Cache expiration duration (default: 14 days)
  cacheSizeThreshold: 20 * 1024 * 1024, // Optional: Cache size threshold in bytes (default: 20MB)
);

  final results = await rugReefer.lookup(30.5735040, 34.453125);
  print(results);
}

Example Output:

[
  {
    "in": {
      "bush": ["scrub"],
      "forest": ["forest"]
    }
  },
  {
    "by": {
      "water": ["stream"]
    }
  }
]

Available Methods

1. Lookup Metadata

Perform a geospatial metadata lookup for a given latitude and longitude.

Future<Map<String, Map<String, List<String>>>> lookup(
  double latitude,
  double longitude, {
  double distanceThreshold = 10.0, // Optional: Distance threshold in meters (default: 10.0)
});

Example:

final metadata = await rugReefer.lookup(37.7749, -122.4194);
print(metadata);

---

2. Get Current Cache Size

Get the total size of the cache in bytes.

Future<int> getCurrentCacheSize();

Example:

final cacheSize = await rugReefer.getCurrentCacheSize();
print("Cache size: ${cacheSize / 1024 / 1024} MB");

---

3. List Cached Files

List all currently cached files with their sizes and last access times.

Future<List<Map<String, dynamic>>> listCachedFiles();

Example:

final cachedFiles = await rugReefer.listCachedFiles();
for (var file in cachedFiles) {
  print("File: ${file['file']}, Size: ${file['size']} bytes, Last Access: ${file['lastAccess']}");
}

---

4. Delete a Specific Cached File

Delete a specific cached file by its geohash.

Future<void> deleteCachedFile(String geohash);

Example:

await rugReefer.deleteCachedFile('u4pru');

---

5. Clear the Entire Cache

Delete all cached files and remove their last access times.

Future<void> clearCache();

Example:

await rugReefer.clearCache();

Author

@randogoth