Add CAMPD integration with new endpoint and client for emissions and compliance data

Author: hk-dev13

API_DOCUMENTATION.md

@@ -245,6 +245,19 @@ Returns EDGAR urban emissions data with trend analysis.
 - `pollutant` (optional): Pollutant type (default: "PM2.5")  
 - `window` (optional): Trend analysis window in years (default: 3)
 
+## Endpoint Data Global
+
+### GET /global/campd
+
+Mengekspos data mentah dari API CAMPD untuk fasilitas tertentu.
+
+**Parameter Kueri:**
+- `facility_id` (integer, wajib): ID fasilitas dari CAMPD.
+
+**Contoh Permintaan:**
+```bash
+curl -X GET "http://localhost:5000/global/campd?facility_id=12345"
+
 #### 8. CEVS Composite Score
 **GET** `/global/cevs/<company>`
 

README.md

@@ -213,6 +213,13 @@ Documentation
 - ISO: CSV/JSON and Excel list (ISO_CSV_URL, ISO_XLSX_PATH)
 - EDGAR: UCDB Excel aggregated per country-year (set EDGAR_XLSX_PATH or place file at `reference/EDGAR_emiss_on_UCDB_2024.xlsx`)
 
+## Integrasi Data CAMPD
+
+Proyek ini terintegrasi dengan [Clean Air Markets Program Data (CAMPD)](https://www.epa.gov/airmarkets) untuk memperkaya Skor Verifikasi Lingkungan Komprehensif (CEVS) dengan data emisi dan kepatuhan dari pembangkit listrik di AS.
+
+### Konfigurasi
+
+Untuk mengaktifkan integrasi ini, Anda memerlukan API key dari CAMPD. Tambahkan kunci Anda ke file `.env` Anda:
 CEVS pollution trend source selection: set `CEVS_POLLUTION_SOURCE` to `auto` (default), `eea`, or `edgar`.
 
 ## ✅ Current Status

api/clients/campd_client.py

@@ -0,0 +1,60 @@
+import os
+import requests
+from dotenv import load_dotenv
+
+load_dotenv()
+
+class CAMDClient:
+    """
+    Client for interacting with the Clean Air Markets Program Data (CAMPD) API.
+    This client manages requests and authentication using a dedicated API key.
+    """
+    def __init__(self):
+        self.api_key = os.getenv("CAMPD_API_KEY")
+        if not self.api_key:
+            raise ValueError("CAMPD_API_KEY environment variable not set.")
+        self.base_url = "https://api.epa.gov/easey"
+
+    def get_emissions_data(self, facility_id):
+        """
+        Retrieves emissions data for a specific facility.
+
+        Args:
+            facility_id (int): The ID of the facility to retrieve data for.
+
+        Returns:
+            dict: A dictionary containing the emissions data, or None if the request fails.
+        """
+        endpoint = f"/api/v2/facilities/{facility_id}/emissions"
+        headers = {
+            "x-api-key": self.api_key
+        }
+        try:
+            response = requests.get(f"{self.base_url}{endpoint}", headers=headers)
+            response.raise_for_status()  # Raise an exception for bad status codes
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            print(f"Error fetching emissions data from CAMPD: {e}")
+            return None
+
+    def get_compliance_data(self, facility_id):
+        """
+        Retrieves compliance data for a specific facility.
+
+        Args:
+            facility_id (int): The ID of the facility to retrieve data for.
+
+        Returns:
+            dict: A dictionary containing the compliance data, or None if the request fails.
+        """
+        endpoint = f"/api/v2/facilities/{facility_id}/compliance"
+        headers = {
+            "x-api-key": self.api_key
+        }
+        try:
+            response = requests.get(f"{self.base_url}{endpoint}", headers=headers)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            print(f"Error fetching compliance data from CAMPD: {e}")
+            return None

api/routes/global_data.py

@@ -12,6 +12,8 @@
 from api.clients.iso_client import ISOClient
 from api.clients.eea_client import EEAClient
 from api.clients.edgar_client import EDGARClient
+# --- PERUBAHAN 1: Impor CAMDClient ---
+from api.clients.campd_client import CAMDClient
 from api.services.cevs_aggregator import compute_cevs_for_company
 
 
@@ -365,5 +367,66 @@ def global_cevs(company_name: str):
 		logger.error(f"Error in /global/cevs/{company_name}: {e}")
 		return jsonify({"status": "error", "message": str(e)}), 500
 
+# --- PERUBAHAN 2: Tambahkan endpoint baru untuk CAMPD ---
+@global_bp.route('/global/campd', methods=['GET'])
+@swag_from({
+    'tags': ['Global Data'],
+    'summary': 'Get Raw CAMPD Data',
+    'description': 'Retrieves raw emissions and compliance data from the CAMPD API for a given facility. Requires API key authentication.',
+    'security': [{'ApiKeyAuth': []}],
+    'parameters': [
+        {
+            'name': 'facility_id',
+            'in': 'query',
+            'type': 'integer',
+            'required': True,
+            'description': 'The facility ID from CAMPD (e.g., 7 for Tennessee Valley Authority).',
+            'example': 7
+        }
+    ],
+    'responses': {
+        200: {
+            'description': 'Successful response with CAMPD data.',
+            'schema': {
+                'type': 'object',
+                'properties': {
+                    'status': {'type': 'string'},
+                    'emissions': {'type': 'object'},
+                    'compliance': {'type': 'object'}
+                }
+            }
+        },
+        400: {
+            'description': 'Missing or invalid facility_id parameter.'
+        },
+        500: {
+            'description': 'Error fetching data from CAMPD API.'
+        }
+    }
+})
+def get_campd_data():
+    """
+    Endpoint to retrieve raw data from the CAMPD API for a given facility.
+    """
+    facility_id_str = request.args.get('facility_id')
+    if not facility_id_str or not facility_id_str.isdigit():
+        return jsonify({"status": "error", "message": "A valid facility_id parameter is required"}), 400
+
+    try:
+        facility_id = int(facility_id_str)
+        client = CAMDClient()
+        emissions = client.get_emissions_data(facility_id)
+        compliance = client.get_compliance_data(facility_id)
+        
+        return jsonify({
+            "status": "success",
+            "emissions": emissions,
+            "compliance": compliance,
+            "retrieved_at": datetime.now().isoformat(),
+        })
+    except Exception as e:
+        logger.error(f"Error in /global/campd: {e}")
+        return jsonify({"status": "error", "message": str(e)}), 500
+
 
 __all__ = ["global_bp"]

api/services/cevs_aggregator.py

@@ -8,6 +8,8 @@
 from api.clients.iso_client import ISOClient
 from api.clients.eea_client import EEAClient
 from api.clients.edgar_client import EDGARClient
+# --- PERUBAHAN 1: Impor CAMDClient ---
+from api.clients.campd_client import CAMDClient
 from api.utils.policy import load_best_practices, practices_for_country
 
 logger = logging.getLogger(__name__)
@@ -25,9 +27,23 @@ def compute_cevs_for_company(company_name: str, *, company_country: Optional[str
       - +30 if company has ISO 14001 certification
       - - up to 30 penalty based on EPA results count in the company's state (proxy via name contains)
       - + up to 20 boost for EEA indicator improvements (placeholder)
+      - - up to 50 penalty based on CAMPD emissions and compliance data
     """
     company_key = _normalize_name(company_name)
 
+    # --- PERUBAHAN 2: Inisialisasi CAMDClient ---
+    campd_client = CAMDClient()
+    
+    # Placeholder untuk pemetaan nama perusahaan ke ID fasilitas CAMPD.
+    # Dalam implementasi nyata, Anda memerlukan cara yang lebih dinamis untuk mendapatkan ini.
+    facility_id_map = {
+        "example power plant inc.": 12345,
+        "tennessee valley authority": 7, # Contoh nyata
+        "southern company": 553, # Contoh nyata
+    }
+    facility_id = facility_id_map.get(company_key)
+
+
     # EPA: use permits data normalized list, then filter by company name
     epa_client = EPAClient()
     # Try a short-timeout EPA fetch for responsiveness
@@ -72,7 +88,9 @@ def compute_cevs_for_company(company_name: str, *, company_country: Optional[str
         "epa_penalty": 0.0,
         "renewables_bonus": 0.0,
         "pollution_penalty": 0.0,
-    "policy_bonus": 0.0,
+        "policy_bonus": 0.0,
+        # --- PERUBAHAN 3: Tambahkan komponen baru untuk CAMPD ---
+        "campd_penalty": 0.0,
     }
 
     if has_iso:
@@ -186,6 +204,49 @@ def slope_for(key: str) -> Dict[str, Any]:
     components["policy_bonus"] = policy_bonus
     score += policy_bonus
 
+    # --- PERUBAHAN 4: Logika penskoran untuk data CAMPD ---
+    campd_penalty = 0.0
+    campd_details = {}
+    if facility_id:
+        try:
+            emissions_data = campd_client.get_emissions_data(facility_id)
+            compliance_data = campd_client.get_compliance_data(facility_id)
+            
+            # Logika penalti emisi (contoh sederhana)
+            # Penalti berdasarkan total emisi CO2, SO2, dan NOx
+            # Anda harus menyesuaikan ambang batas ini
+            emissions_penalty = 0
+            if emissions_data:
+                total_co2 = sum(d.get('co2Mass', 0) for d in emissions_data)
+                total_so2 = sum(d.get('so2Mass', 0) for d in emissions_data)
+                total_nox = sum(d.get('noxMass', 0) for d in emissions_data)
+                
+                if total_co2 > 5000000: emissions_penalty += 10
+                if total_so2 > 1000: emissions_penalty += 5
+                if total_nox > 1000: emissions_penalty += 5
+            
+            # Logika penalti kepatuhan
+            # Penalti 20 poin jika ada satu saja indikator tidak patuh
+            compliance_penalty = 0
+            if compliance_data:
+                is_compliant = all(d.get('compliantIndicator', 1) == 1 for d in compliance_data)
+                if not is_compliant:
+                    compliance_penalty = 20
+
+            campd_penalty = min(40.0, emissions_penalty + compliance_penalty) # Batasi penalti maksimal
+            campd_details = {
+                "facility_id": facility_id,
+                "emissions_penalty": emissions_penalty,
+                "compliance_penalty": compliance_penalty,
+                "total_penalty": campd_penalty
+            }
+
+        except Exception as e:
+            logger.warning(f"Gagal mengambil atau memproses data CAMPD untuk facility_id {facility_id}: {e}")
+
+    components["campd_penalty"] = -campd_penalty
+    score -= campd_penalty
+    
     # Clamp score to [0, 100]
     score = max(0.0, min(100.0, score))
 
@@ -209,5 +270,7 @@ def slope_for(key: str) -> Dict[str, Any]:
             "renewables": {"country_row": renew_row, "eu_row": eu_row, "bonus_calc": renew_details},
             "pollution_trend": pol_details or pol_trend,
             "policy": policy_details,
+            # --- PERUBAHAN 5: Tambahkan detail CAMPD ke output ---
+            "campd": campd_details,
         },
     }