API Documentation¶

Overview¶

The EEMT suite provides multiple interfaces for workflow execution and data processing. This documentation covers the REST API, web interface, command-line tools, and Python modules.

API Interfaces¶

🌐 REST API Endpoints¶

Complete reference for the FastAPI-based REST interface: - Job submission and management - Status monitoring - Results retrieval - Health checks and metrics

📊 Web Interface¶

Browser-based interface for workflow management: - Interactive job submission forms - Real-time progress monitoring - Result visualization and downloads - Multi-user support

🔧 Workflow Parameters¶

Comprehensive parameter documentation: - Solar radiation parameters - EEMT calculation options - Climate data settings - Performance tuning

💻 Command Line Interface¶

Direct workflow execution via command line: - Python workflow scripts - Shell script utilities - Batch processing options

🐍 Python Modules¶

Programmatic access to EEMT functions: - Core calculation functions - Data I/O utilities - Visualization tools - Custom workflow development

Quick Start Examples¶

REST API¶

# Submit a solar radiation job
curl -X POST "http://localhost:5000/api/jobs" \
  -F "workflow_type=sol" \
  -F "dem_file=@your_dem.tif" \
  -F "parameters={\"step\": 15, \"num_threads\": 4}"

# Check job status
curl "http://localhost:5000/api/jobs/JOB_ID/status"

# Download results
curl -O "http://localhost:5000/api/jobs/JOB_ID/download"

Python SDK¶

from eemt import EEMTClient

# Initialize client
client = EEMTClient(base_url="http://localhost:5000")

# Submit job
job_id = client.submit_job(
    workflow_type="eemt",
    dem_file="path/to/dem.tif",
    parameters={
        "start_year": 2020,
        "end_year": 2022,
        "step": 15
    }
)

# Monitor progress
status = client.get_job_status(job_id)
print(f"Progress: {status.progress}%")

# Download results
client.download_results(job_id, output_dir="./results")

Command Line¶

# Run solar radiation workflow
python /opt/eemt/sol/run-workflow \
  --dem input_dem.tif \
  --output ./output \
  --step 15 \
  --num-threads 8

# Run full EEMT analysis
python /opt/eemt/eemt/run-workflow \
  --dem input_dem.tif \
  --output ./output \
  --start-year 2020 \
  --end-year 2022 \
  --step 15

API Features¶

Authentication & Security¶

• API key authentication (optional)
• Rate limiting and quotas
• HTTPS support
• CORS configuration

Job Management¶

• Asynchronous job submission
• Queue management
• Priority scheduling
• Resource allocation

Data Handling¶

• Large file uploads (chunked)
• Streaming downloads
• Compression support
• Format conversion

Monitoring & Metrics¶

• Real-time progress tracking
• Resource usage statistics
• Error logging and debugging
• Performance metrics

Response Formats¶

Standard Response Structure¶

{
  "status": "success",
  "data": {
    // Response data
  },
  "message": "Operation completed successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response¶

{
  "status": "error",
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Step value must be between 1 and 30",
    "details": {
      "parameter": "step",
      "provided_value": 45,
      "allowed_range": [1, 30]
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Job Status Response¶

{
  "job_id": "20240115-103000-abc123",
  "status": "running",
  "progress": 45,
  "current_task": "Processing day 165 of 365",
  "started_at": "2024-01-15T10:30:00Z",
  "estimated_completion": "2024-01-15T11:30:00Z",
  "resources": {
    "cpu_usage": 85,
    "memory_usage": 4.2,
    "disk_usage": 12.5
  }
}

Rate Limits¶

Versioning¶

The API follows semantic versioning:

• Current Version: v1.0
• Base URL: /api/v1/
• Deprecation Policy: 6 months notice
• Backwards Compatibility: Maintained within major versions

API Clients¶

Official client libraries:

• Python: pip install eemt-client
• JavaScript: npm install @eemt/client
• R: install.packages("eemtr")

Community clients:

• Julia Client
• MATLAB Interface

OpenAPI Specification¶

The complete OpenAPI 3.0 specification is available at:

• JSON: /api/openapi.json
• YAML: /api/openapi.yaml
• Interactive Docs: /api/docs (Swagger UI)
• ReDoc: /api/redoc

Support¶

For API support:

1. Check the FAQ
2. Review Examples
3. Post on Discussions
4. Report Issues

For installation instructions, see Installation Guide. For workflow details, see Workflows Documentation.