# Rugreefer
Rugreefer is a Dart library for retrieving metadata about geographic coordinates from a [dopecarpet](http://github.com/randogoth/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/randogoth/rugreefer.git
```
Then, run:
```sh
flutter pub get
```
## Usage
### Basic Example
To create an instance of `RugReefer`, provide the required parameters:
```dart
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:
```json
[
{
"in": {
"bush": ["scrub"],
"forest": ["forest"]
}
},
{
"by": {
"water": ["stream"]
}
}
]
```
## Available Methods
### 1. Lookup Metadata
Perform a geospatial metadata lookup for a given latitude and longitude.
```dart
Future>>> lookup(
double latitude,
double longitude, {
double distanceThreshold = 10.0, // Optional: Distance threshold in meters (default: 10.0)
});
```
Example:
```dart
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.
```dart
Future getCurrentCacheSize();
```
Example:
```dart
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.
```dart
Future>> listCachedFiles();
```
Example:
```dart
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.
```dart
Future deleteCachedFile(String geohash);
```
Example:
```dart
await rugReefer.deleteCachedFile('u4pru');
```
---
### 5. Clear the Entire Cache
Delete all cached files and remove their last access times.
```dart
Future clearCache();
```
Example:
```dart
await rugReefer.clearCache();
```
## Author
[@randogoth](https://github.com/randogoth)