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`:

```yaml
dependencies:
  rugreefer:
    git:
      url: https://github.com/TheRandonauts/rugreefer.git
```

Then, run:
```sh
flutter pub get
```

## Usage

### **Basic Example**
```dart
import 'package:rugreefer/rugreefer.dart';

void main() async {
  final lookup = GeoMetadataLookup(
    apiUrl: 'http://localhost:8000/get_geodata/?format=geojson&geohash=',
    enableCacheExpiration: true,
  );

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

### **Custom Cache Settings**
```dart
final lookup = GeoMetadataLookup(
  apiUrl: 'http://your-api.com/get_geodata/?format=geojson&geohash=',
  enableCacheExpiration: true,
  cacheExpirationDuration: Duration(days: 7),
);
```

## API Reference

### **`GeoMetadataLookup` Constructor**
```dart
GeoMetadataLookup({
  required String apiUrl,
  bool enableCacheExpiration = false,
  Duration cacheExpirationDuration = const Duration(days: 14),
});
```

### **Methods**
#### **`lookup(double latitude, double longitude, {double distanceThreshold = 10.0})`**
- Fetches and processes metadata for a given coordinate.
- **Returns:** `Future<List<Map<String, dynamic>>>`

#### **`enableCacheExpiration` (bool)**
- Enables or disables automatic cache cleanup.

#### **`cacheExpirationDuration` (Duration)**
- Specifies how long cached files are kept before deletion.

## Changes in Data Handling
- The library now ensures compatibility with **Point** instead of **Position** for `booleanPointInPolygon` and `_isPointNearLine`.
- Web caching uses `SharedPreferences`, while file-based caching is used on other platforms.
- `lookup()` internally converts coordinates into `Point(coordinates: [longitude, latitude])`.

## Author
[@randogoth](https://github.com/randogoth)