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

{
  "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:

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:

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:

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:

{
  "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!