Envoyou CEVS Aggregator API

The official backend API for the Envoyou platform. This service aggregates environmental data from multiple global sources to calculate a Composite Environmental Verification Score (CEVS), providing a standardized metric for corporate environmental performance.

📖 Overview

The CEVS Aggregator API acts as a robust data pipeline and scoring engine. It connects to various official data sources (e.g., EPA, EEA, ISO), normalizes the incoming data into a consistent schema, and applies a sophisticated scoring algorithm to generate the CEVS for a given company.

🌍 Project Summary

For detailed information on all Project, please refer to the official Project Summary.

✨ Key Features

✨ Key Features

• Multi-Source Data Aggregation: Integrates with key environmental data providers:
  • EPA (USA): Facility and power plant emissions data (Envirofacts, CAMPD).
  • EEA (Europe): Industrial pollution and renewable energy statistics.
  • EDGAR: Global urban emissions data.
  • ISO: ISO 14001 certification status (40+ certificates integrated).
  • Amdalnet (Indonesia): Environmental permits and approvals from KLHK (integrated with dev API).
• Composite Environmental Verification Score (CEVS): A proprietary scoring model that provides a holistic view of a company's environmental impact and commitment.
• Secure API Access: All critical endpoints are protected by API key authentication.
• Frontend Integration Ready: Pre-configured CORS for React/Vite applications with demo API keys.
• Real-time CEVS Scoring: Live calculation with comprehensive environmental data (score range: 0-100).
• Demo API Key System: Built-in endpoint for generating demo keys for frontend development.
• Comprehensive Permit Management: Full CRUD operations for environmental permits with search and filtering.
• Tier-Based Rate Limiting: Different usage tiers (Basic, Premium) to manage API load.
• Robust Caching: In-memory and file-based caching for improved performance and reduced external API calls.
• Standardized Data Schemas: All data is normalized into a clean, predictable format.
• Asynchronous Framework: Built with FastAPI for high performance and scalability.
• Dockerized: Ready for containerized deployment in any environment.

📚 API Documentation

For detailed information on all available endpoints, request/response formats, and usage examples, please refer to the official API Documentation.

🚀 Getting Started

Prerequisites

• Python 3.10+
• Docker & Docker Compose (Recommended)
• Node.js 18+ & npm (for frontend development)

1. Environment Setup

First, create a .env file from the example template:

cp .env.example .env

2. Installation

Install the required Python packages:

pip install -r requirements.txt

3. Running the Server

Local Development (with Uvicorn)

The server supports live reloading, which is ideal for development.

uvicorn app.api_server:app --reload --port 8000 --log-level debug

The API will be available at http://localhost:8000.

Production (with Docker)

Using Docker is the recommended way to run the application in production.

# Build and run the services in the background
docker-compose up --build -d

# Check the logs
docker-compose logs -f

# Stop the services
docker-compose down

🌐 Frontend Integration

React + Vite Setup

The API is designed to work seamlessly with modern frontend frameworks:

1. CORS Configuration: Pre-configured for local development with Vite (port 5173)
2. Demo API Keys: Built-in demo keys for frontend development
3. Real-time Data: Live CEVS scoring with 40+ ISO certificates integration

Example Frontend Integration

// vite.config.js
export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
})

Getting Demo API Key

// Frontend code example
const getDemoKey = async () => {
  const response = await fetch('/api/admin/request-demo-key', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ tier: 'premium' })
  });
  const data = await response.json();
  return data.api_key;
};

🌍 Amdalnet Integration

Indonesian Environmental Data

The API integrates with Amdalnet (KLHK - Kementerian Lingkungan Hidup dan Kehutanan) to provide real environmental permit data from Indonesia.

Available Endpoints

• SK Final: Environmental permits and approvals
• Pemrakarsa: Business entities with environmental permits
• Rencana Usaha: Business plans and activities
• Map Services: Geographic project boundaries

API Configuration

# Set your Amdalnet credentials in .env
AMDALNET_API_URL=https://amdalnet-dev.kemenlh.go.id
AMDALNET_API_KEY=your_token_here
AMDALNET_SSO_USERNAME=your_username
AMDALNET_SSO_PASSWORD=your_password

Getting API Access

1. Register at Amdalnet SSO
2. Login to get authentication token
3. Configure token in environment variables
4. Test integration with /permits endpoint

Example Usage

from app.clients.amdalnet_client import AmdalnetClient

# Initialize client
client = AmdalnetClient(api_key="your_token")

# Get environmental permits
permits = client.get_sk_final(page=1, limit=50)
print(f"Found {len(permits)} permits")

⚙️ Configuration

The application is configured via environment variables, which are loaded by pydantic-settings from the .env file. Key configuration options are defined in app/config.py.

• PORT: The port the server will run on.
• LOG_LEVEL: The logging level (e.g., DEBUG, INFO, WARNING).
• API_KEYS: A comma-separated list of valid API keys and their tiers.
• CAMPD_API_KEY: Your API key for the EPA CAMPD service.
• *_XLSX_PATH: Paths to local reference data files (EDGAR, ISO, Policy).

🧪 Running Tests

The project uses pytest for testing.

pytest

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

---

License

This project is released under the Business Source License 1.1 (BSL-1.1).

• Non-commercial use only.
• Will be automatically re-licensed to Apache 2.0 in 2028.
• See the LICENSE file for details.

Acknowledgements

• FastAPI
• Uvicorn
• Pydantic

Contact

Maintained by Husni Kusuma
🌐 Website: envoyou.com
📧 More info: info@envoyou.com

---

© 2025 Envoyou | All Rights Reserved

Empowering Global Environmental Transparency