thrillwiki_laravel/memory-bank/services/GeocodeService.md

GeocodeService Documentation

Overview

The GeocodeService provides geocoding functionality through OpenStreetMap's Nominatim API, offering address lookup, reverse geocoding, and result caching capabilities.

Features

1. Address to Coordinates

• Forward geocoding (address to coordinates)
• Address normalization and validation
• Result confidence scoring
• Batch processing support

2. Coordinates to Address

• Reverse geocoding (coordinates to address)
• Multiple result handling
• Address component extraction
• Location type detection

3. Cache Management

• 24-hour TTL for results
• Cache invalidation strategy
• Memory optimization
• Cache warming support

4. Error Handling

• Rate limit management
• API error handling
• Validation failures
• Network timeouts

Implementation Details

Service Structure

class GeocodeService
{
    public function geocode(string $address): ?array
    public function reverseGeocode(float $lat, float $lon): ?array
    public function batchGeocode(array $addresses): array
    public function validateCoordinates(float $lat, float $lon): bool
    public function clearCache(?string $key = null): void
    public function warmCache(array $addresses): void
}

Cache Keys

• Forward geocoding: geocode:{normalized_address}
• Reverse geocoding: reverse:{lat},{lon}
• TTL: 24 hours (configurable)

API Integration

• Base URL: https://nominatim.openstreetmap.org
• Rate Limiting: Max 1 request per second
• User-Agent Required: "ThrillWiki Geocoder"
• Response Format: JSON

Validation Rules

• Latitude: -90 to 90
• Longitude: -180 to 180
• Address length: 5 to 200 characters
• Required fields: street or city + country

Usage Examples

Forward Geocoding

$geocoder = app(GeocodeService::class);
$result = $geocoder->geocode('123 Main St, City, Country');
// Returns: ['lat' => 12.34, 'lon' => 56.78, 'display_name' => '...', ...]

Reverse Geocoding

$geocoder = app(GeocodeService::class);
$result = $geocoder->reverseGeocode(12.34, 56.78);
// Returns: ['address' => [...], 'display_name' => '...', ...]

Batch Processing

$geocoder = app(GeocodeService::class);
$results = $geocoder->batchGeocode(['address1', 'address2']);
// Returns: ['address1' => [...], 'address2' => [...]]

Error Handling

Exception Types

1. GeocodingException
   • Invalid input
   • API errors
   • Rate limiting
2. ValidationException
   • Invalid coordinates
   • Invalid address format
3. CacheException
   • Cache access errors
   • Invalid cache data

Error Responses

try {
    $result = $geocoder->geocode($address);
} catch (GeocodingException $e) {
    // Handle geocoding errors
} catch (ValidationException $e) {
    // Handle validation errors
}

Performance Optimization

Cache Strategy

1. Cache all successful results
2. Implement cache warming for common addresses
3. Use cache tags for better management
4. Regular cache cleanup

Batch Processing

1. Group requests when possible
2. Respect rate limits
3. Parallel processing for large batches
4. Error handling per item

Integration Points

1. Location Model

• Automatic geocoding on address changes
• Cache management for stored locations
• Coordinate validation

2. HasLocation Trait

• Geocoding helpers
• Address formatting
• Location type handling

3. Components

• Address search interface
• Map display
• Location selection

Testing Strategy

Unit Tests

• Address validation
• Coordinate validation
• Cache management
• Error handling

Integration Tests

• API communication
• Cache interaction
• Batch processing
• Rate limiting

Performance Tests

• Cache efficiency
• Memory usage
• Response times
• Batch processing speed