ocean-cleanup/server/WATER_QUALITY_INTEGRATION.md

# Water Quality Data Integration Guide

## Overview

EPA Ireland water quality data is publicly available but doesn't have a traditional REST API with keys. This guide explains how to integrate real water quality data.

## No API Key Required! 🎉

Unlike weather APIs, water quality data from EPA Ireland and EU sources is completely free and requires **no API key or authentication**.

## Recommended Approach: EU Bathing Water Quality API

### Why This Option?
- ✅ Free and public
- ✅ No API key or registration required
- ✅ Covers all Irish designated bathing waters
- ✅ Regularly updated (annual + in-season)
- ✅ Standardized EU-wide data format
- ✅ Easy to integrate

### Data Source
**European Environment Agency (EEA)**
- Website: https://www.eea.europa.eu/
- Data Portal: https://www.eea.europa.eu/data-and-maps/data/bathing-water-directive-status-of-bathing-water

### API Endpoints

#### Get All Irish Bathing Waters
```
GET https://www.eea.europa.eu/api/EMIS/get_bathing_water_data?country=IE
```

#### Response Format
```json
{
  "bathingWaters": [
    {
      "id": "IEWEBW_0100_01_0000",
      "name": "Sandymount Strand",
      "latitude": 53.3333,
      "longitude": -6.2167,
      "classification": "Excellent",
      "year": 2024,
      "region": "Dublin",
      "parameters": {
        "ecoli": 250,
        "enterococci": 100
      }
    }
  ]
}
```

### Water Quality Classifications
- **Excellent** - Highest quality, safe for swimming
- **Good** - Good quality, safe for swimming
- **Sufficient** - Acceptable quality, generally safe
- **Poor** - Below standards, swimming not recommended

### Implementation Steps

1. **Update `externalDataService.ts`:**

```typescript
export const getWaterQualityData = async (
  latitude: number,
  longitude: number
): Promise<WaterQualityData | null> => {
  const cacheKey = `water-quality:${latitude.toFixed(4)}:${longitude.toFixed(4)}`;

  try {
    // Check cache first
    const cached = cache.get<WaterQualityData>(cacheKey);
    if (cached) {
      console.log('Water quality data retrieved from cache');
      return cached;
    }

    // Fetch all Irish bathing waters from EU API
    const response = await axios.get(
      'https://www.eea.europa.eu/api/EMIS/get_bathing_water_data',
      {
        params: {
          country: 'IE',
          year: new Date().getFullYear(),
        },
        timeout: 10000,
      }
    );

    // Find nearest bathing water to given coordinates
    const bathingWaters = response.data.bathingWaters || [];
    const nearest = findNearestBathingWater(bathingWaters, latitude, longitude);

    if (!nearest) {
      return null;
    }

    // Map EU classification to our format
    const statusMap: Record<string, WaterQualityData['status']> = {
      'Excellent': 'excellent',
      'Good': 'good',
      'Sufficient': 'sufficient',
      'Poor': 'poor',
    };

    const waterQualityData: WaterQualityData = {
      status: statusMap[nearest.classification] || 'unknown',
      lastSampled: nearest.lastSampleDate,
      parameters: {
        ecoli: nearest.parameters?.ecoli,
        enterococci: nearest.parameters?.enterococci,
      },
      source: 'European Environment Agency',
      timestamp: new Date().toISOString(),
    };

    // Cache for 6 hours
    cache.set(cacheKey, waterQualityData, CACHE_EXPIRATION);

    return waterQualityData;
  } catch (error) {
    console.error('Error fetching water quality data:', error);
    return null;
  }
};

function findNearestBathingWater(
  bathingWaters: any[],
  latitude: number,
  longitude: number
): any | null {
  let nearest = null;
  let minDistance = Number.MAX_VALUE;

  for (const water of bathingWaters) {
    const distance = calculateDistance(
      latitude,
      longitude,
      water.latitude,
      water.longitude
    );

    // Only consider bathing waters within 10km
    if (distance < minDistance && distance < 10) {
      minDistance = distance;
      nearest = water;
    }
  }

  return nearest;
}
```

2. **Test the Integration:**

```bash
curl http://localhost:3005/api/external/water-quality/53.3498/-6.2603
```

## Alternative: EPA Ireland Direct Data

### Option 1: EPA GeoPortal Downloads
1. Visit https://gis.epa.ie/EPAMaps/
2. Navigate to "Water" section
3. Download bathing water quality datasets
4. Import into your database
5. Query locally (no external API calls)

### Option 2: Marine Institute Ireland
1. Visit https://data.marine.ie/
2. Browse water quality datasets
3. Use ERDDAP server for programmatic access
4. Example: `https://erddap.marine.ie/erddap/tabledap/IWBNetwork.json`

### Option 3: Static Database
Create a static database of Irish beaches:

```typescript
const IRISH_BEACHES = [
  {
    name: 'Sandymount Strand',
    latitude: 53.3333,
    longitude: -6.2167,
    status: 'excellent',
    lastSampled: '2024-08-15',
  },
  {
    name: 'Dollymount Strand',
    latitude: 53.3667,
    longitude: -6.1667,
    status: 'good',
    lastSampled: '2024-08-15',
  },
  // Add more beaches...
];
```

## Data Update Frequency

### EU Bathing Water Quality
- **Annual Classification:** Published each May for previous season
- **In-Season Updates:** Weekly during bathing season (June-September)
- **Historical Data:** Available for past years

### Recommended Cache Duration
- **6 hours** during bathing season (June-September)
- **24 hours** outside bathing season
- **1 week** for historical/annual classifications

## Testing Without Real Data

The current placeholder implementation returns:
```json
{
  "status": "unknown",
  "source": "EPA Ireland",
  "timestamp": "2024-11-16T23:30:00.000Z"
}
```

This allows the frontend to work while you implement the real integration.

## Cost & Rate Limits

- **Cost:** $0 (completely free)
- **Rate Limits:** None specified (reasonable use expected)
- **Authentication:** Not required
- **API Key:** Not required

## Implementation Priority

**Low Priority** - The placeholder works fine for MVP. Real data integration can be added later when:
1. You have more users requesting this feature
2. You want to differentiate from competitors
3. You're ready to maintain the integration

## Support & Resources

- **EEA Contact:** https://www.eea.europa.eu/en/contact-us
- **EPA Ireland:** info@epa.ie
- **Marine Institute:** data@marine.ie

## Summary

✅ No API key required
✅ Free public data available
✅ Multiple integration options
✅ Current placeholder works for MVP
⏳ Real integration can be added anytime

The water quality integration is **optional** and can be implemented when needed. The system works perfectly without it!