diff --git a/server/EXTERNAL_API_IMPLEMENTATION.md b/server/EXTERNAL_API_IMPLEMENTATION.md index abe2b89..8324220 100644 --- a/server/EXTERNAL_API_IMPLEMENTATION.md +++ b/server/EXTERNAL_API_IMPLEMENTATION.md @@ -250,10 +250,15 @@ redis-cli ping # Should return PONG ``` ### To Implement EPA Water Quality -1. Research EPA Ireland API or data access methods -2. May require web scraping or manual data entry -3. Alternative: Use EU Bathing Water Quality database -4. Update `getWaterQualityData()` function +1. **Recommended:** Use EU Bathing Water Quality API (free, no key required) + - Endpoint: `https://www.eea.europa.eu/api/EMIS/get_bathing_water_data?country=IE` + - No authentication needed + - Covers all Irish designated bathing waters +2. Alternative: EPA Ireland GeoPortal (manual download or web scraping) +3. Alternative: Marine Institute Ireland data portal +4. Update `getWaterQualityData()` function in `externalDataService.ts` + +**Note:** No API key required for any water quality data source ### To Implement Beach Quality 1. Create static database of Irish beaches diff --git a/server/EXTERNAL_API_SETUP.md b/server/EXTERNAL_API_SETUP.md index 24eacb1..2b1a3a1 100644 --- a/server/EXTERNAL_API_SETUP.md +++ b/server/EXTERNAL_API_SETUP.md @@ -133,16 +133,69 @@ These APIs are not fully implemented yet but have placeholder endpoints: **Purpose:** Water quality monitoring data for Irish beaches and coastal areas. -**Source:** [EPA Ireland Open Data Portal](https://gis.epa.ie/EPAMaps/) +**Available Data Sources:** -**Status:** Placeholder implementation - returns mock data -**Cost:** Free (public data) -**API Key:** Not required +#### Option A: EU Bathing Water Quality (Recommended) +- **Source:** European Environment Agency +- **API:** https://www.eea.europa.eu/data-and-maps/data/bathing-water-directive-status-of-bathing-water +- **Cost:** Free, no API key required +- **Coverage:** All EU designated bathing waters including Ireland +- **Data Format:** CSV/XML downloads or REST API +- **Update Frequency:** Annual with in-season updates +- **Documentation:** https://www.eea.europa.eu/help/glossary/eea-glossary/bathing-water -**To Implement:** -- Research EPA's data access methods (may require web scraping or specific API) -- Contact EPA for API access if available -- Alternative: Use EU Bathing Water Quality data +**How to Access:** +1. Use EEA's REST API endpoint +2. Filter by country code "IE" for Ireland +3. Parse XML/JSON response +4. No authentication required + +**Example Endpoint:** +``` +https://www.eea.europa.eu/api/EMIS/get_bathing_water_data?country=IE +``` + +#### Option B: EPA Ireland GeoPortal +- **Source:** EPA Ireland +- **Portal:** https://gis.epa.ie/EPAMaps/ +- **Cost:** Free, no API key required +- **Method:** Web scraping or manual data download +- **Data:** Real-time and historical water quality data + +**Access Methods:** +1. **Manual Download:** Download datasets from EPA GeoPortal +2. **Web Scraping:** Parse EPA maps (requires permission) +3. **Contact EPA:** Request API access at info@epa.ie + +#### Option C: Marine Institute Ireland +- **Source:** Marine Institute +- **Portal:** https://data.marine.ie/ +- **Cost:** Free, no API key required +- **Data:** Marine water quality, oceanographic data +- **Format:** Various formats including API access + +**How to Access:** +1. Browse datasets at https://data.marine.ie/ +2. Use ERDDAP server for programmatic access +3. No API key required for public data + +#### Option D: Static Database (Simplest) +- **Method:** Create a database of Irish beaches with latest quality ratings +- **Source:** Manual entry from EPA/EU reports +- **Update:** Quarterly or annually +- **Pros:** Fast, reliable, no external dependencies +- **Cons:** Requires manual updates + +**Recommended Approach:** +Use **EU Bathing Water Quality API** (Option A) as it's: +- Free and public +- No API key required +- Covers all Irish beaches +- Regularly updated +- Easy to integrate + +**Status:** Placeholder implementation - needs integration with one of the above sources +**API Key:** Not required for any option --- diff --git a/server/WATER_QUALITY_INTEGRATION.md b/server/WATER_QUALITY_INTEGRATION.md new file mode 100644 index 0000000..2c3f938 --- /dev/null +++ b/server/WATER_QUALITY_INTEGRATION.md @@ -0,0 +1,252 @@ +# 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 => { + const cacheKey = `water-quality:${latitude.toFixed(4)}:${longitude.toFixed(4)}`; + + try { + // Check cache first + const cached = cache.get(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 = { + '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!