# Changelog - GeolocPlugin - Sébastien Siegrist

## Latest (v2.1)

**Enhancements:**

- Added explicit `distanceField` and `durationField` parameters to `@RouteCalculation` annotation
- Added `autoCalculate` parameter for automatic route calculation on save
- Supports both explicit field specification and automatic detection (backward compatible)
- Added 3 new geocoding providers: **Google Maps**, **HERE**, and **Mapbox** for address search
- Added configurable rate limiting for geocoding requests with `GEOLOC_GEOCODING_DELAY`

**New Features:**

**New Geocoding Providers:**

The plugin now supports 6 geocoding providers for address search:

- ✅ **Nominatim** (free, 1 req/sec) - Default
- ✅ **LocationIQ** (5,000 req/day free)
- ✅ **OpenRouteService** (2,500 req/day free)
- 🆕 **Google Maps** (pay-as-you-go, excellent quality)
- 🆕 **HERE** (250,000 req/month free, excellent quality)
- 🆕 **Mapbox** (100,000 req/month free, excellent quality)

Configuration example:

```bash
GEOLOC_GEOCODING_PROVIDER=googlemaps  # or 'here' or 'mapbox'
GOOGLE_MAPS_API_KEY=your-api-key
```

**Configurable Rate Limiting:**

You can now control the delay between geocoding requests for all providers:

```bash
# Default: 1000ms (1 second) - respects Nominatim usage policy
GEOLOC_GEOCODING_DELAY=1000

# Examples:
GEOLOC_GEOCODING_DELAY=500   # 2 requests per second
GEOLOC_GEOCODING_DELAY=200   # 5 requests per second
GEOLOC_GEOCODING_DELAY=0     # No rate limiting (for paid APIs)
```

This is useful when:

- Using paid APIs (Google Maps, HERE, Mapbox) with higher rate limits
- Running your own Nominatim instance with custom policies
- Testing and development scenarios

**Automatic Route Calculation:** Routes are now automatically calculated when coordinates change, eliminating the need to manually click "Calculate Route":

```cds
@RouteCalculation: {
  from: 'startingPointCoordinates',
  to: 'endingPointCoordinates',
  mode: 'transportMode',
  distanceField: 'distance',
  durationField: 'duration',
  autoCalculate: true  // NEW: Auto-calculate on CREATE/UPDATE
}
distance : Decimal(10, 2);
duration : String;
```

**How it works:**

- On CREATE: If both `from` and `to` coordinates are present, route is calculated automatically
- On UPDATE: If `from` or `to` coordinates change, route is recalculated automatically
- Non-blocking: If calculation fails, the save operation continues
- Manual calculation button remains available

## v1.0 - v2.0

Users need to:

1. Annotate fields with `@AddressSearch: true`
2. Include the `AddressSuggestions` entity via `using { geoloc.plugin } from 'geoloc-plugin/cds/address-suggestions-mixin'`
3. Declare actions in the CDS service

### 🔮 Future Roadmap

- Automatic generation of actions in CSN
- Support for additional providers (on request)

---