GeocodingService class

A geocoding service that caches reverse geocoding and place search results locally using Hive CE to reduce API calls.

Coordinates within GeocodeCacheOptions.cacheRadiusMeters of a previously resolved location are served from cache without hitting the geocoding API.

Usage

// Configure (optional)
GeocodingService.instance.configure(
  options: const GeocodeCacheOptions(cacheRadiusMeters: 15),
);

// Initialise once
await GeocodingService.instance.init();

// Use anywhere — caching is transparent
final address = await GeocodingService.instance
    .getAddressFromCoordinates(lat, lon);

Lifecycle

  1. Optionally call configure to set custom options.
  2. Call init once before using any other method.
  3. Call dispose when the service is no longer needed.

Properties

allCachedEntries → List<CachedGeocode>
Read-only list of all cached geocode entries.
no setter
cacheSize → int
Number of entries currently in the geocode cache.
no setter
hashCode → int
The hash code for this object.
no setterinherited
isInitialised → bool
Whether the service has been initialised and is ready to use.
no setter
options → GeocodeCacheOptions
The current configuration options.
no setter
placeSearchCacheSize → int
Number of entries currently in the place search cache.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

clearCache() → Future<void>
Removes all entries from both geocode and place search caches.
clearGeocodeCache() → Future<void>
Removes only geocode cache entries (preserves place search cache).
clearPlaceSearchCache() → Future<void>
Removes only place search cache entries (preserves geocode cache).
configure({GeocodeCacheOptions? options}) → void
Configures the service with custom options.
dispose() → Future<void>
Closes the underlying Hive boxes and resets the singleton instance.
evictEntriesOlderThan(Duration age) → Future<int>
Removes geocode cache entries older than age.
getAddressFromCoordinates(double latitude, double longitude) → Future<String?>
Returns a human-readable address for the given latitude / longitude.
init() → Future<void>
Initialises Hive and opens the cache boxes.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
searchPlaces(String query) → Future<List<Map<String, dynamic>>>
Searches for places matching query using Nominatim, with caching.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

instance → GeocodingService
Returns the singleton instance of GeocodingService.
no setter